CLAUDE.md는 코딩 에이전트가 매 턴 통째로 읽어 들이는 프로젝트 메모리 파일이다. 이 헌법을 ‘언제 로드되는가’ 기준으로 법률(문서)·시행령(커맨드)과 갈라 짧게 유지할수록, 에이전트는 규칙을 더 일관되게 지킨다.
코딩 에이전트에게 "자동 생성되는 파일은 손대지 마"라고 규칙을 적어 둔다. 그런데 며칠 뒤, 에이전트는 그 파일을 또 고쳐 놓는다.
규칙을 못 봐서가 아니다. 그 규칙은 CLAUDE.md에 또렷이 적혀 있고, 에이전트는 매 턴 그 파일을 읽는다. 그런데도 어긴다. 더 이상한 건, 이런 일이 생길 때마다 규칙을 한 줄씩 더 적어 넣으면 개별 규칙이 오히려 더 안 지켜진다는 것이다. 왜 그런지는 이 파일이 언제, 어떻게 읽히는지를 들여다보면 드러난다.
프로젝트 메모리, 왜 매 턴 통째로 불려오나
CLAUDE.md는 코딩 에이전트의 프로젝트 메모리다. 에이전트가 새 작업을 받을 때마다, 이 파일은 요청과 함께 통째로 프롬프트 맨 앞에 실린다. 스펙 문서나 슬래시 커맨드처럼 필요할 때만 펼쳐 보는 참고 자료가 아니다 — 매 턴, 예외 없이, 처음부터 끝까지 읽힌다.
그래서 여기에 규칙을 한 줄 더 적는 일은 공짜가 아니다. 지금 하려는 작업이 커밋 메시지를 다듬는 일이든 테스트를 고치는 일이든, 에이전트는 그 순간 아무 상관없는 규칙까지 전부 함께 읽는다. 파일이 100줄이면 그 100줄이 매 요청마다 맨 앞자리를 차지한다. 그런데 그중 지금 작업과 정말 관련된 규칙은 서너 줄뿐인 경우가 대부분이다.
나머지는 노이즈다. 그리고 노이즈가 늘수록 신호는 묻힌다. 불변의 원칙과 특정 작업의 세부 절차와 가끔 필요한 참고 정보가 한 파일에 뒤섞여 있으면, 에이전트에게는 무엇이 절대 어기면 안 되는 규칙이고 무엇이 상황 따라 달라지는 세부인지 가를 근거가 없다. 그러니 파일이 길어지는 게 문제가 아니다. 길어진 파일 전체가 매번 함께 로드된다는 게 진짜 문제다.
"언제 로드되는가", 그 질문 하나로 3층을 가른다
그렇다면 무엇을 남기고 무엇을 덜어낼까. 흔히 우리는 ‘무엇이 더 중요한가’로 규칙을 고르려 한다. 하지만 그 기준으로는 아무것도 못 덜어낸다 — 적어 둔 규칙은 다 나름대로 중요하기 때문이다. 그래서 기준을 바꾼다. 중요도가 아니라 ‘이 지식이 언제 읽혀야 하는가’로 묻는 것이다.
이 질문 하나로 프로젝트 메모리는 세 층으로 갈린다. 법 체계가 이미 오래전에 풀어 둔 구도이기도 하다.
- 헌법: 항상 필요한 것. 어떤 작업에서도 배경이 되는 불변 원칙과 라우팅 포인터다. CLAUDE.md 자체가 이 자리다.
- 법률: 특정 작업에서만 필요한 것. 노드 작성 규격이나 빌드 명세 같은 상세는 스펙 문서(
docs/)에 두고, 그 작업을 할 때만 펼친다. - 시행령: 반복 절차. 수집·검증 워크플로우의 단계와 통과 기준은 슬래시 커맨드·스킬 파일에 고정해, 그 명령을 부를 때만 로드한다.
세 층은 로드되는 시점이 서로 다르다. 헌법은 늘, 법률은 그 작업에서만, 시행령은 그 명령을 부를 때만 읽힌다. 그림 1가 이 갈래를 한눈에 보여준다 — 하나의 CLAUDE.md에서 세 방향으로 뻗는 가지에, 각 가지가 언제 로드되는지가 붙어 있다.
세 층을 가르는 기준은 그러니까 하나뿐이다. 무엇이 더 중요하냐가 아니라, 언제 읽혀야 하느냐.
실물 85줄을 펼쳐 보면
이 구도가 추상론이 아니라 실물에서 어떻게 생겼는지 보자. 실제로 운영 중인 한 도메인 지식그래프 프로젝트의 CLAUDE.md가 손에 있다. 도메인이 복잡한 멀티에이전트 시스템의 지식 레이어인데도, 이 헌법은 85줄이다. 구조는 여덟 섹션으로 나뉜다 — 프로젝트 정체성 두세 문장, 절대 원칙 일곱 항, 문서 지도, 디렉토리 지도, 검증 명령어, 알려진 함정, 작업 흐름, 그리고 하지 말 것.
헌법을 짧게 유지하는 진짜 장치는 세 번째 ‘문서 지도’다. 왼쪽이 작업 종류, 오른쪽이 읽어야 할 문서인 두 열짜리 표인데, 작업 열두 종을 스펙 문서 열두 개로 곧장 이어 준다. 노드 작성법의 상세 규격을 헌법에 적었다면 그것만 수백 줄이 됐을 것이고, 그 수백 줄은 빌드 스크립트만 손보는 작업에서도 매 턴 실렸을 것이다. 대신 헌법은 "노드를 만들려거든 이 문서를 읽어라"는 한 줄짜리 포인터만 갖는다. 상세는 법률에 있고, 법률은 그 작업에서만 펼쳐진다.
헌법 몫은 이렇게 85줄뿐이다. 그런데 그 85줄 안에 프로젝트 판단의 축 대부분이 들어 있다.
굵은 단언에는 짧은 근거가 붙는다
그 축이 가장 또렷하게 드러나는 자리가 절대 원칙이다. 일곱 항을 하나씩 뜯어보면 공통된 문형이 보인다. 전부 ‘굵은 단언 + 짧은 근거’ 형태다. 예를 들어 이 프로젝트의 일곱 번째 원칙은 이렇게 시작한다.
외부 라이브러리는 vendoring. 사내망 배포를 위해 CDN 런타임 의존 금지, viewer/vendor/에 커밋.
"CDN 런타임 의존 금지"만 있으면 에이전트는 처음 보는 외부 라이브러리를 들일 때 흔들린다. 이게 정말 금지 대상인지, 예외는 아닌지 판단할 근거가 없기 때문이다. 그런데 "사내망, 곧 외부 네트워크가 없는 환경에 배포하기 위해서"라는 근거가 붙으면, 처음 보는 의존성 앞에서도 같은 결론에 도달한다. 이 코드가 외부 네트워크에 기대는가? 그렇다면 vendor로 들여온다.
근거가 하는 일이 이것이다. 근거 없는 규칙은 적어 둔 그 상황에서만 작동하는 낱개 지시다. 반면 근거 있는 규칙은 처음 보는 상황에도 응용되는 판단의 축이 된다. 원칙이 규칙의 나열이 아니라 판단의 축이어야 한다는 말은, 실무에서는 규칙마다 ‘왜’를 한 조각씩 달아 두라는 말과 같다.
"하지 말 것" 목록은 판례집이다
그런데 이 헌법에는, 근거를 단 원칙과 성격이 아예 다른 목록이 하나 더 있다. 여덟 섹션의 마지막에 놓인 "하지 말 것 (반복 주의)"이라는 부정형 목록이다. 역시 일곱 줄인데, 이게 절대 원칙과 따로 떨어져 있다는 점이 이 설계에서 가장 흥미로운 대목이다.
목록의 각 줄은 대개 원칙에서 자명하게 도출되는 것들이다. ‘INDEX.md는 자동 생성 파일’이라는 원칙이 있으면 ‘INDEX.md 수동 편집 금지’는 당연히 따라 나온다. 그런데도 왜 굳이 다시 적는가. 에이전트가 원칙에서 그 결론을 매번 도출하지는 못하기 때문이다. ‘자동 생성 파일’이라는 추상 원칙을 읽고도, 막상 그 파일에서 오타를 발견하면 그냥 고쳐 버리는 일이 생긴다. 추상 원칙과 구체 행동 사이엔 틈이 있고, 사고는 늘 그 틈에서 난다.
하지 말 것 목록은 그 틈에서 실제로 벌어진 사고를 하나씩 구체 금지 행동으로 못박은 것이다. 제목에 붙은 ‘(반복 주의)’가 그래서 핵심이다. 이건 헌법이 스스로 겪어 낸 판례집에 가깝다.
그래서 이 목록은 미리 상상해서 채우는 게 아니다. ‘이런 것도 금지해야지’ 하며 앞서 채우면, 그 예측 목록이 다시 노이즈가 되어 헌법을 불린다. 에이전트를 굴리다가 같은 실수가 두 번 반복되면 — 그때 한 줄 추가한다. 이 목록의 자격은 상상이 아니라 관찰에서 나온다.
절대 원칙이 설계 시점에 세운 상위 규범이라면, 하지 말 것은 사후에 관찰로 채워지는 목록이다. 예측의 기록이 아니라 관찰의 기록인 셈이다.
법률과 시행령, 커맨드에 박히는 기계 게이트
헌법이 짧을 수 있는 건 나머지 두 층이 각자 몫을 지기 때문이다. 법률에 해당하는 스펙 문서는 그 작업만의 상세 절차를 담되, 헌법 내용을 복붙하지 않는다. 상위 규율은 "정본은 헌법을 보라"는 포인터로만 가리키고, 자기는 얇게 유지한다. 스펙이 헌법을 재수록하기 시작하면 두 파일이 어긋날 씨앗이 심긴다.
시행령인 커맨드 파일은 한 걸음 더 나간다. 반복 워크플로우의 절차를 프롬프트가 아니라 파일에 고정한다. 채팅으로 매번 "이런 순서로 수집하고 이런 기준으로 통과시켜라"라고 지시하면, 그 지시는 세션마다 조금씩 달라진다. 어제는 통과 기준을 다섯 개 말했는데 오늘은 세 개만 말하는 식이다. 이 프로젝트의 수집 커맨드는 절차와 함께 기계 게이트 열 항을 파일에 못박아, 누가 언제 부르든 같은 검사를 거치게 한다. 게이트는 "좋은 문서를 저장하라" 같은 모호한 지시가 아니라, 필수 필드가 다 있는가·아이디가 규약에 맞는가처럼 예/아니오로 답할 수 있는 형태로 쓰여 있다.
한 가지가 더 있다. 이 게이트에는 판정 기본값이 명시돼 있다 — "애매하면 실패 쪽으로". 회색지대에서 에이전트가 어느 쪽으로 기울지를 정해 주지 않으면 결과가 세션마다 요동친다. 이 한 줄이 그 요동을 없앤다.
세 층으로 나누면 새 위험이 하나 생긴다. 같은 규율이 여러 파일에 복제되는 것이다. 소스 등급 기준 같은 규율이 헌법에도 있고 커맨드에도 있고 스펙에도 있으면, 하나를 고칠 때 나머지를 빠뜨리고 결국 파일마다 미묘하게 다른 규칙이 공존하게 된다. 그 순간 에이전트는 어느 것을 믿어야 할지 알 수 없다.
해법은 정본 포인터다. 규율을 여러 곳에서 참조하되, 각 사본 맨 위에 "진짜는 여기다"를 박아 둔다. 복제 자체를 금지하는 게 아니라, 복제에 방향을 부여하는 것이다 — 어느 쪽이 진짜인지.
이 세 층을 관통하는 정신은 결국 하나다. 반복되는 절차는 사람이 그날그날 기억해 내는 게 아니라, 파일에 고정된 게이트가 대신 결정한다.
짧을수록 더 지켜진다는 역설
이제 처음 질문으로 돌아가자. 헌법을 짧게 유지한다는 건 규칙을 버린다는 뜻이 아니다. 특정 작업에서만 필요한 상세는 법률로 내리고, 반복 절차는 시행령으로 옮기고, 헌법에는 포인터 한 줄만 남기는 일이다. 규칙의 총량은 그대로다. 다만 각 규칙이 자기가 로드될 자격이 있는 자리로 옮겨 갈 뿐이다.
그 결과가 그림 2에 담겨 있다. 왼쪽은 규칙을 전부 욱여넣은 긴 헌법이다. 지금 이 작업과 관련된 규칙은 몇 줄뿐이라 밝게 빛나지만, 나머지는 회색 노이즈로 화면을 채운다. 오른쪽은 상세를 덜어낸 짧은 헌법이다. 남은 줄 거의 전부가 지금 판단과 관련돼 밝다. 매 턴 로드되는 것 대비 지금 쓸모 있는 것의 비율, 곧 신호 대 노이즈 비율이 올라간 것이다.
짧은 헌법이 더 잘 지켜지는 이유가 여기 있다. 규칙이 적어서가 아니라, 매 턴 읽히는 것 중 지금 쓸모 있는 것의 밀도가 높아서다. 덜 적었는데 더 지켜지는 역설은 그러니까 사실 역설이 아니다.
지금 쓰는 CLAUDE.md를 열어 놓고 다섯 가지를 물어보면, 어디를 덜어낼지 곧 드러난다.
- 절반 이상이 특정 작업에서만 필요한 내용인가? 그렇다면 그 절반을 스펙 문서로 내리고, 헌법엔 "그 작업엔 이 문서를 읽어라" 포인터 한 줄만 남긴다.
- 절대 원칙에 ‘왜’가 붙어 있는가? 근거 없는 금지는 처음 보는 상황에서 응용되지 않는다.
- 반복해서 어긴 것들이 ‘하지 말 것’에 구체적 행동으로 적혀 있는가? 단, 상상으로 미리 채우지는 않는다 — 두 번 어긴 것만.
- 반복 작업의 절차가 채팅이 아니라 커맨드·스킬 파일에 있는가? 판정이 필요한 절차라면 ‘애매하면 어느 쪽’이라는 기본값까지.
- 같은 규율이 여러 파일에 복제됐는데 정본 표시가 없는가? 있다면 지금 이미 어긋나 있거나 곧 어긋난다.
CLAUDE.md를 잘 쓴다는 건 규칙을 많이 적는 게 아니다. 매 턴 로드될 자격이 있는 것만 헌법에 남기고, 나머지는 필요한 순간에만 펼쳐지도록 자리를 잡아 주는 일이다.
더 읽기
- Anthropic, "Best practices for Claude Code" — Claude Code 공식 문서의 CLAUDE.md 실무 권고(200줄 이하 유지·비대해진 파일은 규칙이 묻힌다). https://code.claude.com/docs/en/best-practices
- Anthropic Engineering, "Effective context engineering for AI agents" (2025) — 컨텍스트를 양이 아니라 신호 위주로 관리하는 원칙. https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
- Anthropic, Claude Code 문서 "How Claude remembers your project" — CLAUDE.md의 로드 방식과 프로젝트·유저 메모리 계층. https://code.claude.com/docs/en/memory