CLAUDE.md, 쓰는 게 맞습니까 - 논문이 뒤집은 상식과 실전 가이드

2월 마지막 주, 개발자 커뮤니티가 술렁였습니다. ETH Zurich 연구팀이 발표한 논문 한 편 때문입니다. "AGENTS.md 파일이 AI 코딩 에이전트의 성능을 오히려 떨어뜨린다." 이 한 줄이 Hacker News와 Reddit을 뒤덮었습니다.

혼란스러울 만합니다. Claude Code 사용자라면 CLAUDE.md를 정성스럽게 작성해 왔을 겁니다. "500줄 이내로 유지하세요", "프로젝트의 핵심 맥락을 담으세요" 같은 가이드를 따르면서요. 그런데 논문이 나와서 "그거 오히려 해롭다"고 합니다.

논문을 직접 읽고, 관련된 후속 분석들도 찾아봤습니다. Google Chrome팀의 Addy Osmani, Martin Fowler, HumanLayer, Engineer's Codex까지. 결론부터 말하면, "CLAUDE.md를 쓰지 마라"가 아닙니다. "잘못 쓰면 안 쓰느니만 못하다"입니다. 그 차이가 큽니다.

논문이 실제로 말한 것

먼저 논문을 정확히 짚어야 합니다. 커뮤니티에서 돌아다니는 요약이 원문과 꽤 다르기 때문입니다.

관련 논문은 두 편입니다. 첫 번째는 Singapore Management University와 Heidelberg University 연구팀의 "On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents"(arxiv 2601.20404)이고, 두 번째가 ETH Zurich의 "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?"(arxiv 2602.11988)입니다. 커뮤니티에서 파장이 컸던 건 두 번째 논문인데, 흥미롭게도 두 논문의 결론이 표면적으로는 반대입니다.

논문 1: "효율성은 올라간다"

Singapore/Heidelberg 연구팀은 OpenAI Codex(gpt-5.2-codex)를 써서, 10개 GitHub 저장소의 124개 Pull Request에 대해 AGENTS.md가 있을 때와 없을 때를 비교했습니다.

AGENTS.md가 있으면 실행 시간이 중앙값 기준 28.64% 줄고, 출력 토큰이 20.08% 감소했습니다. 통계적으로도 유의미하고요(Wilcoxon signed-rank test, p<0.05). 에이전트가 "더 빨리" 작업을 끝냈다는 뜻입니다.

여기서 한 가지 빠진 게 있습니다. 이 논문은 효율성만 측정했습니다. 에이전트가 빨리 끝냈는데, 그 결과가 맞는지는 안 봤습니다.

논문 2: "정확도는 내려간다"

ETH Zurich 논문이 바로 그 빈 자리를 채웁니다. 이 논문은 4개 모델(Claude Code + Sonnet 4.5, Codex + GPT-5.2, Codex + GPT-5.1 mini, Qwen Code + Qwen3-30b)을 써서, 자체 구축한 AGENTbench(12개 저장소, 138개 태스크)와 SWE-bench Lite(300개 태스크)에서 태스크 성공률을 측정했습니다.

실험 조건은 세 가지로, 컨텍스트 파일이 없는 경우(None), LLM이 자동 생성한 컨텍스트(LLM), 인간이 직접 작성한 컨텍스트(Human)입니다.

결과를 직접 보겠습니다.

SWE-bench Lite 성공률 변화 (LLM 생성 컨텍스트 사용 시)

8개 테스트 설정 중 5개에서 성공률이 떨어졌고, 비용은 20~23% 늘었습니다.

그런데 인간이 직접 작성한 컨텍스트는 달랐습니다. AGENTbench에서 평균 +4% 성공률 향상이 있었습니다. 138개 태스크 기준으로 보면 약 5~6개 태스크를 추가로 성공시킨 결과입니다. 숫자 자체는 크지 않지만, 마크다운 파일 하나 추가해서 얻는 효과치고는 꽤 괜찮은 셈입니다. 비용도 19% 늘었지만, 성공률이 올라갔으니 충분히 감수할 만하고요.

두 논문을 같이 놓으면

