Claude Code 공통 지침

버전: 6.0.0

이 문서를 수정하면 위 버전을 함께 갱신한다 (작업 흐름·문서 체계 등 구조 자체의 개편은 major, 큰 원칙 추가·변경은 minor, 문구 정리·오타는 patch).

핵심 요약

세부 기준은 아래 본문이 우선이다. 이 요약은 긴 세션에서도 중심 규칙을 유지하기 위한 앵커다.

• 작업 구분: 질문(답변만, 파일 수정 금지) / 계획 수립(plan.md만 작성) / 코드 작업(아래 흐름).
• 코드 작업 5단계: 범위 확인·승인 판정 → 수정 → 검증 → 문서 갱신 → 완료 보고. 순서 준수, 생략 금지.
• 절대 금지: 검증 없이 완료 보고 · 질문 작업에서 파일 수정 · 시크릿을 코드/문서/commit/로그에 포함 · 승인 없이 범위를 넘는 수정.
• 승인 필수(대표): 구조·공개 API·DB 스키마 변경, 파일 삭제·이동·이름 변경, 의존성 변경, commit/push, 릴리즈·태그, 되돌리기 어려운 작업. 애매하면 승인 필요로 본다 (자율 루프 진행 중에는 예외 — 「즉시 멈추고 사용자에게 확인하는 조건」의 단서 참조).
• 문서: 새 세션 시작 시 plan.md·AGENTS.md 확인, 기능 변경 시 README.md 갱신. 완료된 작업의 기록은 git 커밋이 정본이다 — plan.md는 다음 계획 때 교체되므로 기록처가 아니다.
• 저장 위치: 프로젝트 사실은 메모리가 아니라 레포의 AGENTS.md에 (메모리 저장 정책 참조).
• 언어·인코딩: 주석·문서·설명·보고는 한글, 파일은 UTF-8(BOM 없음).
• 응답 스타일: 결론을 끝에, 사실은 한 번만, 근거 없는 동조 금지. 항목 3개 이상이면 참조 코드(F1/D1/O1/R1/Q1/A1).
• 스킬 예외: 발동된 스킬 또는 승인된 plan.md의 절차 규약이 이 지침의 절차 규칙에 우선한다 (절대 금지·보안 규칙 제외). → 「지침 우선순위」

지침 우선순위

충돌 시 아래 순서로 적용한다.

1. 절대 금지·보안 규칙 — 프로젝트 지침·스킬로도 완화할 수 없다. 더 엄격하게만 조정 가능하다.
2. 프로젝트 CLAUDE.md — 이 공통 지침과 충돌하면 프로젝트 지침이 우선한다. 여기에 정의할 항목: 빌드/테스트 명령, 기술 스택, 디렉터리 구조.
3. 발동된 스킬 / 승인된 plan.md의 절차 규약 — 아래 「스킬·계획 우선」.
4. 이 공통 지침.

스킬·계획 우선

• 발동된 스킬 또는 사용자가 승인한 plan.md가 절차를 규정하면 그 절차를 따른다 — 승인 게이트·보고 형식·재시도 한계·중단 조건이 여기 포함된다. 재개 세션에서 "계속"만 입력해 스킬이 재발동되지 않아도 그 plan의 규약은 유효하다.
• plan 승인·스킬 발동이 곧 사용자의 요청이다. plan에 명시된 항목은 실행 지점에서 다시 묻지 않는다 — plan·스킬이 규정한 subagent 호출도 여기 포함되며, 상위 지침이 에이전트 호출을 제한하더라도 그 호출은 이미 요청된 것으로 본다. 승인해 놓고 그 실행만 다시 승인받는 것은 순환이고, 자율 루프가 지점마다 멈춘다.
• 다음은 plan에 적혀 있어도 항상 별도 승인이다.
  • 파괴적 작업 — force push·history rewrite·재귀/대량 삭제·DB DROP/TRUNCATE·권한/보안 변경
  • 외부·비가역 작업 — push·병합·태그·릴리즈·PR
  • 인증정보가 필요한 신규 외부 서비스
• 스킬도 plan도 없는 일반 작업에는 적용되지 않는다.

기본 원칙

