Claude가 웹 테스트 명령을 매번 다르게 제안한다면 프롬프트를 길게 쓰기보다 `CLAUDE.md`와 실제 `package.json`이 서로 맞는지 먼저 봐야 합니다. 프로젝트 지침은 설명서 창고가 아니라 새 세션이 어떤 파일을 읽고 어떤 명령을 실행할지 정하는 짧은 규칙입니다. 여기서는 Plan Mode로 충돌을 찾고, 사람이 남길 문장과 버릴 문장을 고른 뒤 새 세션에서 다시 확인하는 흐름을 보여줍니다.

핵심 좋은 프로젝트 지침은 자주 쓰는 명령, 반드시 지켜야 할 구조와 금지사항을 구체적으로 적고 나머지 지식은 별도 문서로 연결합니다. 개인 설정은 팀 파일에 섞지 말고 현재 공식 문서 불러오기 방식을 사용합니다.

무엇을 넣고 무엇을 빼야 하나. 저장소 구조의 핵심, 개발 브랜치, 포맷·테스트·배포 명령, 데이터와 보안 금지사항, 자주 틀리는 프로젝트 고유 규칙은 넣을 가치가 큽니다. 누구나 코드만 보면 알 수 있는 설명과 일회성 작업 기록은 지침을 불필요하게 키웁니다.

막연한 표현보다 관찰 가능한 행동을 적습니다. 품질을 높이라는 문장보다 변경한 PHP 파일에 문법 검사를 실행하라는 문장이 잘 지켜지고 검증하기도 쉽습니다.

프로젝트와 개인 지침을 분리한다. 프로젝트 루트의 팀 지침 파일은 저장소 구성원이 공유하는 규칙입니다. 사용자 전역 지침은 홈 디렉터리의 파일에 둡니다. 과거의 로컬 전용 지침 파일은 현재 폐기됐으며, 개인 지침을 팀 파일에서 불러오는 공식 방식이 여러 Git 워크트리와 더 잘 맞습니다.

비밀키와 개인 토큰은 어떤 지침 파일에도 적지 않습니다. 파일 위치를 안내해야 한다면 값이 아니라 안전한 저장 위치와 로딩 방법만 기록합니다.

큰 저장소에서는 계층을 이용한다. Claude Code는 실행 위치에서 상위 방향의 지침을 읽고, 하위 폴더의 지침은 해당 영역 파일을 읽을 때 추가로 발견합니다. 모노레포 전체 규칙은 상위에, 웹·서버·모바일의 세부 규칙은 각 하위 폴더에 두면 초기 컨텍스트를 줄일 수 있습니다.

같은 규칙을 여러 파일에 복제하면 시간이 지나 충돌합니다. 공통 규칙은 한 곳을 원본으로 두고 다른 지침은 링크하거나 차이만 기록합니다.

지침도 코드처럼 리뷰한다. 작업이 끝날 때 새로 발견한 규칙을 무조건 추가하지 않습니다. 반복될 가능성, 프로젝트 전체 적용 여부와 기존 문서와의 중복을 확인합니다. 길이가 계속 늘어난다면 원칙, 운영 문서와 특정 사건 기록이 섞였다는 신호입니다.

잘못된 코드가 반복되면 프롬프트를 더 세게 쓰기 전에 지침이 모호한지, 실제 테스트 명령이 빠졌는지 확인합니다. 지침의 품질은 문장 수가 아니라 반복 오류가 줄어드는지로 판단합니다.

긴 지침을 바로 고치지 말고 충돌부터 찾습니다. 예시 세션에서는 루트 `CLAUDE.md`와 웹 하위 지침이 서로 다른 패키지 명령을 가리킵니다. Plan Mode에서 지침 파일과 실제 `package.json`만 읽혀, 어느 규칙이 코드와 맞는지 먼저 확인합니다.

지침 감사용 첫 프롬프트
claude --permission-mode plan