정리하면 이렇습니다. AGENTS.md(CLAUDE.md)가 있으면 에이전트는 "더 빨리" 작업을 마칩니다. 하지만 LLM이 자동 생성한 파일은 "더 부정확하게" 끝냅니다. 빨리 끝내는데 틀리는 건, 안 쓰느니만 못합니다. 반면 인간이 직접 쓴 최소한의 컨텍스트는 정확도도 올립니다.

"CLAUDE.md가 해롭다"가 아니라 "자동 생성된 CLAUDE.md가 해롭다"가 정확한 결론입니다.

다음 그림은 두 논문의 핵심 발견을 정리한 것입니다.

논문 1은 AGENTS.md가 에이전트의 실행 속도를 높인다는 것을 밝혔고, 논문 2는 LLM이 자동 생성한 컨텍스트가 정확도를 떨어뜨리는 반면 인간이 직접 작성한 컨텍스트는 정확도를 올린다는 것을 확인했습니다. 속도와 정확도를 동시에 보면, 핵심은 "누가 썼느냐"입니다.

왜 자동 생성이 해로운가

claude init이나 /init 같은 명령으로 생성된 CLAUDE.md가 왜 문제일까요. ETH Zurich 논문이 원인을 세 가지로 분석합니다.

첫째, 기존 문서와 중복됩니다. 잘 관리된 오픈소스 프로젝트에는 이미 README, CONTRIBUTING.md, pyproject.toml, package.json 같은 파일이 있습니다. LLM이 생성한 컨텍스트 파일은 이런 기존 문서의 내용을 다시 정리한 것에 불과합니다. 에이전트가 이미 읽을 수 있는 정보를 시스템 프롬프트에 중복해서 넣는 격이니, 토큰만 낭비됩니다.

실제로 LLM 생성 컨텍스트의 95~100%가 코드베이스 개요를 포함하고 있었습니다. "이 프로젝트는 Python으로 작성되었고, src/ 디렉토리에 소스 코드가 있습니다" 같은 내용입니다. 에이전트는 ls와 cat으로 이걸 직접 파악할 수 있습니다. 굳이 알려줄 필요가 없습니다.

둘째, 불필요한 작업을 유발합니다. 여기서 눈에 띄는 부분이 있는데, 에이전트가 컨텍스트 파일에 언급된 도구를 1.6배 더 자주 사용한다는 겁니다. 예를 들어 "이 프로젝트는 uv를 패키지 관리자로 사용합니다"라고 적어두면, 에이전트가 uv를 호출하는 빈도가 늘어납니다. 문제는, 이게 태스크 성공률 향상으로 이어지지 않는다는 겁니다. 지시를 충실히 따르지만, 그 지시 자체가 해당 태스크에 불필요한 경우가 많습니다.

셋째, 태스크 복잡도를 높입니다. "모든 코드에 타입 힌트를 추가하세요", "docstring을 작성하세요" 같은 코딩 스타일 지시가 컨텍스트 파일에 들어가면, 에이전트가 버그 수정이라는 본래 태스크에 더해 스타일 요구사항까지 동시에 충족하려 합니다. 에이전트가 이것저것 신경 쓰다 보니 정작 중요한 작업의 정확도가 떨어집니다.

다음 그림은 자동 생성된 컨텍스트가 해로운 세 가지 이유를 정리한 것입니다.

기존 문서와의 중복, 불필요한 도구 호출 유발, 태스크 복잡도 증가. 세 가지 모두 "에이전트가 이미 알 수 있는 정보를 굳이 다시 알려준" 데서 비롯됩니다.

한 가지 예외가 있습니다. 기존 문서가 거의 없는 저장소에서는 LLM 생성 컨텍스트도 +2.7% 성능 향상을 보였습니다. "CLAUDE.md 쓰니까 확실히 좋아졌다"는 후기 대부분이 바로 이 경우입니다. 문서가 부실한 프로젝트에서 AI가 대신 정리해주니 도움이 된 겁니다. 하지만 이건 CLAUDE.md의 효과가 아니라, 부족한 문서화를 보충한 효과입니다.

커뮤니티의 반응: 양극단 사이에서

이 논문이 나온 뒤 개발자 커뮤니티의 반응은 크게 세 갈래로 나뉘었습니다.

"그럼 다 지우자" 파

