CLAUDE.md를 오래 지키게 만든 규칙

처음 CLAUDE.md를 만드는 분, 파일은 만들었는데 Claude가 자꾸 어긴다고 느끼는 분에게 맞는 글입니다. 매번 같은 작업 방식과 주의사항을 설명하지 않으려 파일을 두지만, 한 번 작성했다고 곧바로 안정적인 작업 규칙이 되지는 않습니다.

저희도 앱 저장소에서 4주 동안 운영하며 파일을 여러 번 고쳤습니다. 처음에는 유용해 보였던 문장이 나중에는 비용이 되기도 했고, 저장 위치 때문에 예상하지 못한 문제가 생기기도 했습니다. 몇 가지 함정은 실제 작업 뒤에야 드러났습니다.

먼저 결론부터

• CLAUDE.md는 저장소에 두면 세션마다 자동으로 읽히므로, 반복해서 입력하던 작업 규칙을 담기에 좋습니다.
• 홈 파일은 모든 프로젝트에, 저장소 루트 파일은 해당 저장소에, 하위 폴더 파일은 그 폴더 작업에 함께 적용되도록 계층을 나눕니다.
• 항상 읽히는 파일은 짧게 유지하고, 저희는 토큰을 줄이기 위해 이 파일을 영어로 작성하며 필요한 문서는 한국어로 분리합니다.
• 규칙은 추상적인 권고 대신 결과를 보고 판정할 수 있는 금지 문장으로 씁니다.
• 같은 실수를 두 번 겪었을 때만 규칙을 추가하면, 파일이 경험과 함께 자라면서도 불필요하게 길어지지 않습니다.
• 공개 범위와 실제 측정값을 함께 점검해야 하며, 특히 측정이 규칙을 반박할 때는 규칙을 먼저 고쳐야 합니다.

파일은 계층으로 나눕니다

범위부터 나눴습니다.

앱 저장소에서는 모든 프로젝트에 적용할 기준은 홈에 두고, 저장소 전체의 작업 방식은 루트에 두며, 특정 기능이나 폴더에서만 반복되는 주의점은 그 하위 폴더에 두어 읽히는 범위를 작업 위치에 맞췄습니다.

구성은 아래와 같습니다.

~/.claude/CLAUDE.md                 # 모든 프로젝트
project/.claude/CLAUDE.md           # 해당 저장소
project/feature/.claude/CLAUDE.md   # feature 폴더 작업

이 구조는 앱 저장소에서 쓰고 있습니다. 전역 파일에는 정말 공통인 기준만 남기고, 테마나 특정 초기화 코드처럼 한 프로젝트에만 해당하는 내용은 저장소 또는 하위 폴더로 내렸습니다.

항상 읽히는 파일은 짧아야 합니다. 세션마다 토큰을 쓰기 때문입니다. 저희는 같은 뜻이라면 영어가 한국어보다 토큰을 덜 먹는다는 점을 반영해 항상 읽히는 파일을 영어로 작성하고, 필요할 때만 여는 긴 문서는 한국어로 둡니다.

금지는 판정 가능하게 씁니다

모호한 문장은 남지 않았습니다.

‘코드를 깔끔하게’라는 문장은 무엇을 검사하고 멈춰야 하는지 알려 주지 못했지만, main에 직접 push하지 말고 브랜치와 PR을 거치라는 문장은 작업 결과에서 바로 판정할 수 있었습니다.

저희 파일의 절반은 이런 금지 목록입니다.

- Do not push directly to main. Use a branch and PR.
- Do not leave AI traces in commit messages.

규칙 하나에는 행동 하나를 넣는 편이 좋았습니다. 완료 뒤에 누가 봐도 지켰는지 판단할 수 있어야 합니다. 표현의 품질을 요구하고 싶다면, 그 품질을 확인할 기준도 함께 적어야 합니다.

사고 뒤에 규칙을 추가합니다

처음부터 많이 쓰지 않았습니다.

같은 함정을 두 번 만났을 때만 파일에 넣었습니다. 실제로 특정 테마에서 다크 모드 선택자가 예상과 달랐던 일, 특정 초기화 코드가 표를 깨뜨린 일처럼 작업 중에 겪은 사례만 규칙이 됐습니다.

이 기준은 파일을 가볍게 지킵니다. 일어나지 않은 위험까지 미리 적으면 읽는 비용만 커지고, 중요한 항목도 긴 목록 속에 묻힙니다. 문제가 재현됐는지와 다시 막을 가치가 있는지를 확인한 뒤에 추가하면 충분합니다.

공개 범위도 작업 규칙입니다

규칙 파일도 저장소 파일입니다.

블로그 저장소 여덟 개가 전부 공개인 상태에서 에이전트 운영 규칙을 그대로 올려 두고 있었고, 이를 발견한 뒤에는 규칙을 비공개 저장소로 옮긴 다음 프롬프트가 절대 경로에서 읽도록 바꿨습니다.

이 변경은 추측으로 정하지 않았습니다. 헤드리스 에이전트가 작업 폴더 밖의 경로를 읽을 수 있는지 먼저 실험으로 확인했습니다. 공개 저장소의 CLAUDE.md에는 공개돼도 괜찮은 내용만 넣어야 합니다(운영 방식도 포함됩니다).

측정값이 규칙을 이겨야 합니다

이 부분이 가장 오래 남았습니다.

글쓰기 규칙은 짧은 문장을 섞어 끊으라고 했지만, 같은 프로젝트의 측정은 실제 문제를 긴 문장의 부재로 정정한 상태였고, 이 차이를 놓친 탓에 넉 달치 글이 한 방향으로 쏠렸습니다.

규칙은 계속 맞는 답이 아닙니다. 문체 규칙이든 코드 규칙이든, 실제 결과를 측정하는 기준과 충돌하면 규칙의 근거부터 다시 봐야 합니다. 저희는 이 일을 겪은 뒤 규칙 자체도 주기적으로 검증할 대상으로 다루고 있습니다.

마무리

다음 작업에서는 전역, 저장소, 하위 폴더에 둘 내용을 먼저 세 칸으로 나누고, 지금 반복되는 실수 한두 개만 판정 가능한 문장으로 적어 보시면 됩니다. 그 뒤에는 세션 몇 번을 지나며 실제로 지켜졌는지, 파일이 길어지지 않는지 확인하면 됩니다.

여기서 적은 테마 선택자, 표를 깨뜨린 초기화 코드, 헤드리스 에이전트의 경로 읽기, 글의 측정값은 공식 문서에 있을 수 없는 저희 프로젝트의 작업 기록입니다. CLAUDE.md의 동작 방식은 문서에서 확인할 수 있어도, 어떤 규칙이 비용이 됐고 어떤 규칙이 측정과 어긋났는지는 각 저장소에서 직접 확인해야 합니다.