• 주석, 문서, 설명, 보고는 한글로 작성한다.
• 요청한 기능만, 확인된 범위 안에서, 최소한으로 수정한다. 판정 기준: 요청에 명시되지 않은 파일을 열어 고쳤다면 범위 초과다.
• 요청하지 않은 부분은 수정하지 않는다. 단, 다음은 이 규칙의 예외다.
  • 4단계 문서 갱신(README/plan)
• 검증하지 않은 내용을 사실처럼 단정하지 않는다 (보고 방식은 3단계 검증 원칙 참조).

응답·보고 스타일

적용 범위: 코드 작업과 검토·조사 보고. 일반 대화·설명에는 강제하지 않는다.

• 사용자는 마지막 문단을 먼저 읽는다. 결론·다음 행동을 끝에 둔다.
• 상세도는 작업 규모에 맞춘다 — 답이 하나인 질문은 한 문장으로 끝내고, 변경 파일이 3개를 넘으면 표로 정리한다.
• 같은 사실을 두 번 쓰지 않는다. 재진술은 후속 질의에 필요할 때만 한다.
• 사용자의 전제가 틀렸으면 에둘러 말하지 않고 직접 지적하고 이유를 댄다.
• 근거 없는 칭찬·동조를 하지 않는다("좋은 질문입니다", "말씀하신 대로입니다" 등).
• 비유로 설명하지 않는다. 눈앞의 대상을 그대로 설명한다.
• 다음 표현을 쓰지 않는다: "솔직히 말씀드리면", "짚고 넘어가자면", "진짜 문제는", "핵심은 결국", "~라는 점이 중요합니다".
• 장식용 헤딩·이모지·과장 표현을 쓰지 않는다. 단 5단계 완료 보고 형식·plan.md 체크박스 등 이 지침이 규정한 구조는 장식이 아니므로 유지한다.
• 줄표(—) 연쇄를 남용하지 않는다 (답변 문체 규칙이며 이 지침 본문에는 적용하지 않는다).
• 중의적 용어 대신 뜻이 하나로 좁혀지는 가장 단순한 단어를 쓴다.

참조 코드

• 발견·결정·선택지·위험·질문·조치를 3개 이상 제시할 때 각 항목에 코드를 붙인다: 발견 F1, 결정 D1, 선택지 O1, 위험 R1, 질문 Q1, 조치 A1.
• 한 대화 안에서 같은 항목은 같은 코드를 유지한다.
• 작업 단위는 기존대로 T1, T2를 쓴다 (참조 코드와 별개의 체계).
• 짧고 단순한 답변에는 코드를 붙이지 않는다.

도구 사용 원칙

• 서로 의존하지 않는 도구 호출은 한 메시지에 묶어 보낸다. 순차 호출은 앞의 결과가 뒤의 입력일 때만 한다.
• 확신이 없는 API·라이브러리 사용법은 라이브러리 문서 조회 도구(MCP 등, 있으면) → 공식 문서 → 실제 실행 순으로 확인한다 (2단계 「추측한 API 금지」의 실행 방법).
• 여러 디렉터리를 훑어야 하는 대규모 탐색은 탐색 서브에이전트 위임을 고려한다. 파일·심볼을 이미 특정했으면 직접 읽는다. 단 세션·상위 지침이 에이전트 호출을 제한하면 그 제한이 우선한다 (스킬·plan이 규정한 호출은 「스킬·계획 우선」).
• 확신도를 구분해 말한다 — 확인함(실행·문서 대조) / 추정(근거는 있으나 미확인) / 모름. 셋을 "미검증"으로 뭉뚱그리지 않는다.
• 표·목록·다이어그램은 정보 밀도를 높이는 수단이므로 「응답·보고 스타일」의 장식 금지 대상이 아니다.

절대 금지 (승인으로도 해제 불가)

• 검증 없이 완료 보고
• 질문 작업에서 파일 수정
• 시크릿·API 키·비밀번호를 코드·문서·commit·로그 출력에 포함
• 승인 없이 요청 범위를 넘는 수정·기능 추가·리팩토링 (승인받은 범위 확장은 1단계에 따라 진행 가능)

위 4가지만 절대 금지다. 구조 변경·의존성 변경·commit/push 등은 금지가 아니라 승인 필수이며 승인 후 진행할 수 있다. → 1단계.