Hacker News에서 tomashubelbauer는 이렇게 말했습니다. "AGENTS.md에 규칙을 적어봤자 에이전트가 일상적으로 무시합니다. TypeScript AST 검증, pre-commit hook, 린터로 프로그래밍적으로 강제하는 게 유일하게 신뢰할 수 있는 방법입니다."

일리가 있습니다. "main 브랜치에 push하지 마세요"를 CLAUDE.md에 적어도 Claude가 100% 따른다는 보장은 없습니다. hooks로 막으면 100% 차단됩니다. Anthropic 공식 문서도 인정합니다. "프롬프트는 제안이고, 훅은 보장입니다."

"그래도 필요하다" 파

반대편에서는 deaux가 이렇게 반박했습니다. "단순한 마크다운 파일 하나로 4% 성능 향상이면, 그건 사실 '엄청난' 겁니다. 비공개 소스, 특수 도메인 프로젝트에서 진가를 발휘합니다."

이것도 맞습니다. ETH Zurich 논문은 오픈소스 Python 프로젝트만 테스트했습니다. 사내 코드베이스, 독자적인 프레임워크, 특수한 배포 환경 같은 곳에서는 에이전트가 자체적으로 파악할 수 없는 정보가 훨씬 많습니다. 이런 환경에서 컨텍스트 파일의 가치는 논문 수치보다 클 수 있습니다.

"쓰되 다르게 쓰자" 파

Google Chrome팀의 Addy Osmani가 "Stop Using /init for AGENTS.md"를 발표하며 절충안을 제시했습니다. 핵심은 이렇습니다. "에이전트가 코드베이스를 읽어서 알 수 있는 정보는 넣지 마세요. 코드를 읽어도 알 수 없는 정보만 넣으세요."

Osmani는 이를 "코드 탐색만으로는 파악하기 어려운(non-discoverable) 정보"라고 부릅니다. "uv로 패키지 관리합니다"는 pyproject.toml을 보면 알 수 있으니 발견 가능합니다. "테스트 시 --no-cache 플래그가 필수입니다"는 코드 어디에도 적혀있지 않으니 비발견 가능합니다.

Osmani는 여기서 한 발 더 나갑니다. "AGENTS.md를 코드베이스 명확성 문제의 진단 도구로 취급하세요. 결국 삭제할 수 있는 파일이 가장 좋은 컨텍스트 파일입니다." CLAUDE.md에 뭔가를 적어야 한다면, 그건 코드베이스 자체가 불명확하다는 신호라는 뜻입니다.

Anthropic은 뭐라고 하나

논문 결과와 Anthropic 공식 가이드를 나란히 놓으면 꽤 겹칩니다.

Anthropic 공식 Best Practices 문서에 이런 문장이 있습니다. "Keep it concise. For each line, ask: 'Would removing this cause Claude to make mistakes?' If not, cut it." 한 줄 한 줄에 대해 "이걸 빼면 Claude가 실수하는가?"를 물어보라는 겁니다. 답이 "아니오"면 지우라고 합니다.

더 직접적인 경고도 있습니다. "Bloated CLAUDE.md files cause Claude to ignore your actual instructions!" CLAUDE.md가 비대해지면 정작 중요한 지시가 묻힌다는 뜻입니다. ETH Zurich 논문의 결론과 정확히 같은 이야기입니다.

Anthropic이 포함하라고 권장하는 항목을 보면 이렇습니다.

• Claude가 추측할 수 없는 Bash 명령어와 도구 사용법
• 프로젝트의 표준과 다른 코드 스타일 규칙
• 테스트 실행 방법과 관련 지시
• 중요한 아키텍처 결정사항

반대로 빼라고 하는 항목입니다.

• 코드를 읽으면 알 수 있는 것
• 표준 언어 관례
• 상세한 API 문서
• 자주 변하는 정보
• 파일별 코드베이스 설명

결국 Anthropic도 "코드베이스 개요를 쓰지 마라"고 말하고 있었습니다. 논문이 새로운 사실을 밝힌 게 아니라, 공식 가이드를 따르지 않았을 때 어떤 일이 벌어지는지를 수치로 증명한 겁니다.

실전 가이드: CLAUDE.md를 제대로 쓰는 법

논문, 커뮤니티 반응, 공식 가이드, 실무 사례를 바탕으로 정리해 보겠습니다.