CLAUDE.md, apps/web/CLAUDE.md, package.json, apps/web/package.json을 읽으세요.
코드는 수정하지 마세요.
출력은 다음 표로 제한하세요.
- 규칙 문장
- 실제 코드 또는 스크립트 근거
- 충돌 여부
- 유지/삭제/별도 문서 이동 제안
개인 설정과 비밀값은 읽지 마세요.

후속 요청은 문장 수보다 행동을 바꿉니다. 사람이 "웹 테스트는 `pnpm --filter web test`가 맞고, 배포 설명은 운영 문서로 이동"이라고 결정한 뒤 편집을 승인합니다. 후속 프롬프트는 "두 지침 파일만 수정하고 코드에는 손대지 마세요. 같은 규칙을 중복하지 말고 하위 파일에는 웹 전용 차이만 남기세요"처럼 씁니다.

수정 뒤 `git diff --check`, `git diff -- CLAUDE.md apps/web/CLAUDE.md`를 보고 두 파일 외 변경이 없는지 확인합니다. 이어 새 Claude 세션을 열어 지침만 읽힌 상태에서 웹 테스트 명령을 물어 예상 명령을 반환하는지 봅니다. 팀 결정이 필요한 브랜치 정책이 나타나거나 개인 선호와 공통 규칙을 구분할 수 없으면 편집을 멈춥니다. 지침 변경 검증은 기존 대화가 없는 새 세션에서 해야 이전 설명의 영향을 피할 수 있습니다.

가상의 결제 작업에서 같은 검사가 계속 빠졌다. 가상의 저장소는 결제 상태를 바꾸면 일반 단위 테스트와 별도로 멱등성 회귀를 실행해야 했습니다. 규칙이 긴 운영 문서 중간에 있어 에이전트는 일반 테스트만 통과시키고 완료라고 보고했습니다. “테스트를 충분히 실행한다”는 팀 지침도 어떤 명령을 뜻하는지 모호했습니다.

잘못된 선택의 예로 운영 문서를 통째로 프로젝트 지침에 붙이면 필요한 규칙은 생겼지만 지침이 지나치게 길어져 다른 작업에서도 배포 역사와 장애 기록을 읽었습니다. 빠뜨린 내용을 전부 넣는 선택은 중요한 한 줄을 더 잘 보이게 하지 못했습니다.

필수 행동만 남긴 뒤 결과가 달라진다. 프로젝트 지침에는 결제 파일 경로, 변경 뒤 실행할 두 명령, 운영 결제 실행 금지, 배포 승인 필요만 남겼습니다. 상세한 장애 원인과 복구 절차는 별도 문서에 두고 결제 작업에서만 읽도록 연결했습니다. 개인이 쓰는 출력 형식과 단축 명령은 팀 파일에서 제거했습니다.

교정 전에는 멱등성 검사가 누락되는지 보고, 지침 수정 뒤에는 결제 파일 변경 시 해당 명령이 제안되는지 새 세션에서 확인합니다. 고의로 중복 요청 결함을 넣은 작업은 일반 테스트를 통과한 뒤 멱등성 검사에서 실패했습니다. 짧아졌다는 사실보다 반복 누락이 실제로 줄었다는 결과가 지침의 효용을 보여줬습니다.

지침에 추가하지 말아야 할 순간. 한 번 발생한 장애의 시간표, 이미 코드가 강제하는 형식, 개인의 말투 선호는 팀 지침에 넣지 않습니다. 새 규칙이 기존 규칙과 충돌하거나 어느 명령으로 준수 여부를 확인할지 답할 수 없으면 추가를 보류합니다.

비밀값과 고객 데이터는 예시로도 기록하지 않습니다. 공식 동작이 바뀌어 파일 계층이나 불러오기 방식이 불확실하면 현재 문서를 확인할 때까지 단정하지 않으며, 팀 지침 변경도 코드 변경처럼 동료 검토를 거칩니다.