Claude가 실제로 따르는 CLAUDE.md는 어떻게 쓰는가?

CLAUDE.md는 강제 설정이 아니다 — 왜 길수록 덜 따르나

CLAUDE.md는 프로젝트의 지침(코딩 규칙·구조·주의사항)을 적어 두면 Claude Code가 매 세션 함께 읽는 파일이다. 하지만 강제되는 설정이 아니다. 코드로 검사받아 막히는 것이 아니라, Claude가 참고하는 지시문일 뿐이라 지킬 수도 있고 놓칠 수도 있다.

그래서 한 파일에 규칙을 계속 쌓으면 역효과가 난다. 파일이 길어질수록 규칙끼리 서로 경쟁하고, 정작 깨지면 곤란한 핵심 지시가 수많은 사소한 지시에 묻혀 덜 정확히 지켜진다. 요령은 '많이 적는 것'이 아니라 '타이트하게 유지하는 것'이다. 아래 다섯 가지가 그 방법이다.

애초에 CLAUDE.md가 맞는 도구인가 — 강제 규칙은 hook으로

터미널에서 hook이 main으로의 push를 'never push to main' 메시지와 함께 차단하는 화면. 프로젝트 레벨 hook이 권한 설정과 무관하게 막는 의도된 가드레일이라는 설명. — hook은 'never push to main'을 실제로 차단한다 — 부탁이 아니라 강제 (Anthropic 공식 영상)

규칙을 적기 전에 먼저 물어야 한다. 이 규칙이 정말 CLAUDE.md에 들어갈 것인가? '절대 main에 직접 push 금지'처럼 반드시 막아야 하는 규칙은 지침이 아니라 pre-tool-use hook에 넣는다. hook은 Claude가 그 동작을 실제로 시도하는 순간 중단시키도록 설계돼 있다. 즉 '지켜 주길 바라는 부탁'이 아니라 '어기면 실제로 막는 차단'이다.

구분은 이렇다. CLAUDE.md 문장은 Claude가 따라 주길 바라는 것이고, hook은 어겼을 때 실제로 멈추는 것이다. 운영 환경 배포, 강제 푸시, 프로덕션 DB 삭제처럼 깨지면 크게 아픈 규칙은 CLAUDE.md 문장에 'IMPORTANT'를 붙여 강조하는 대신 hook으로 옮긴다. 그러면 CLAUDE.md는 그만큼 짧아지고, 강제해야 할 것은 확실히 강제된다.

CLAUDE.md는 네 곳에 있다 — managed·user·project·local

CLAUDE.md가 존재하는 네 위치를 아이콘과 설명으로 정리한 도식 — Managed Policy(조직, 제외 불가), User(개인 전역), Project(팀 공유), Local(git 무시, 이 repo 개인 메모). — CLAUDE.md 네 위치: managed policy·user·project·local — 전부 함께 로드된다 (Anthropic 공식 영상)

CLAUDE.md는 프로젝트 폴더 안 파일 하나만 있는 게 아니다. 네 곳에 있다. managed policy는 조직 차원의 파일로 플랫폼 팀이 관리하고 개인이 제외할 수 없다. user는 내 컴퓨터의 모든 프로젝트에 적용되는 개인 설정이다. project는 팀과 공유하는 프로젝트 파일이다. local은 git이 무시하는, 이 repo에서 나만 보는 개인 메모다.

Claude는 이 메모리 파일들을 전부 함께 로드한다. 무엇도 버려지지 않고, 조직 정책은 항상 적용된다. 그래서 '이번 스프린트에서 리팩터링하는 동안 이 아키텍처 결정을 계속 염두에 둬 줘' 같은 나만의 임시 맥락은 팀 공유 project 파일이 아니라 local에 넣는다. 모두가 봐야 할 규칙과 나만의 임시 메모를 섞지 않는 것이 핵심이다.

@경로 import로 나누되, 무엇을 얻는지 알기

에디터에 열린 CLAUDE.md — 'Split into topic files for readability — all still load at launch'라는 주석과 함께 @.claude/conventions/code-style.md 등 @경로 import 세 줄, 그 아래 ## Rules 섹션. — @경로 import는 정리엔 좋지만 실행 시 인라인으로 펼쳐져 컨텍스트를 줄여 주진 않는다 (Anthropic 공식 영상)

CLAUDE.md가 커지면 @경로 import 문법으로 지침을 여러 파일로 쪼갤 수 있다. 예를 들어 `@.claude/conventions/code-style.md`처럼 적으면 그 파일의 내용이 이 자리에 연결된다. 코드 스타일·테스트·워크플로를 주제별 파일로 나눠 두면 큰 CLAUDE.md를 관리하기 쉬워진다.