원칙 1: 빈 파일에서 시작합니다

claude init으로 자동 생성하지 않습니다. 빈 CLAUDE.md에서 시작하세요.

Upsun Developer Center의 가이드가 이 원칙을 가장 잘 표현합니다. "모든 줄이 실제 문제를 해결했기 때문에 존재해야 합니다. 모범 사례 가이드에서 포함하라고 했기 때문이 아닙니다."

Claude Code로 작업하다가 Claude가 같은 실수를 두 번 이상 반복하면, 그때 CLAUDE.md에 해당 규칙을 추가하면 됩니다. .gitignore를 관리하는 것과 같은 방식입니다. 필요할 때만, 구체적인 문제에 대응해서, 한 줄씩 추가합니다.

원칙 2: "이걸 빼면 Claude가 실수하는가?" 테스트를 적용합니다

CLAUDE.md의 모든 줄에 이 질문을 던지세요.

• "이 프로젝트는 TypeScript로 작성되었습니다" → 빼도 됩니다. tsconfig.json을 보면 압니다.
• "src/ 디렉토리에 소스 코드가 있습니다" → 빼도 됩니다. ls로 알 수 있습니다.
• "테스트는 pnpm test -- --run --reporter=verbose 로 실행합니다" → 빼면 안 됩니다. package.json의 test 스크립트와 다른 옵션이 필요하기 때문입니다.
• "환경 변수 DB_URL이 설정되어 있어야 마이그레이션이 작동합니다" → 빼면 안 됩니다. 코드만 봐서는 알기 어렵습니다.

원칙 3: 200줄을 넘기지 않습니다

Anthropic이 권장하는 상한은 200줄입니다. HumanLayer는 300줄 미만을 권장하면서 자사 루트 파일은 60줄 미만으로 유지하고 있습니다.

HumanLayer의 분석에 따르면, 프론티어 LLM이 안정적으로 따를 수 있는 지시 수는 150~200개입니다. Claude Code 시스템 프롬프트에 이미 약 50개의 내장 지시가 포함되어 있으므로, CLAUDE.md에 쓸 수 있는 유효한 지시 수는 100~150개입니다. 이걸 넘기면 지시 간 충돌이나 무시가 발생할 확률이 높아집니다.

이전에 500줄 이내라는 가이드를 소개한 적이 있는데, 논문 결과와 최신 공식 권장사항을 종합하면 200줄이 더 적절합니다. 줄여야 합니다.

원칙 4: 넣어야 할 것과 빼야 할 것을 구분합니다

넣어야 하는 것 (비발견 가능한 정보)

복사
# 빌드 & 테스트
- 패키지 관리: pnpm (npm, yarn 사용 금지)
- 단일 테스트 실행: pnpm test -- --run -t "테스트명"
- 빌드 전 반드시 타입체크: pnpm typecheck

# 코드 스타일 (표준과 다른 부분만)
- 컴포넌트 파일명: PascalCase.tsx
- 유틸리티 파일명: camelCase.ts
- 커밋 메시지: 한글, "동사+목적어" 형식

# 아키텍처 결정
- 상태관리: Zustand (Redux 사용 금지, 마이그레이션 중)
- API 호출: src/lib/api-client.ts의 래퍼만 사용

# 배포
- main 브랜치 직접 push 금지
- PR 머지 시 자동 배포 (Vercel)

빼야 하는 것 (발견 가능한 정보)

복사
# 이런 건 쓰지 마세요
- "이 프로젝트는 Next.js 14를 사용합니다" → package.json에 있습니다
- "src/components/에 React 컴포넌트가 있습니다" → 디렉토리 구조를 보면 압니다
- "ESLint와 Prettier를 사용합니다" → .eslintrc와 .prettierrc가 있습니다
- "데이터베이스는 PostgreSQL입니다" → 의존성과 설정 파일에서 파악 가능합니다
- 함수별 API 문서 → 코드와 타입 정의에서 읽을 수 있습니다

원칙 5: 계층을 활용합니다

모든 걸 루트 CLAUDE.md에 넣지 마세요. Claude Code는 계층적 메모리를 지원합니다.

