코딩 에이전트를 진지하게 쓰는 사람의 CLAUDE.md는 대체로 같은 길을 걷습니다. 처음엔 빈 파일이었다가, 사고가 날 때마다 규칙이 한 줄씩 늘고, 어느 날 보면 500줄이 되어 있습니다.

그런데 이상한 일이 벌어집니다. 규칙을 더할수록 에이전트가 규칙을 덜 지킵니다. 분명히 적어놨는데 무시합니다. 그래서 같은 규칙을 더 강한 어조로 다시 적습니다. 굵게 표시하고, 느낌표를 붙이고, “반드시"를 답니다. 그래도 무시합니다.

이 가이드는 CLAUDE.md에 무엇을 넣을지가 아니라 무엇을 뺄지를 다룹니다. 결론부터 말하면, 좋은 CLAUDE.md는 긴 규칙집이 아니라 짧은 헌법입니다. AGENTS.md를 읽는 도구에도 똑같이 적용됩니다.

왜 무거워지는가

경로는 늘 같습니다. 에이전트가 실수합니다. 규칙을 추가합니다. 다른 실수를 합니다. 또 추가합니다.

추가하는 순간에는 언제나 정당합니다. 방금 사고가 났고, 이 문장이 그 사고를 막아줄 테니까요. 문제는 반대 방향에 있습니다. 규칙을 지우는 순간은 영영 오지 않습니다. 지워서 좋아졌는지는 확인하기 어렵고, 남겨둬서 나빠지는 건 천천히 일어나니까요.

그러니 CLAUDE.md는 게을러서 무거워지는 게 아닙니다. 인센티브가 한 방향으로만 걸려 있어서 무거워집니다.

왜 무거우면 나빠지는가

세 가지 원리가 겹칩니다.

컨텍스트는 고정 비용입니다. CLAUDE.md는 모든 세션, 모든 턴에 실려 갑니다. 500줄이면 매 요청마다 500줄 값을 냅니다. 토큰 요금 이야기만이 아닙니다. 모델이 실제 작업에 쓸 주의력을 선불로 떼어가는 비용입니다. 캐싱과 컨텍스트 비용의 구조는 토큰 이코노믹스에서 따로 다뤘습니다.

강조는 나눠 가질수록 옅어집니다. 규칙이 5개면 하나하나가 무겁습니다. 50개면 각각의 무게는 1/50입니다. 전부를 강조하면 아무것도 강조하지 않은 것과 같습니다. “반드시"가 열 번 나오는 문서에서 열한 번째 “반드시"는 장식입니다.

모순은 조용히 처리됩니다. 오래 자란 규칙집에는 서로 부딪히는 조항이 생깁니다. “항상 테스트를 먼저 작성하라"와 “요청받은 최소 변경만 하라"가 한 파일에 있으면, 모델은 충돌을 보고하지 않습니다. 그냥 한쪽을 조용히 버립니다. 어느 쪽을 버릴지는 그때그때 다릅니다. 규칙이 안 지켜진다고 느낀 순간의 상당수가 사실은 이 경우입니다.

넣을 것과 뺄 것

남기는 것은 세 종류면 충분합니다.

  • 코드와 문서에서 알아낼 수 없는 것: 왜 이 구조를 택했는지, 어디에도 명시된 적 없는 팀 관습
  • 매 세션 무조건 적용되는 것: 말투, 언어, 커밋 규칙 같은 상시 원칙
  • 위험 경계: 푸시 금지, 프로덕션 접근 금지처럼 어기면 되돌리기 어려운 것

빼는 것은 네 종류입니다.

  • 코드를 읽으면 아는 것 (디렉토리 구조 설명, 함수 목록)
  • 한 번만 필요했던 지시 (그 태스크가 끝나면 수명도 끝난 것)
  • 특정 상황에서만 필요한 절차 (다음 섹션에서 갈 곳을 정합니다)
  • 모델이 원래 잘하는 것 (“좋은 코드를 작성하라” 류)

리트머스는 한 줄입니다. “이 줄을 지우면 다음 세션에서 실제로 무엇이 나빠지는가?” 구체적인 답이 나오지 않으면 지웁니다.

덜어낸 것들이 갈 곳

