“CLAUDE.md 지워라” 논문의 진짜 의미 — AI 에이전트 컨텍스트의 미래

들어가며

AI 코딩 에이전트를 쓰는 개발자라면 CLAUDE.md나 AGENTS.md를 프로젝트 루트에 두고 있을 것이다. 프로젝트 구조, 코딩 컨벤션, 아키텍처 결정 — 에이전트가 “우리 프로젝트를 이해”하도록 꼼꼼히 적어둔다.

최근 나온 논문 하나가 이 상식을 정면으로 뒤집었다. Theo(t3.gg)가 29분짜리 영상으로 논문을 실전 관점에서 해부했고, 코드팩토리가 한국어로 핵심을 짚었다.

“Repository-level Context Files: Helpful for Coding Agents?”

결론부터: CLAUDE.md가 AI를 더 멍청하게 만들고, 돈은 더 많이 든다. 단, 조건이 있다.

논문이 실제로 말하는 것

실험 설계

연구팀은 GitHub PR 기반 벤치마크를 만들고, 세 가지 조건에서 AI 에이전트를 테스트했다:

예상 밖의 결과

AI가 자동 생성한 CLAUDE.md:

• 성공률 2% 하락 (Agent Bench), 0.5% 하락 (SWE-bench)
• 추론 비용 20% 이상 증가
• 툴 사용 횟수 증가 — 불필요하게 넓은 탐색

사람이 직접 쓴 CLAUDE.md:

• 대부분의 모델에서 성공률 19% 상승
• 단, Sonnet은 오히려 하락 (혼자서도 잘하는 타입)

왜 이런 결과가 나왔나

핵심은 불필요한 컨텍스트가 방해한다는 것이다.

현대 AI 에이전트는 자율적으로 코드를 탐색하고 분석한다. 서브에이전트를 띄워 병렬로 분석하고, 필요한 파일만 골라 읽는다. 여기에 “프로젝트 전체 구조도”를 통째로 던져주면?

• 지금 작업과 무관한 정보가 컨텍스트를 오염시킨다
• “하지 마라”는 지시가 오히려 그 행동을 상기시킨다
• 첫 번째 응답까지의 스텝 수가 증가한다

GPT-5.2는 컨텍스트 파일 처리에 추론 토큰을 22% 더 소모했다. 5.1 Mini는 14%. 스스로 작업을 더 어렵게 만든 셈이다.

Theo의 실전 감사: “내 AGENTS.md도 문제였다”

Theo(t3.gg)는 이 논문을 보고 자기 프로젝트(T3 Chat)의 AGENTS.md를 라이브로 감사했다.

컨텍스트 우선순위 계층

Theo가 정리한 AI 에이전트의 컨텍스트 처리 순서:

1. Provider Instructions (최상위 — 회사가 심은 행동 규칙)
2. System Prompt (시스템 프롬프트)
3. CLAUDE.md / AGENTS.md ← 여기
4. User Prompt (사용자 입력)
5. Agent Output (에이전트 출력 → 다시 컨텍스트로)

CLAUDE.md는 시스템 프롬프트 바로 아래에 위치한다. 모든 대화에서 사용자 입력보다 높은 우선순위로 작용한다. 여기에 잘못된 정보가 있으면? 사용자가 아무리 정확한 프롬프트를 줘도 CLAUDE.md가 이긴다.

T3 Chat AGENTS.md에서 발견한 문제들

1. 자동 생성된 부분이 대부분 쓸모없었다

# 자동 생성 — 에이전트가 알아서 찾을 수 있는 것들
- pnpm 스크립트 목록 (dev, lint, build...)
- 폴더 구조 설명
- 사용 중인 서비스 목록

에이전트는 package.json을 읽으면 스크립트를 안다. 폴더 구조는 탐색하면 된다. 이미 코드에 있는 정보를 CLAUDE.md에 다시 적는 건 중복이고, 오히려 방해다.

2. “TRPC 사용” 한 줄이 만든 부작용

AGENTS.md에 “이 프로젝트는 TRPC를 사용한다”고 명시했더니, 모델이 TRPC를 쓰면 안 되는 곳에서도 TRPC를 시도했다. 컨텍스트에 기술 이름을 넣으면 에이전트가 그쪽으로 편향된다.

3. 직접 쓴 부분만 효과가 있었다

# 사람이 쓴 부분 — 에이전트가 절대 알 수 없는 것
- "pnpm dev는 실행하지 마라, 이미 돌아가고 있다"
- "pnpm build는 CI에서만 실행"

이건 코드를 아무리 읽어도 알 수 없는 운영 맥락이다. 이런 정보만 남길 가치가 있다.

Theo의 결론

“에이전트가 코드를 읽으면 알 수 있는 것은 전부 지워라. CLAUDE.md에는 에이전트가 절대 혼자 알아낼 수 없는 정보만 남겨라.”