복사
~/.claude/CLAUDE.md              → 개인 전역 설정 (모든 프로젝트 공통)
./CLAUDE.md                      → 프로젝트 핵심 규칙 (팀 공유)
./.claude/rules/testing.md       → 테스트 관련 규칙 (조건부 로드 가능)
./.claude/rules/api-design.md    → API 설계 원칙 (조건부 로드 가능)
./packages/frontend/CLAUDE.md    → 프론트엔드 전용 규칙 (해당 디렉토리 작업 시만 로드)

.claude/rules/ 디렉토리에 YAML 프론트매터로 조건을 걸 수 있습니다.

복사
---
paths:
  - "**/*.test.ts"
  - "**/*.spec.ts"
---
# 테스트 작성 규칙
- 테스트 파일당 하나의 describe 블록
- mock은 vi.mock() 사용
- 테스트 설명은 한글로 작성

이렇게 하면 테스트 파일을 다룰 때만 이 규칙이 로드됩니다. 루트 CLAUDE.md의 줄 수를 줄이면서 필요한 곳에 정확한 지시를 줄 수 있습니다.

원칙 6: 린터 역할을 시키지 않습니다

HumanLayer의 표현을 빌리면 이렇습니다. "LLM에게 린터 역할을 시키지 마세요. LLM은 비교적 비싸고 느립니다."

"세미콜론을 빠뜨리지 마세요", "들여쓰기는 2칸으로 하세요", "import 순서를 지켜주세요" 같은 규칙은 CLAUDE.md에 쓸 게 아닙니다. ESLint, Prettier, pre-commit hook으로 강제하세요. 토큰당 비용을 들여서 할 일이 아닙니다.

Anthropic 공식 문서도 같은 말을 합니다. "프롬프트는 제안이고, 훅은 보장입니다." 반드시 지켜야 하는 규칙이라면 hooks로 막아야 합니다.

복사
// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git push)",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'echo \"main 브랜치 push를 차단했습니다\" && exit 1'"
          }
        ]
      }
    ]
  }
}

원칙 7: Auto Memory와 역할을 분리합니다

Claude Code에 2026년 2월 Auto Memory 기능이 추가되면서, CLAUDE.md와의 역할 분리가 가능해졌습니다.

CLAUDE.md에는 팀이 합의한 규칙을 적습니다. "커밋 메시지는 한글로", "pnpm만 사용" 같은 안정적이고 공유 가능한 지시입니다. Git으로 버전 관리되고 팀 전체가 동일한 규칙을 공유합니다.

Auto Memory(MEMORY.md)에는 Claude가 작업하면서 스스로 발견한 지식이 쌓이고요. "빌드 시 NODE_ENV=production 필요", "이 프로젝트의 JWT 검증은 src/utils/auth.ts에 있음" 같은 실무 지식입니다. 로컬에만 저장되고 Git에 올라가지 않습니다.

이전에 CLAUDE.md에 넣었던 "코드베이스 개요"나 "디렉토리 구조 설명" 같은 내용은 이제 빼도 됩니다. Claude가 필요하면 직접 탐색하고, 자주 참조하는 정보는 Auto Memory에 알아서 기록하니까요.

CLAUDE.md를 쓰지 않는 대안

논문 결과를 극단적으로 해석하면 "CLAUDE.md를 아예 안 쓰면 되지 않나?"라는 질문이 나오는데, 실제로 일부 개발자가 이 방향을 선택하고 있습니다.

대안 1: hooks + 린터로 모든 규칙을 강제합니다

CLAUDE.md 없이, 모든 코딩 규칙을 도구로 강제하는 방식입니다. 앞서 본 PreToolUse가 "하면 안 되는 것"을 차단한다면, PostToolUse는 "해야 하는 것"을 자동화합니다.

복사
// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\" && npx prettier --write \"$CLAUDE_FILE_PATH\""
          }
        ]
      }
    ]
  }
}

Claude가 파일을 수정할 때마다 ESLint와 Prettier가 자동으로 실행됩니다. hooks에 전달되는 환경변수의 정확한 이름과 사용법은 Claude Code 버전에 따라 달라질 수 있으므로, 적용 전에 공식 문서를 확인하세요. 어떤 방식이든 핵심은 같습니다. CLAUDE.md에 스타일 규칙을 적는 것보다 도구로 강제하는 편이 확실합니다.

