CLAUDE.md 안 썼더니 오히려 잘한 짓이었다

타임라인에 CLAUDE.md(또는 AGENTS.md) 관련 글이 올라올 때마다 “나중에 해야지” 하고 스크롤을 내렸다. 정교하게 AGENTS.md를 구성하는 사람들을 보면서 슬쩍 불안하기도 했다. 나만 뒤처지는 건 아닐까 싶어서.

그런데 최근 벤치마크 데이터가 나왔고, 그 불안이 싹 사라졌다. 내 귀찮음이 꽤 합리적인 엔지니어링 판단이었다는 게 밝혀진 것이다.

LLM이 만들어준 컨텍스트 파일, 오히려 독

“컨텍스트를 더 주면 당연히 더 잘하겠지.” 나도 그렇게 생각했다.

연구자들이 SWE-bench Lite에서 LLM 자동 생성 컨텍스트를 테스트해봤더니 성공률이 0.5% 떨어졌다. AgentBench에서는 추가로 2%가 더 빠졌다. 손으로 꼼꼼히 작성한 파일도 겨우 4% 개선에 그쳤다. 일종의 ‘컨텍스트 과적합’이라고 부를 만하다.

• SWE-bench Lite: LLM 생성 컨텍스트로 성공률 0.5% 하락
• AgentBench: 추가로 2% 추가 하락
• 추론 비용 20~23% 증가
• 문서가 아예 없는 저장소에서만 2.7% 긍정적 효과

Gloaguen 외 연구진이 쓴 논문 “Evaluating AGENTS.md”에서 확인된 결과다. 저장소 컨텍스트를 아예 제공하지 않을 때보다 컨텍스트 파일이 있을 때 작업 성공률이 낮아지는 경향이 있다.

에이전트가 지시를 너무 잘 따르는 게 문제다

에이전트가 지시를 무시해서 생기는 문제가 아니다. 오히려 반대다.

컨텍스트 파일에 uv를 쓰라고 한 줄만 써놓으면, 에이전트는 전혀 필요 없는 상황에서도 uv를 설치하고 실행하면서 매번 불필요한 단계를 추가한다.

GPT-5.2 기준으로 컨텍스트 파일이 있을 때 추론 토큰이 14~22% 늘어났다. 지시를 따르느라 정작 문제를 푸는 데 집중하지 못하는 것이다.

• 불필요한 pytest 실행 증가
• grep이나 파일 읽기 도구 사용이 필요 이상으로 늘어남

”X 하지 마”라고 쓰면 에이전트는 X를 더 생각한다

예전 글에서 SKILL.md 본문 내용이 특정 타이밍에 읽힌다는 내용을 다룬 적 있는데, AGENTS.md도 비슷한 문제가 있다.

AGENTS.md는 시스템 프롬프트와 사용자 프롬프트 사이의 ‘개발자 메시지’ 레이어에 위치한다. 이 위치가 에이전트 추론을 크게 제약한다.

“이 파일은 건드리지 마”라고 써놓으면 에이전트는 그 파일을 한 번 더 떠올린다. 연구자들은 이걸 ‘분홍 코끼리 효과’라고 불렀다. 분홍 코끼리를 생각하지 말라고 하면 딱 그게 머릿속에 떠오르는 것처럼.

• 우선순위: 제공자 지시 → 시스템 프롬프트 → AGENTS.md → 사용자 프롬프트
• 손으로 관리하는 파일은 코드 변경을 따라잡지 못해서 정보가 금방 낡아버린다

꼭 써야 한다면, 최소한으로

저장소에 문서가 아예 없는 경우라면 컨텍스트 파일이 도움이 될 수 있다. 데이터상으로도 그런 경우에만 2.7% 긍정적인 효과가 있었다. 그래도 쓴다면 내용을 최소한으로 줄여야 한다.

저장소 특화 빌드 도구 사용법 한 줄. 에이전트가 반복해서 잘못 패턴화하는 부분 교정 한 줄.

“구조적으로 이상한 점을 발견하면 바로 알려줘” 같은 걸 넣으면 에이전트가 코드베이스 취약점을 보고하는 도구로 변해버린다. 그것보다는 코드 구조 자체를 직관적으로 만드는 게 훨씬 효과적이다.

• 유닛 테스트와 타입 검사를 강화하는 게 컨텍스트 파일보다 낫다
• 파일 위치가 헷갈린다면 설명을 쓰는 대신 파일을 옮겨라

좋은 컨텍스트 파일을 쓰는 게 반드시 실력의 증거는 아니다. 컨텍스트 파일의 구조를 이해하고 그것을 둘러싼 메타 시스템을 설계하는 것, 그게 진짜 실력이다. 그리고 가끔은 “귀찮아서 안 했다”는 게 최선의 엔지니어링 결정이 되기도 한다.