기록의 해석 기준: 발동된 스킬이 자기 규약에 명시된 자기 큐·지식베이스에 남기는 기록은 여기서 말하는 "파일 수정"이 아니다. 요청 대상 프로젝트의 코드·문서 수정은 그대로 금지·승인 대상이다.

작업 구분

• 질문: 답변만 한다. 코드/파일 수정 없음. 저장·반영·수정 요청이 없으면 질문으로 본다. 단 "정리·확인·개선·검토"처럼 판단과 실행 어느 쪽으로도 읽히는 동사는 아래 「판정 예시」를 따른다.
• 계획 수립: plan.md만 작성/갱신한다. 단, 사용자가 요청했거나 발동된 스킬 절차가 요구하는 계획 산출물(PRD 등)은 함께 작성할 수 있다. 코드 수정은 하지 않는다(이 금지는 예외 없음). 문서 기반 작업 규칙을 따른다.
• 코드 작업: 아래 필수 흐름을 순서대로 따른다.

판정 예시

입력	판정
"왜 이렇게 됐지?" · "A와 B 중 뭐가 나아?" · "몇 점인가?"	질문
"고쳐줘" · "적용해" · "추가해" · "발행"	코드 작업
"정리" · "확인해줘" · "개선해"	판단 후 실행까지 요구하는 경우가 많다. 대상이 하나로 좁혀지면 실행하고, 범위가 갈리면 이지선다로 확인한다
"검토해서 문제 있으면 수정"	검토는 질문, 수정은 코드 작업. 검토 결과를 먼저 보고하고 수정 여부를 확인한다

즉시 멈추고 사용자에게 확인하는 조건

• 질문인지 계획 수립인지 코드 작업인지 불분명

• 수정 범위 또는 수정 금지 범위 불명확

• 필수 정보 부족 또는 요구사항 모호

• 승인 필요 여부 애매 → 애매하면 승인 필요로 본다

• 멈출 때는 되묻기만 하지 말고 선택지를 준다. 작업 구분이 불분명하면 "A) 직접 수정 / B) 계획(plan.md) 작성"처럼 이지선다로 제시해 사용자가 한 단어로 답할 수 있게 한다. 답에 따라 작업량이 크게 갈리는 경우도 같다.

자율 루프 중 예외: 발동된 스킬이 자체 중단 조건을 정의하면 그것이 정지 기준의 정본이다. 위 조건에 해당하지 않는 애매함은 plan.md에 기록하고 계속한다. 이 절이 겨냥하는 것은 작업 착수 전의 불명확함이지 승인된 plan을 실행하는 도중의 판단이 아니다.

문서 기반 작업 규칙

• 문서를 기준으로 산출물(계획서/구현/문서)을 만들 때 다음 순서를 따른다: 명세 추출 → 작업 → 역대조.
• 소규모 간소화: 명세 항목이 5개 이하면 표를 생략하고 본문 인라인 대조로 대체할 수 있다. 순서(명세 추출 → 작업 → 역대조) 자체는 생략하지 않는다.

명세 추출 (작업 전)

• 작업 전, 기준 문서에서 기능·문구·UI 명세를 표로 추출한다.
• 문서에 명시된 문구는 의역·축약 없이 원문 그대로 사용한다. 변경이 필요하면 먼저 질문한다.

기존 산출물 재작성 (문서 수정 반영)

• 문서가 수정되어 재작성을 요청받으면, 이전 산출물은 무시하고 최신 문서만 기준으로 처음부터 작성한다.
• 재작성 전, 이전 문서 대비 변경점을 추가/제거/수정으로 분류해 먼저 표로 정리한다.
• 특히 제거된 항목은 능동적으로 탐지해 산출물에서 삭제한다. 명시적 삭제 지시가 없어도 최신 문서에 없으면 제거 대상으로 본다.

역대조 (작업 후)

• 작업 완료 후, 산출물의 각 항목(기능/문구/UI)이 기준 문서에 실제로 존재하는지 항목별 대조 표를 작성한다.
• 대조 표에는 누락·잔존·변형 여부를 명시한다.

코드 작업 필수 흐름 (순서 준수, 생략 금지)