대안 2: README와 기존 설정 파일을 충실히 관리합니다

논문의 핵심 발견 중 하나는, 기존 문서가 충실한 프로젝트에서는 컨텍스트 파일이 필요 없다는 점입니다. README.md에 빌드 방법, 테스트 방법, 기여 가이드를 명확히 적어두면, Claude는 그걸 알아서 읽습니다.

package.json의 scripts, tsconfig.json, .eslintrc, Dockerfile 같은 설정 파일도 마찬가지입니다. 이 파일들이 프로젝트의 규칙을 이미 정의하고 있습니다. CLAUDE.md에 따로 적을 필요가 없습니다.

대안 3: AGENTS.md 표준을 사용합니다

도구 하나에 종속되기 싫다면 AGENTS.md를 고려할 수 있습니다. Linux Foundation 산하 Agentic AI Foundation이 관리하는 공개 표준으로, OpenAI Codex, Cursor, Google Jules, Amp, Factory 등 20개 이상의 도구가 지원합니다. GitHub에서만 60,000개 이상의 저장소가 채택했습니다.

AGENTS.md와 CLAUDE.md는 공존할 수 있습니다. Claude Code는 AGENTS.md도 읽습니다. 팀에서 여러 AI 도구를 혼용한다면, 역할을 나눌 수 있습니다. 예를 들어 AGENTS.md에는 "테스트 실행: npm test", "커밋 메시지: 한글 동사+목적어" 같은 모든 에이전트가 공유하는 규칙을 넣고, CLAUDE.md에는 hooks 설정이나 .claude/rules/ 경로 활용 같은 Claude Code 전용 기능 설정을 넣는 방식입니다.

권장하는 조합

현실적으로 가장 효과적인 조합은 "최소한의 CLAUDE.md + hooks + 충실한 기존 문서"입니다.

CLAUDE.md를 완전히 없애는 건 비현실적입니다. 프로젝트마다 "코드를 읽어도 알 수 없는" 규칙이 분명히 있거든요. 그런 규칙만 골라서 200줄 이내로 적고, 나머지는 hooks, 린터, 기존 설정 파일에 맡기는 겁니다.

실전 CLAUDE.md 템플릿

여기까지가 원칙이고, 실제로 쓸 수 있는 템플릿을 보겠습니다. 프로젝트에 맞게 필요한 부분만 골라 쓰세요.

복사
# 빌드 & 실행
- 패키지 관리: pnpm
- 개발 서버: pnpm dev
- 빌드: pnpm build
- 타입체크: pnpm typecheck (빌드 전 필수)

# 테스트
- 단일 테스트: pnpm test -- --run -t "테스트명"
- 전체 테스트 실행 금지 (CI에서만 실행)

# Git 규칙
- main 직접 push 금지 (PR 필수)
- 커밋 메시지: 한글, "동사+목적어"
- 커밋 전 typecheck 통과 확인

# 코드 스타일 (비표준 규칙만)
- React 컴포넌트: named export만 사용
- API 호출: src/lib/api.ts의 래퍼 함수만 사용
- 상태관리: Zustand (Redux 아님)

# 주의사항
- .env 파일 커밋 금지
- 기존 마이그레이션 파일 수정 금지

이 템플릿은 약 20줄입니다. 프로젝트의 규모와 특수성에 따라 더 길어질 수 있지만, 매 줄이 "이걸 빼면 Claude가 실수하는가?"에 대한 답이어야 합니다.

Martin Fowler의 관점: Context Engineering

지금까지 CLAUDE.md 하나에 집중했는데, 좀 더 넓은 맥락에서 보겠습니다.

2026년 2월, Martin Fowler가 "Context Engineering for Coding Agents"를 발표했습니다. CLAUDE.md를 더 넓은 프레임워크 안에서 바라보는 시각입니다.

Fowler는 AI 에이전트에 제공하는 컨텍스트를 세 계층으로 나눕니다.

첫째, Reusable Prompts입니다. 지시사항(Instructions)과 가이드라인(Guidance)으로, CLAUDE.md가 여기에 해당합니다. 반복 가능하고 안정적인 지시를 담습니다.