단, import가 무엇을 해 주는지 정확히 알아야 한다. Claude는 실행을 시작할 때 import된 파일을 그것을 참조한 파일 바로 옆에 인라인으로 펼쳐 넣는다. 즉 import는 큰 파일을 '정리'하는 데는 도움이 되지만, 어차피 전부 처음에 함께 로드되므로 컨텍스트(토큰) 사용을 줄여 주지는 않는다. '나눴으니 가벼워졌다'는 착각을 하지 말 것 — 정리 효과와 컨텍스트 절감은 다른 이야기다.

표현이 준수를 가른다 — 구체적으로, 대체안을 못박아

CLAUDE.md의 Conventions 목록 — 'Don't use default exports', 'Don't use any', 'Don't put business logic in components' 등 '~하지 마'로만 적힌 규칙들. — 'Don't use default exports'는 대체안이 없어 모호하다 — 'Use named exports'로 못박는 편이 낫다 (Anthropic 공식 영상)

같은 규칙도 어떻게 쓰느냐에 따라 Claude가 따르는 정도가 달라진다. 대부분의 규칙이 실패하는 이유는 모호해서다. 첫째, 구체적이고 검증 가능하게 쓴다. '베스트 프랙티스를 따르라'는 그게 무슨 뜻인지 사람도 정확히 모른다 — Claude가 알아서 지킬 리 없다. 대신 '새 API 라우트는 src/api/handlers에 파일 하나당 하나씩 둔다'처럼 확인할 수 있게 명시한다.

둘째, 금지만 하지 말고 대체안을 이름으로 지목한다. 'default export를 쓰지 마'는 그럼 무엇을 쓰라는지 열어 둔 채라 해석의 여지가 남는다. 'named export를 써라, default export 말고'로 쓰면 오해의 여지를 닫는다. 무엇을 하지 말라고만 하면 Claude가 엉뚱한 대안을 고를 수 있으니, 대신 할 것을 지목한다.

강조는 예산이다 — IMPORTANT를 아껴 써라

CLAUDE.md의 'HARD RULES — DO NOT BREAK THESE' 목록 — 모든 줄이 YOU MUST NEVER, IMPORTANT, CRITICAL 등 대문자 강조로 도배된 화면. — 모든 규칙에 YOU MUST·IMPORTANT를 붙이면 아무것도 강조되지 않는다 — 강조는 두세 개에만 (Anthropic 공식 영상)

강조에도 예산이 있다. IMPORTANT나 YOU MUST는 규칙의 우선순위를 높여 주지만, 어디까지나 주변의 더 조용한 규칙들에 대해 상대적으로 그렇다. 모든 줄에 IMPORTANT·YOU MUST를 붙이면, 결국 아무것도 강조하지 않은 것과 같아진다. 다 외치면 무엇이 진짜 중요한지 사라진다.

그래서 강조는 깨지면 정말 아픈 두세 개의 규칙에만 쓴다. 나머지는 담담한 평서문으로 두고, 반드시 강제해야 하는 것은 (앞서 말한) hook으로 옮긴다. 강조를 아껴 쓸수록 남은 강조가 실제로 힘을 갖는다.

CLAUDE.md도 계속 개정한다 — 틀리면 버그 리포트처럼

터미널에서 사용자가 'Ok, put in the CLAUDE.md file'이라고 입력해, 방금 정한 규칙을 CLAUDE.md에 추가하도록 지시하는 화면. — 잘못을 본 뒤 'CLAUDE.md에 추가해'라고 시키면 Claude가 규칙을 써 준다 (Anthropic 공식 영상)

CLAUDE.md는 한 번 쓰고 끝나는 문서가 아니라 계속 고쳐 나가는 문서다. Claude가 잘못된 동작을 하면, 그것을 CLAUDE.md에 대한 '버그 리포트'로 취급한다. 무엇이 왜 잘못됐는지 본 다음, 'Claude에게 그거 CLAUDE.md에 규칙으로 추가해'라고 말하면 Claude가 그 규칙을 문장으로 대신 써 준다.

이렇게 하면 CLAUDE.md는 실제로 겪은 문제를 바탕으로 조금씩 정교해진다. 상상해서 미리 채워 넣는 규칙보다, 실제 실패에서 뽑아낸 규칙이 훨씬 잘 지켜지고 군더더기도 적다.

결론 — CLAUDE.md를 프로덕션 코드처럼

CLAUDE.md를 프로덕션 코드처럼 다룬다. 한 줄 한 줄이 왜 있는지 정당화할 수 있어야 하고, 정당화하지 못하는 줄은 지운다. 강제해야 할 것은 hook으로 옮기고, 커진 파일은 @경로 import로 정리한다.

그리고 특정 영역에만 해당하는 규칙은 그 영역에서만 로드되도록 범위를 좁힌다(예: 해당 하위 디렉터리의 CLAUDE.md에 두면 그 폴더에서 작업할 때만 함께 읽힌다). 파일이 린할수록, Claude가 그중 더 많은 부분을 따른다. 결국 CLAUDE.md를 지키게 만드는 건 얼마나 많이 적었는가가 아니라 얼마나 절제했는가다.