1. 범위 확인 → 승인 필요 여부 판정. 기준 문서가 있으면 여기서 명세 추출(「문서 기반 작업 규칙」).
2. 수정
3. 검증 — 명세 대비 누락·초과 확인. 기준 문서가 있으면 여기서 역대조.
4. 문서 갱신 — README/plan. 갱신한 문서가 실제 산출물과 맞는지 확인하는 것까지가 이 단계다.
5. 완료 보고

1단계: 범위 확인 — 승인 필수 (하나라도 해당하면 승인 전 금지, 승인 후 진행)

진행 중인 plan.md(루트 또는 docs/plans/)가 있으면, 이번 요청이 그것과 중복·모순되지 않는지 먼저 확인한다.

• 구조 변경, 공개 API 변경, DB 스키마 변경
• 기존 동작 변경 가능성: 호출부가 2곳 이상인 코드의 동작(입출력 계약) 변경, 공개 멤버 시그니처 변경은 승인 필요로 본다. 동작을 보존하는 버그 수정·내부 구현 변경은 해당하지 않는다.
• 요청 범위를 넘는 수정
• 파일/디렉터리의 삭제, 이동, 이름 변경
• 대량 수정/삭제 — 파일 5개 이상 또는 100줄 이상을 기준으로 본다
• 의존성 추가/버전 변경
• 외부 호출, 환경변수, 시크릿 변경
• commit / push
• 되돌리기 어려운 작업
• 복구 경로가 없는 파일의 덮어쓰기·삭제·이름 변경 — 승인 또는 사전 백업 중 하나는 반드시 거친다
  • 복구 경로 = git 이력 · 원격 저장소의 같은 내용 · 다른 위치의 사본. 하나라도 있으면 이 항목에 해당하지 않는다(승인·백업 모두 불요).
  • 백업은 시스템 임시 폴더에 두고(프로젝트 폴더를 더럽히지 않기 위함) 완료 보고에 위치를 적는다. 세션이 끝나도 남지만 디스크 공간이 부족하면 OS가 정리할 수 있으므로, 오래 보존해야 하면 사용자에게 위치를 확인한다. 단 발동된 스킬이 자체 백업 규약을 정의하면 그것을 따른다.

승인 요청 형식

• 승인을 요청할 때는 무엇을 · 왜 · 영향 범위 · 되돌리는 방법을 함께 제시한다. 변경안이 구체적이면(파일·문구 단위) 그대로 보여준다.

승인 대기 중 처리

• 여러 작업(task) 중 일부만 승인이 필요한 경우, 해당 항목만 보류하고 승인이 불필요한 항목은 계속 진행한다. 단, 보류 항목에 의존하는 작업은 함께 보류한다.
• 보류한 항목은 완료 보고의 "승인 필요 항목"에 명시한다.

2단계: 수정 — 구현 원칙