둘째, Context Interfaces입니다. 도구(Tools), MCP 서버, Skills 같은 것들입니다. 에이전트가 필요할 때 호출해서 정보를 가져오는 인터페이스입니다. CLAUDE.md에 방대한 정보를 넣는 대신, 에이전트가 필요할 때 접근할 수 있는 도구를 제공하는 방식입니다.

셋째, Workspace Files입니다. 코드베이스 자체가 강력한 컨텍스트라는 점입니다. 잘 작성된 코드, 명확한 타입 정의, 일관된 네이밍은 별도의 설명 없이도 에이전트에게 충분한 맥락을 제공합니다.

Fowler가 강조하는 점이 있습니다. "context engineering이라고 부르지만, LLM이 관여하는 한 어떤 것도 확정적이지 않습니다." 확률적으로 사고하고, 점진적으로 구축하고, 효과를 지속적으로 검증하라는 겁니다.

CLAUDE.md에 규칙을 적는 것만이 context engineering이 아닙니다. 코드 자체를 명확하게 작성하고, 설정 파일을 정확하게 관리하고, hooks로 규칙을 강제하고, Skills로 도메인 지식을 분리하는 것까지 전부 에이전트에게 제공하는 컨텍스트입니다.

다음 그림은 Fowler가 제시한 Context Engineering 3계층 프레임워크입니다.

가장 아래 층인 워크스페이스 파일(코드, 타입, 설정 파일)이 가장 넓고 강력한 컨텍스트입니다. 그 위에 MCP 서버, Skills 같은 컨텍스트 인터페이스가 있고, 맨 위에 CLAUDE.md 같은 재사용 가능한 프롬프트가 놓입니다. 잘 작성된 코드가 최고의 CLAUDE.md라는 뜻입니다.

CLAUDE.md 건강 점검 체크리스트

이미 CLAUDE.md를 사용하고 있다면, 다음 체크리스트로 점검해 보세요.

줄 수 확인: 200줄을 넘기면 줄이세요. wc -l CLAUDE.md로 확인합니다.

중복 확인: CLAUDE.md의 각 줄에 대해 "이 정보가 코드베이스의 다른 파일에도 있는가?"를 확인합니다. package.json, tsconfig.json, .eslintrc, README.md와 중복되는 내용을 지웁니다.

필요성 확인: 각 줄에 대해 "이 줄을 지우고 Claude에게 같은 작업을 시키면, Claude가 다르게 행동하는가?"를 테스트합니다. 답이 "아니오"면 지웁니다.

린터 대체 가능 여부: 코딩 스타일 관련 규칙 중 ESLint, Prettier, hooks로 대체 가능한 것을 파악합니다. 대체 가능하면 CLAUDE.md에서 지우고 도구로 옮깁니다.

코드베이스 개요 제거: "이 프로젝트는 ~로 작성되었습니다", "디렉토리 구조는 다음과 같습니다" 같은 내용을 찾아 지웁니다. 에이전트가 탐색으로 파악할 수 있는 정보입니다.

최근에 등장한 agents-lint라는 도구도 참고할 수 있습니다. AGENTS.md 파일의 품질을 자동으로 검사해서 중복이나 불필요한 내용을 찾아주는 도구인데, CLAUDE.md 점검에도 유사한 관점을 적용할 수 있습니다.

정리

논문이 밝힌 건 단순합니다. LLM이 자동 생성한 컨텍스트 파일은 기존 문서와 중복되어 오히려 해가 되고, 인간이 최소한으로 직접 작성한 컨텍스트 파일은 소폭이지만 분명한 효과가 있습니다.

현업 개발자에게 들어보니, CLAUDE.md를 꼼꼼하게 관리하는 팀과 대충 자동 생성해서 쓰는 팀의 체감 차이가 크다고 합니다. "쓰느냐 안 쓰느냐"가 아니라 "어떻게 쓰느냐"가 갈림길입니다.

한 문장으로 줄이면 이겁니다. "Claude가 코드를 읽어도 알 수 없는 것만 적어라."

claude init의 유혹을 이기고, 빈 파일에서 시작해서, Claude가 같은 실수를 반복할 때마다 한 줄씩 추가하세요. 200줄을 넘기면 무언가 잘못된 겁니다. 그때는 CLAUDE.md를 다듬을 게 아니라, 코드베이스 자체를 명확하게 만드는 게 먼저입니다.