빼라고 하면 불안해집니다. 그 규칙들은 전부 사고의 기록인데, 버려도 되나?

버리는 게 아닙니다. 자리를 옮기는 겁니다. CLAUDE.md가 헌법이라면 나머지는 법령입니다. 헌법에는 정체성과 원칙만 남기고, 구체 조항은 필요할 때만 로드되는 곳으로 보냅니다.

  • 상황별 절차 → 스킬(커맨드). “배포할 때는 이 순서로"는 매 턴 실릴 이유가 없습니다. /deploy를 부를 때만 로드되면 충분합니다.
  • 기계적 반복 → 훅. “커밋 전에 린트를 돌려라"는 규칙이 아니라 자동화 대상입니다. 훅은 모델의 기억력과 무관하게 항상 실행됩니다. 기억에 맡길 일과 기계에 맡길 일을 구분하는 게 핵심입니다.
  • 쌓이는 지식 → 메모리. “지난번에 이 버그는 이렇게 잡았다"는 규칙이 아니라 기억입니다. 파일 기반이든 전용 도구든, 검색해서 꺼내 쓰는 층이 따로 있어야 합니다.
  • 프로젝트 사실 → 코드 옆 문서. 아키텍처 설명은 README와 docs가 제자리입니다. 에이전트는 필요할 때 찾아 읽습니다.

이 구조가 생기면 규칙 추가 요청이 올 때마다 물을 질문이 생깁니다. “이건 헌법인가, 법령인가?” 대부분은 법령입니다.

실물: 다이어트 전후

전형적인 다이어트 전 모습입니다.

# CLAUDE.md (발췌 — 다이어트 전, 총 500여 줄)
- 항상 한국어로 답할 것
- src/utils에 헬퍼 함수가 있다. src/components는 UI 컴포넌트,
  src/api는 API 클라이언트, src/hooks는... (구조 설명 40줄)
- 커밋 전에 반드시 npm run lint를 실행할 것
- 배포는 반드시 다음 순서로: 1) 테스트 2) 빌드 3) 스테이징 확인 4) ...
- config.ts를 직접 수정하지 말 것 (2026-05-12 사고 참고)
- 좋은 커밋 메시지를 작성할 것
- ...

다이어트 후에는 이렇게 남습니다. 발췌가 아니라 전문입니다.

# CLAUDE.md (다이어트 후 — 전문)

## 정체성
한국어로, 동료처럼 말한다. 결론을 먼저 쓴다.

## 경계
- main에 직접 푸시하지 않는다. 커밋 전에 확인을 받는다.
- 프로덕션 설정 파일은 읽기만 한다.

## 위임
- 배포 절차: /deploy 스킬
- 커밋 전 린트: 훅이 처리한다 (모델 기억에 의존하지 않음)
- 프로젝트 히스토리와 과거 사고: 메모리에서 검색

사라진 490줄이 어디로 갔는지가 이 가이드의 전부입니다. 구조 설명은 코드 옆 문서로, 배포 순서는 스킬로, 린트는 훅으로, 사고 기록은 메모리로. 없어진 게 아니라 각자 제자리로 갔습니다.

가볍게 유지하는 루틴

  • 사고가 나면 순서를 바꿉니다. “규칙을 추가하자"가 아니라 “이건 어디로 보내야 하나"를 먼저 묻습니다. 스킬인가, 훅인가, 메모리인가. CLAUDE.md는 마지막 선택지입니다.
  • 주기적으로 다이어트합니다. 최근 세션 열 개를 돌아보며 한 번도 발동하지 않은 규칙을 찾습니다. 리트머스를 통과하지 못하면 지웁니다.
  • 상한을 정합니다. 저는 화면 한 장을 기준으로 삼습니다. 스크롤이 생기면 무언가를 내보낼 때가 된 겁니다.

체크리스트

CLAUDE.md를 열고 다섯 가지만 확인해보세요.

  1. 지우면 다음 세션이 실제로 나빠지는 줄만 남았는가
  2. 코드를 읽으면 알 수 있는 설명이 들어 있지 않은가
  3. “반드시"가 세 번 이상 나오지 않는가
  4. 서로 부딪히는 조항이 없는가
  5. 화면 한 장을 넘지 않는가