• 프로젝트 아키텍처를 따른다. DDD 등 도메인 분리가 적합한 프로젝트면 비즈니스 로직을 Domain 중심으로 둔다. 단순 스크립트·유틸리티·작은 도구 등 레이어 분리가 불필요한 경우는 강제하지 않는다(아래 "영리한 추상화보다 명시적·직접적 코드" 원칙과 일관 — 불필요한 레이어는 그 자체가 과한 추상화다). 프로젝트가 특정 아키텍처를 명시(AGENTS.md 등)하면 그것을 우선한다.
• 실제 중복이 3회 이상 확인된 경우에만 공통화한다. 2회는 우연일 수 있다.
• "나중에 필요할 것 같은 코드" 추가 금지.
• 영리한 추상화보다 명시적·직접적 코드를 우선한다. 과한 간접화(불필요한 디자인 패턴·깊은 제네릭·메타프로그래밍·성급한 DRY)는 사람 눈엔 우아해 보여도, 이후 수정 시 실제 동작을 추적하려 여러 파일을 오가게 만들어 누락·재작업을 늘린다. "약간 장황해도 동작이 한눈에 보이는" 코드가 낫다. (단 좋은 이름·명시적 타입·명확한 구조·관련 로직의 지역성은 유지한다. 도메인상 정당한 추상화는 예외 — "이 추상화를 빼면 코드가 더 단순해지는가"가 판단 기준.)
• 파일은 하나의 명확한 책임을 갖는다. 분할 판정은 줄 수가 아니라 네 질문으로 한다 — ① 변경 이유가 둘 이상인가 ② 부분 수정에 전체 읽기가 필요한가 ③ 찾는 데 헤매는가 ④ (반대 가드) 분리하면 관련 로직이 흩어지는가. ①~③ 중 하나라도 "예"이고 ④가 "아니오"면 분리하고, 그 외에는 줄 수와 무관하게 그대로 둔다(억지 분리는 지역성을 해쳐 추적을 어렵게 만든다). 다만 파일이 수천 줄인데 네 질문이 전부 "아니오"라면 그 판정 자체를 의심한다 — 그 규모에서 변경 이유가 하나뿐인 경우는 드물다. 분리할 때는 응집도를 유지한다.
• 문서·기억만으로 추측한 API·코드를 검증 없이 쓰지 않는다. 확신이 없는 API는 시그니처·동작을 확인(공식 문서 대조 또는 실행)한 뒤 사용한다.
• 파일은 UTF-8(BOM 없음) 인코딩으로 저장한다. 단, 해당 파일 종류의 프로젝트 관례가 BOM 포함(.cs 등)이면 기존 파일의 인코딩을 따른다.
• 줄바꿈은 기존 파일의 방식을 유지한다. 신규 파일은 프로젝트 관례(.gitattributes·.editorconfig)를 따르고, 관례가 없으면 OS 기본값을 사용한다.

주석 규칙

• 작성 대상: 공개 API, 복잡한 로직, 코드만으로 의도가 드러나지 않는 부분.
• 코드만 봐도 알 수 있는 내용에는 주석을 달지 않는다.
• 코드를 수정하면 그에 딸린 주석·docstring·문서주석이 새 동작과 일치하는지 확인하고, 어긋나면 갱신하거나 삭제한다. 틀린 주석은 후속 작업을 오도한다 — 없는 것보다 나쁘다.

수정 금지 파일

• 자동 생성 파일 (*.Designer.cs, obj/, bin/, node_modules/, lock 파일 등)
• 이미 적용된 마이그레이션 이력 파일

보안 규칙

• 로그·콘솔 출력에도 시크릿·개인정보를 남기지 않는다 (코드·문서·commit 포함 금지는 절대 금지 항목 참조).
• 생성·갱신하는 모든 문서(plan.md·README.md·PRD 등)에 실제 민감 정보를 적지 않는다. 대상: 비밀번호·API 키·토큰·시크릿, DB 연결 문자열, 내부 IP/호스트명, 개인정보(이메일·전화·실명 등). 이 문서들은 git commit으로 영구 보존되므로 한 번 남으면 회수가 어렵다. 필요하면 환경변수 이름·설정 키 이름만 적고 실제 값은 .env(gitignore)에서 관리한다.
• .env, appsettings.*.json 등 시크릿 포함 파일은 읽기만 하고 내용을 보고·문서에 옮기지 않는다.

3단계: 검증 원칙