과격한 주장이지만, 논문 데이터가 뒷받침한다. 자동 생성 컨텍스트(= 코드에서 추출한 정보)가 성능을 떨어뜨렸다는 건, 이미 코드에 있는 정보를 CLAUDE.md에 넣으면 해롭다는 뜻이다.

그래서 CLAUDE.md를 어떻게?

세 영상의 관점을 종합하면:

방향은 같다: 적게, 정확하게.

실전 체크리스트

CLAUDE.md의 각 줄에 이 질문을 던져보자:

남겨야 할 것:

- pnpm dev는 실행하지 마라 (이미 돌아가고 있다)
- DB 마이그레이션은 반드시 PR 리뷰 후 실행
- 이 프로젝트의 에러 핸들링은 Result 패턴을 따른다

삭제해야 할 것:

- 이 프로젝트는 Next.js 15를 사용한다 (package.json에 있음)
- src/app/ 폴더에 페이지가 있다 (탐색하면 알 수 있음)
- pnpm dev, pnpm lint, pnpm build 스크립트 목록 (package.json)

컨텍스트의 미래: WebMCP

CLAUDE.md 최적화가 “현재의 해법”이라면, WebMCP는 “미래의 패러다임”이다.

프론트엔드를 위한 MCP

Google과 Microsoft가 공동으로 만든 W3C 표준 초안. AI 에이전트가 웹사이트와 상호작용하는 방식을 근본적으로 바꾼다.

현재: 스크린샷 캡처 → 비전 모델 분석 → 픽셀 단위 추측 (정확도 70%)

WebMCP: 웹사이트가 구조화된 도구를 직접 제공 → 에이전트가 JSON으로 호출 (정확도 98%)

정확도: 70% → 98%
토큰 효율: 89% 개선
컴퓨팅 오버헤드: 67% 감소

아키텍처

웹페이지 ←→ 브라우저(중재자) ←→ AI 에이전트
   │              │                │
   도구 등록      권한 관리         도구 호출

기존 HTML 폼에 속성 몇 줄만 추가하면 AI가 호출 가능한 도구가 된다:

<form tool-name="flight-search" 
      tool-description="항공편 검색" 
      tool-autosubmit>
  <input name="departure" />
  <input name="arrival" />
</form>

MCP + WebMCP = 풀스택 AI 도구 통합

백엔드는 MCP로, 프론트엔드는 WebMCP로. AI 에이전트가 서버와 브라우저 양쪽을 구조화된 방식으로 활용하는 풀스택 아키텍처가 완성된다.

현재 상태

• Chrome 146 Canary에서 테스트 가능 (플래그 뒤)
• W3C 커뮤니티 그룹 초안 (아직 공식 표준 아님)
• 보안 섹션은 아직 미완 (프롬프트 인젝션, 데이터 유출 우려)

모든 이야기가 만나는 지점

논문, Theo의 실전 감사, WebMCP — 전부 같은 문제를 다른 각도에서 본다: AI 에이전트에게 컨텍스트를 어떻게 줘야 하는가?

공통 원칙: 필요한 것만, 구조화해서, 필요할 때만.

실전 액션 아이템

지금 당장 (10분)

1. CLAUDE.md 열고 각 줄에 “에이전트가 코드 읽으면 아는 거 아닌가?” 질문하기 — Yes면 삭제
2. 기술 이름 명시 제거 — “React 사용”, “Prisma ORM” 같은 건 편향만 유발
3. claude /init 결과물 의심하기 — 자동 생성은 논문이 증명한 독

이번 주 (1시간)

4. 남은 내용 중 작업별 지식은 Skills로 분리 — 테스트 작성법, 배포 절차 등
5. CLAUDE.md 30줄 이내 도전 — 운영 맥락 + 불변 규칙만

가까운 미래

6. WebMCP 사양 주시 — 아직 프로덕션 X, 하지만 방향성은 확실
7. MCP + WebMCP 풀스택 설계 — 에이전트 기반 서비스라면 지금부터 아키텍처 고려

마치며

“AI가 멍청해졌다”는 불만의 99%는 사용자의 컨텍스트 관리 문제다.

Theo가 자기 AGENTS.md를 감사하며 발견한 것처럼, 우리가 정성껏 적어둔 CLAUDE.md의 대부분은 에이전트에게 이미 불필요한 정보다. 그리고 그 불필요한 정보가 에이전트를 느리게, 비싸게, 부정확하게 만든다.

더 많이 알려주는 게 능사가 아니다. 적게, 정확하게, 구조화해서 — 이것이 AI 에이전트 시대의 컨텍스트 원칙이다.

논문이 데이터로 증명했고, Theo가 실전으로 확인했고, WebMCP가 그 방향을 인프라 레벨에서 실현하고 있다.

참고 자료:

• 논문: Repository-level Context Files: Helpful for Coding Agents?
• Theo — Delete your CLAUDE.md (and your AGENT.md too)
• 코드팩토리 — CLAUDE.md 지워
• DIY Smart Code — WebMCP