Claude가 또 막힌다. 당신이 넣어준 그 거대한 CLAUDE.md 파일 — 250줄에 달하는 진지한 지침, 도구 목록, 엣지 케이스, 동기부여 명언까지 다 들어찬, LLM이 최대 커버리지를 위해 뱉어낸 완벽주의 산물. 그런데 간단한 리팩토링에서 에이전트가 헛돌기만 한다.
한 발짝 물러서 보자. 이건 사용자 실수가 아니다. ETH Zurich 연구자들이 방금 여러 AI 코딩 에이전트에서 138개 에이전트 파일을 분석한 폭탄 연구를 발표했다. 인간이 쓴 60줄 미만의 간결한 파일? 성공률 +4%. LLM이 쏟아낸 200줄 넘는 책? 성공률 -3%, 토큰 소모는 20% 더 늘었다.
CLAUDE.md 파일이 대체 뭐냐고?
Anthropic의 에이전트 코딩 비밀 무기다. 리포 루트에 놓인 마크다운 파일로, Claude(또는 호환 에이전트)에게 행동 지침을 주는 거지. 프로젝트 헌법 같은 거: 규칙, 도구, 워크플로. 그런데 대부분? 쓰레기. 완전성을 쫓다 명확성을 잃기 때문이다.
ETH 연구의 핵심 인용:
인간 작성, 간결 (<60줄): 성공률 +4%
LLM 생성, 장황 (200줄 이상): 성공률 -3%, 토큰 비용 +20%
LLM 생성 파일이 에이전트를 더 망치게 만든다. 아찔하네.
내 생각인데, 원 연구엔 없지만 이건 90년대 Vim 설정 전쟁과 똑같다. geek들이 .vimrc에 플러그인 잔뜩 쌓아놓다 Minimal ViM이 대박 쳤잖아. 이제 AI 개발에서 프롬프트 미니멀리즘 시대가 온다. Unix 철학 리믹스: 한 가지 일만, 완벽하게.
왜 장황함이 에이전트를 망가뜨릴까?
간단하다. 에이전트는 법률 전문가가 아니라 토큰 제한 속 패턴 매처다. 노이즈로 범벅하면 컨텍스트 윈도우가 막히고, 핵심 지침이 솜털에 묻는다.
하지만 깊이 파보자. Claude의 기반 트랜스포머(알면서 왜 나오냐)는 긴 컨텍스트에서 어텐션 메커니즘이 희석된다. ETH 테스트에서 장황 파일은 할루시네이션 위험을 15% 키웠다. 모델이 리포 실제 구조 대신 무관한 “베스트 프랙티스”에 집착하니까.
비용만 문제 아니야. 인지 문제다. 60줄 파일은 날카로운 API 스펙처럼 — 지시적이고 군살 없음. 그 이상? 전쟁과 평화로 유아 훈련하는 꼴.
60줄 원칙은 임의가 아니다. 전투 검증: 제목(5줄), 핵심 규칙(15), 도구(10), 워크플로(20), 메트릭(10). 딱 총명한 지침.
버려야 할 것? 문서 덤프(“위키 봐!”), LLM 선언문(“넌 10배 엔지니어…”), 싱크대 빼고 다 넣은 파일.
안티패턴: 재앙 갤러리
첫 번째 범인: 문서 덤프. “README.md 봐라 설치법.” 에이전트는 간접 참조 싫어한다 — 동적 파일 읽기는 명시적 페치 없인 안 되고, 토큰만 태운다.
더 나쁜 건 LLM 선언문. 성격 뻥튀기 몇 페이지. “호기심 많고, 공감하고, 회의적일 것.” 귀엽지만 신호 희석. ETH 데이터? 로직 중심 작업에서 성공률 7%↓.
그리고 올인원 파일 — 도구, 규칙, 예제, 히스토리. 블로트 천국. (프로 팁: 에이전트는 순차 파싱; 180줄에 핵심 묻히면 끝.)
점진적 공개: Skills로 구원
덤프 치지 마. 레이어 쌓아. Claude의 Skills 기능 쓰자 — 필요 시 로드되는 모듈 확장. 핵심 CLAUDE.md는 날씬하게, “디버깅”이나 “배포” 같은 틈새는 Skills가.
방법? 파일 경로에 Skills 핀. 에이전트가 필요 감지(의미 매치로), 끌어당김. 쾅 — 컨텍스트 윈도우 보존, 유연성 업.
이건? 아키텍처 전환. 모놀리식 프롬프트에서 조합형 에이전트 OS로. 왜 중요? 100개 넘는 서비스 모노레포에 스케일.
바로 써먹는 템플릿
모노레포 미침? 여기:
# 프로젝트 규칙
- pnpm만 써라.
- 테스트 먼저, 무조건.
# 도구
- Cursor로 편집.
- Biome으로 린트/포맷.
# 워크플로
1. 주석으로 계획.
2. 테스트 작성.
3. 구현 + 린트.
4. PR.
# 측정
성공: 테스트 통과, 린트 에러 없음.
(27줄. 끝.)
API 백엔드? “Prisma로 Postgres 마이그레이션,” “Clerk로 인증”으로 바꿔.
프론트? “React 19, Tailwind, Vite.” 워크플로: “Storybook 체크, chromatic diff.”
확장 말고 적응.
제대로 되는지 어떻게 재?
ETH 스타일 벤치마크. Devin이나 Aider 벤치 포크 — 수정 전후 10개 작업 돌려. 성공 %, 토큰, 시간 추적.
프로 팁: GitHub Actions 후크. PR 때 작업 에이전트화(“utils 리팩토”), 메트릭 로그. 60줄 미만인데 실패? 길이 탓 아냐, 규칙 문제.
AI 개발자한테 왜 중요한가?
CLAUDE.md는 장식 아냐 — 에이전트 코딩의 OS다. 잘못하면 10배 꿈이 1.2배로 끝. 제대로? ETH 추정으로 20-30% 속도 업.
예언: Cursor 같은 툴이 25년 1분기쯤 60줄 스타터 자동 생성, 블로트 사이클 끝장. 당신은 이미 앞서.
🧬 관련 인사이트
- 더 읽기: BLE or Wi-Fi: The Battery Killer Choice for Android IoT Builders
- 더 읽기: Local LLMs Are Eating Your Hardware Alive: Track Costs and Rate Limit Before It’s Too Late
자주 묻는 질문
CLAUDE.md 파일은 뭐에 쓰나요?
Claude 같은 AI 코딩 에이전트에게 프로젝트 규칙, 도구, 워크플로를 안내하는 마크다운 설정 파일 — 리포 에이전트 개발 필수.
CLAUDE.md 파일은 몇 줄이 적당하나요?
60줄 미만 목표: ETH Zurich 연구에서 인간 작성 간결 파일 성공률 4%↑, 장황 파일은 더 실패.
왜 LLM 생성 CLAUDE.md가 성능 떨어지나요?
컨텍스트 블로트(200줄+), 토큰 비용 20%↑, 핵심 지침 희석 — 노이즈에 에이전트 할루시네이션 더 난다.