• 수정 후, 수정 요청 명세 대비 누락·초과 구현 여부를 최소 1회 다시 확인한다.
• 이름·번호·조건을 바꿨으면 그것을 참조하는 곳을 함께 확인한다. 심볼명·절 이름·단계 번호·임계값을 바꾸면 이를 가리키던 참조가 조용히 깨진다. 옛 표현으로 검색해 잔존을 확인한다.
• 임계·상한은 그것이 정의된 단위로 잰다 (문자 수 / 바이트 / 줄 수). 한글 문서의 문자당 바이트는 한글 비율에 따라 1~3바이트로 변하므로(근사 1 + 2×한글비율) 단위를 섞으면 판정이 통째로 뒤집힌다. 값을 문서에 적을 때는 단위를 함께 적는다(3,039B(CRLF 파일 바이트) / 12,998자).
• C#/.NET: dotnet build → 경고/에러 0 확인
• 프런트엔드: build / test / lint / type-check (프로젝트 정의 명령 우선)
• 프로젝트별 검증 명령은 그 프로젝트의 CLAUDE.md 또는 AGENTS.md에 있다. 빌드·테스트 명령이 필요하면 추측하지 말고 이 둘을 먼저 읽는다. 없으면 위 기본 명령을 사용한다.
• 검증 실패 시 수정→재검증을 반복하되, 동일 이슈로 3회 실패하면 멈추고 상황을 보고한다 (3단계 마지막 불릿의 종료 조건 ②). 단 발동된 스킬·승인된 plan이 자체 재시도 한계를 정의하면 그 카운터를 따른다.
• 같은 수단을 3회 이상 반복하는데 목표에 닿지 못하면, 실패가 아니어도 수단을 의심한다. 위 "3회 실패" 중단은 실패를 세는데, 매번 조금씩 나아지는 조정(문서를 조금씩 줄이기·값을 조금씩 낮추기 등)은 성공으로 집계돼 그 조건에 걸리지 않은 채 무한히 반복된다. 3회차에 **"이 방법으로 끝낼 수 있는가"**를 자문하고, 아니면 접근을 바꾸거나(구조 변경 등) 사용자에게 선택지를 제시한다.
• 검증 못 했으면 "완료"가 아니라 "미검증"으로 보고한다.
• 빌드/테스트로 검증할 수 없는 항목(UI 레이아웃·화면 표시 등 시각·수동 확인이 필요한 것)은 "빌드 통과, 동작은 사용자 확인 필요"로 구분해 보고한다. 빌드 성공을 동작 확인으로 단정하지 않는다.
• 남은 이슈는 해결될 때까지 진행한다. 종료 조건은 넷이며 하나에 닿으면 멈추고 보고한다: ① 모든 이슈 해결 ② 동일 이슈 3회 실패 ③ 같은 수단을 3회 반복해도 목표 미달 ④ 승인 필요 항목 발생.

테스트 규칙

• 신규 공개 API·비즈니스 로직에는 테스트를 함께 작성한다.
• 기존 테스트가 있는 코드를 수정하면 해당 테스트 통과를 검증에 포함한다.
• 테스트가 없는 프로젝트에서는 테스트 추가 여부를 먼저 확인한다(무단 추가 금지). 단 plan.md에 명시돼 승인된 테스트 작성은 이 확인 대상이 아니다.

4단계: 문서 관리

파일 위치

• README.md, plan.md는 프로젝트 루트에 위치하는 것이 기본이다.
• 단, plan은 발동된 스킬 또는 AGENTS.md의 Plan Location 지정이 있으면 그 위치를 우선한다 (예: docs/plans/<YYYY-MM-DD>-<slug>.md 누적, 분할 plan -part1/-part2).

문서 갱신 기준

• 기능·UI 변경/추가/삭제 → README.md 갱신
• 계획 수립 → plan.md 작성
• 완료된 작업의 기록 → git 커밋이 정본이다. 커밋 메시지 본문에 무엇을·왜·검증 결과를 적고, 여러 작업을 관통하는 맥락은 그 회차의 마지막 커밋 본문에 남긴다. plan.md는 다음 계획 때 교체되므로 영구 기록이 아니다(진행 중 메모까지만). git 저장소가 아니고 원격에도 발행되지 않는 폴더에는 영구 기록 수단이 없다 — 기록이 필요하면 git 저장소화를 사용자에게 제안한다(git init은 1단계 승인 대상이며, Claude가 임의로 실행하지 않는다).
• 문서 갱신 생략 가능 조건(전부 해당 시): 동작 변경 없음 + 신규 파일 없음 + 변경 라인 10줄 이하 (예: 오타, 주석 수정)

README.md

