Claude가 따르는 CLAUDE.md
거의 모든 사람이 걸려드는 함정이 하나 있습니다. 바로 CLAUDE.md 파일이 계속 커진다는 점입니다. 문제가 하나 생기면 규칙을 하나 추가하고, 또 다른 문제가 생기면 또 규칙을 추가합니다. 그러다 보면 어느새 거대한 파일 하나가 만들어지고, Claude는 그 내용 중 일부를 무시하기 시작합니다. 이는 Claude의 버그가 아닙니다. 이 파일이 작동하는 방식이 원래 그렇습니다.
여기서 꼭 이해해야 할 핵심은 CLAUDE.md가 강제되는 설정이 아니라는 점입니다. 이는 가이드라인입니다. 파일 안의 모든 줄은 Claude의 주의를 끌기 위해 다른 모든 줄과 경쟁합니다. 파일이 길어질수록 줄들끼리 더 많이 경쟁하게 되고, Claude가 개별 규칙을 안정적으로 따를 가능성은 줄어듭니다. 따라서 목표는 모든 것을 적어두는 것이 아닙니다. 목표는 파일을 군더더기 없이 유지하는 것입니다. 파일이 간결할수록 Claude는 그 내용을 실제로 더 많이 따릅니다.
먼저, CLAUDE.md가 애초에 적합한 도구인지 물어보세요
규칙을 작성하기 전에, 그것이 애초에 CLAUDE.md에 속하는 것인지 물어보세요. 어떤 규칙은 가이드라인이고, 어떤 규칙은 절대 넘어서는 안 되는 엄격한 선입니다. 이 둘은 전혀 다른 역할을 합니다.
"main 브랜치에 절대 push하지 않는다"와 같은 규칙을 생각해보세요. 이를 CLAUDE.md에 넣는다면, 여러분은 Claude가 이를 읽고 지켜주기를 바라는 셈입니다. 대부분의 경우 그렇게 될 것입니다. 하지만 그렇게 위험한 사안에서는 "대부분의 경우"로는 충분하지 않습니다. 이런 엄격한 규칙은 대신 pre-tool-use 훅에 속해야 합니다.
이 차이는 중요합니다. 훅은 Claude가 어떤 동작을 실행하기 전에 실행되는 코드이며, 실제로 그 동작을 차단할 수 있습니다. 따라서 Claude가 main에 push를 시도하더라도 훅이 이를 막습니다. 이는 정중한 요청이 아니라 실질적인 강제입니다. 엄격한 규칙은 훅으로 옮기고, CLAUDE.md는 더 유연한 관행을 다루도록 맡기세요.
네 가지 위치
CLAUDE.md는 프로젝트 안에 덩그러니 놓인 단일 파일이 아닙니다. 이 파일이 존재할 수 있는 위치는 네 곳이며, Claude는 실행 시 이 네 가지를 모두 함께 불러옵니다. 어느 것도 누락되지 않으며, 서로 겹쳐 쌓입니다.
각각의 용도는 다음과 같습니다:
- 관리형 정책(Managed policy) — 플랫폼 팀이 관리하는 조직 수준의 파일입니다. 이를 제외할 수 없으므로, 조직 정책은 항상 적용됩니다.
- 사용자(User) — 여러분의 머신에 있는 모든 프로젝트에 걸쳐 따라다니는 개인 선호 설정입니다.
- 프로젝트(Project) — 리포지토리에 커밋되어 팀과 공유되는 파일입니다.
- 로컬(Local) — git에서 제외됩니다. 이 리포지토리 하나만을 위한 개인 메모입니다.
마지막 항목인 로컬은 간과하기 쉽지만 실제로는 매우 유용합니다. 예를 들어 자신만의 브랜치에서 리팩터링을 진행하면서 작업 중 특정 아키텍처 결정 사항을 Claude가 염두에 두길 바란다고 해봅시다. 이는 팀 전체에 영향을 미치는 공유 프로젝트 파일에는 어울리지 않습니다. 이럴 때는 로컬에 넣으면 되며, 이 리포지토리에서만 여러분만의 것으로 남습니다.
import로 큰 파일을 분리하기
프로젝트 파일이 길어지기 시작하면, path-to-file import 구문을 사용해 여러 조각으로 나눌 수 있습니다. 하나의 거대한 텍스트 덩어리 대신, 다른 파일을 가리키는 것입니다:
@.claude/conventions/code-style.md
@.claude/conventions/testing.md
@.claude/conventions/workflow.md이는 정리하는 데는 아주 좋습니다. 하지만 이것이 정확히 무엇을 해주는지는 분명히 알아야 합니다. 잘못 이해하기 쉽기 때문입니다. Claude가 실행될 때, import된 파일들은 참조된 바로 그 위치에 인라인으로 펼쳐집니다. 즉 import는 내용을 깔끔하게 정리하는 데는 도움이 되지만, 모든 내용은 여전히 처음부터 다 로드됩니다. import는 Claude가 읽어야 할 컨텍스트의 양을 줄여주지 않습니다. import는 정리하는 용도로 쓰되, 로드량을 줄이는 용도로 쓰지는 마세요.
규칙을 지속시키는 것은 바로 어구 선택입니다
규칙이 CLAUDE.md에 속한다고 판단했다면, Claude가 실제로 그것을 따를지는 어떻게 어구를 선택했는지에 달려 있습니다. 대부분의 규칙이 실패하는 이유는 모호하기 때문입니다. 이를 바로잡는 방법은 다음과 같습니다.
구체적이고 확인 가능하게 작성하세요
"모범 사례를 따르세요"라고 쓰지 마세요. 여러분 자신도 그것이 정확히 무엇을 의미하는지 아시나요? 지켜졌는지 확인할 수 없다면, Claude도 확인할 수 없습니다. 다음 두 문장을 비교해보세요:
- 모호함: "API 라우트에 대해 모범 사례를 따르세요."
- 구체적: "새 API 라우트는
src/api/handlers에, 파일 하나당 하나씩 넣으세요."
두 번째 문장은 명확합니다. 결과물을 보면 제대로 됐는지 바로 알 수 있습니다. 이것이 모든 규칙이 통과해야 할 기준입니다.
금지만 하지 말고 대안을 명시하세요
Claude에게 어떤 것을 하지 말라고 할 때는, 대신 무엇을 해야 하는지도 말해주세요. 그렇지 않으면 해석의 여지를 열어두는 셈입니다.
- 여지를 남김: "기본 내보내기(default export)를 쓰지 마세요." 좋습니다, 그럼 대신 무엇을 쓰나요?
- 여지를 없앰: "기본 내보내기 대신 이름 있는 내보내기(named export)를 쓰세요."
두 번째 버전은 대안을 명시하고 있어서, 잘못 해석할 여지가 없습니다.
외치지 말고 담담하게 말하세요
"IMPORTANT"나 "YOU MUST" 같은 단어는 Claude가 계속 놓치는 규칙을 거의 구해내지 못합니다. 현재 모델들은 담담하게 적힌 문장을 잘 따르며, 강조를 쌓아올릴수록 오히려 Claude가 그 규칙을 과도하게 적용하게 만들 뿐입니다. 규칙이 절대 타협할 수 없는 것이라면 훅으로 만드세요. 규칙이 계속 묻힌다면 파일을 더 짧게 만드세요.
파일을 계속 수정 중인 상태로 유지하세요
CLAUDE.md 파일은 절대 완성되지 않습니다. 계속 편집되는 살아있는 코드처럼 다루세요.
Claude가 잘못된 일을 했을 때, 그냥 한숨 쉬고 손으로 고치는 데 그치지 마세요. 이를 CLAUDE.md 파일에 대한 버그 리포트로 취급하세요. 심지어 Claude에게 직접 "그걸 CLAUDE.md 파일에 추가해줘"라고 말할 수도 있으며, 그러면 Claude가 여러분 대신 규칙을 작성해줄 것입니다. 이렇게 하면 뭔가 잘못될 때마다 파일이 점점 더 나아집니다.
핵심 요약
CLAUDE.md를 프로덕션 코드처럼 다루세요. 어떤 줄을 정당화할 수 없다면 삭제하세요. 파일을 간결하고 잘 따르게 유지하려면:
- 엄격한 규칙은 훅으로 옮기세요. 그래야 실제로 강제됩니다.
- 긴 파일은 import로 정리하세요(다만 이것이 컨텍스트를 줄여주지는 않는다는 점을 기억하세요).
- 모든 규칙을 구체적이고 확인 가능하게 작성하고, 대안을 명시하세요.
- 강조를 더하기보다는 규칙을 담담하게 표현하세요.
- Claude가 뭔가 잘못할 때마다 파일을 계속 수정하세요.
전체 아이디어는 단순합니다. 파일이 간결할수록 Claude는 그 내용을 더 많이 따릅니다.