CLAUDE.md를 삭제하세요 - AGENTbench 논문이 증명한 컨텍스트 파일의 역설

TL;DR

AGENTbench 논문(arXiv:2602.11988)에 따르면, CLAUDE.md와 AGENTS.md 같은 컨텍스트 파일이 AI 코딩 에이전트의 성공률을 떨어뜨리고 비용을 20% 이상 높입니다. 200줄 이하로 유지하고, 나머지는 Skills와 Hooks로 분리하는 것이 해결책입니다.

논문이 뭘 증명했나요?

12개 Python 리포, 138개 코딩 태스크에서 Claude Code(Sonnet 4.5), Codex(GPT-5.2), Qwen Code를 테스트했습니다.

3가지 조건을 비교했어요:

조건 A: 컨텍스트 파일 없음
조건 B: LLM이 자동 생성한 CLAUDE.md
조건 C: 사람이 직접 작성한 CLAUDE.md

결과가 직관과 완전히 달랐습니다.

LLM 생성 파일: 성공률 최대 2% 하락, 비용 20%+ 증가
사람 작성 파일: 성공률 4% 개선, 비용 20%+ 증가

4%p 개선을 위해 20% 비용 증가를 감수할 가치가 있을까요?

왜 이런 일이 벌어질까요?

에이전트가 CLAUDE.md 지시를 너무 충실히 따릅니다.

# CLAUDE.md에 이렇게 써놓으면
"이 리포는 pytest로 테스트하세요"

# 에이전트가 매번 이렇게 함
$ pytest  # 불필요한 경우에도 실행
$ pytest  # 파일 하나 고쳤는데 전체 테스트
$ pytest  # 또 실행

관련 파일에 도달하는 스텝이 증가하고, 추론 토큰은 최대 22% 늘어납니다. 컨텍스트를 줬더니 오히려 돌아가는 거예요.

"고봉밥" 안티패턴

CLAUDE.md 길이	규칙 적용률
200줄 이하	92%
400줄 초과	71%

직원한테 매뉴얼 10페이지 주면 다 읽어요. 50페이지 주면? 대충 훑고 멋대로 해요. AI도 마찬가지입니다.

해결책 3가지

A. Skills로 분리 (가장 추천)

.claude/skills/
├── thread-writer/SKILL.md     # 제목만 로드 (~100토큰)
├── code-reviewer/SKILL.md     # 필요시 전체 로드
└── deploy-guide/SKILL.md      # 필요시 전체 로드

Skills는 제목만 먼저 로드되고, 에이전트가 필요할 때만 전체를 불러옵니다. 서랍장에 라벨 붙여두고 필요한 서랍만 여는 거예요.

B. @AGENTS.md 패턴

# CLAUDE.md (인덱스 파일)
@.claude/rules/architecture.md
@.claude/rules/testing.md
@.claude/rules/style.md

CLAUDE.md를 한 줄짜리 인덱스로 만들어서 규칙 파일로 위임합니다.

C. Hooks 기반 로딩

CLAUDE.md를 삭제하고 SessionStart 훅에서 필요한 파일만 동적으로 주입합니다. 가장 급진적이지만 컨텍스트를 최소화할 수 있어요.

CLAUDE.md에 뭘 남겨야 할까요?

포함: 테스트/빌드 명령어, 리포 고유 도구, 절대 규칙 3-5개, 스킬 인덱스

제외: 디렉토리 구조(에이전트가 ls로 확인 가능), README 중복, "있으면 좋겠다" 가이드, 상세 코딩 스타일

마무리

"문서 깎는 개발자"가 되어야 합니다. 더 많은 컨텍스트 != 더 나은 결과.

여러분의 CLAUDE.md는 몇 줄이에요?

출처:

DEV Community