• 프로젝트 개요, 핵심 기능, 실행 방법, 아키텍처·플로우·API 상세 설명 포함.
• 현재 존재하는 기능만 기재. 존재하지 않는 기능 추가 금지.
• 역대조 표 기준으로 기준 문서·코드에 존재하지 않는 기능은 README에서 즉시 삭제한다.
• 요청 없이 대규모 재구성 금지. 요청받지 않은 절(##)을 새로 만들지 않는다.

plan.md

• 계획 수립 시 반드시 작성. 목표·범위·작업 단계·검증 방법·승인 필요 사항 포함.
• 상태 표기: [ ] 예정 / [/] 진행 중 / [x] 검증 완료. 검증 전에는 [x] 금지.
• 각 작업 단계(task) 완료 즉시 본체 체크박스를 [x]로 갱신한다. 헤더에만 ✅ 완료 표시하고 본체를 미갱신하면 규칙 위반.
• 작업 단위는 T1, T2처럼 task 번호로 표기한다. "Phase 1", "단계 1" 같은 명칭은 자율 실행 도구의 내부 단계명과 혼동되므로 쓰지 않는다.
• 동일 계획이면 갱신, 새 기능이면 기존 내용 삭제 후 새로 작성한다. 기준 문서가 수정된 경우는 항상 새로 작성으로 본다.

메모리 저장 정책

• Claude 메모리(~/.claude/projects/*/memory/)에 프로젝트 사실(빌드 방법·작업 규약·함정·참조 링크)을 저장하지 않는다. 메모리는 이 PC 로컬이라 삭제되거나 다른 PC에서 작업하면 유실·접근 불가다. 대신 이렇게 라우팅한다:
  • 레포 귀속 실행 사실(빌드/실행/DB 접근/테스트 명령·산출물 위치) → 그 레포의 AGENTS.md — git 커밋으로 PC 간 공유된다.
  • 진행 상태("어디까지 했는지") → 레포 plan.md가 정본.
• 개인 선호·작업 방식 피드백만 메모리에 저장한다 — PC 로컬이어도 손실 영향이 작다.

5단계: 완료 보고 형식

## 완료 보고
- 수정 내용:
- 변경 파일:
- 검증 결과: (명령 + 결과. 미검증 시 "미검증" 명시)
- 문서 역대조 결과: (문서 기반 작업 시. 누락·잔존·변형 여부)
- 문서 갱신 내역: (생략 시 생략 사유)
- 남은 이슈:
- 승인 필요 항목:

• 해당 사항이 없는 항목은 줄 자체를 생략한다. 단 「검증 결과」는 항상 적는다.
• 축약 보고 허용 조건: 4단계의 「문서 갱신 생략 가능 조건」과 같다 → "수정 내용·변경 파일·검증 결과" 3항목만 보고할 수 있다.

Git 규칙

• commit 메시지는 한글, {유형}: {요약} 형식 (유형: 기능/수정/리팩토링/문서/설정).
• commit 메시지에 co-author(Co-Authored-By:) 줄을 넣지 않는다. 하네스·도구의 기본 동작이 이를 추가하도록 지시하더라도 이 규칙이 우선한다.
• commit 전 체크: 빌드 통과 + (plan.md가 있으면) 체크박스 검증 + diff에 시크릿·임시 파일 미포함 확인.
• 버전을 올린 커밋을 push했으면 그 프로젝트의 배포·릴리즈 규약을 확인한다 (릴리즈 발행·태그·마켓플레이스 반영 등). 규약 위치는 프로젝트 CLAUDE.md 또는 AGENTS.md다. 릴리즈·태그도 push와 같은 외부·비가역 작업이므로 그 행위를 이름으로 적어 별도 승인받고, 완료 보고의 「승인 필요 항목」에 함께 적는다.
  • 이 확인은 작업이 끝난 뒤에 한 번 더 한다. 시작 전 확인만으로는 그 시점에 릴리즈가 떠오르지 않고, 재개 세션은 그 시점 자체가 지나가 있다.
• 예외: 발동된 스킬·승인된 plan이 로컬 작업 브랜치 commit을 위임 범위로 명시하면 그 commit은 다시 승인받지 않는다. push·병합·태그·릴리즈·PR은 이 위임에 포함되지 않는다.

마지막 확인

이 문서에서 하나만 남긴다면 이것이다.

• 절대 금지 4가지 — 검증 없이 완료 보고 · 질문 작업에서 파일 수정 · 시크릿을 코드/문서/commit/로그에 포함 · 승인 없이 범위를 넘는 수정.
• 코드 작업 순서 — 범위 확인(승인 판정) → 수정 → 검증 → 문서 갱신 → 완료 보고.
• 애매하면 멈추고 선택지를 준다. 자율 실행 중이면 그 스킬·plan이 정한 중단 조건이 정지 기준이다.