AI 코딩 에이전트를 더 똑똑하게 만들려고 AGENTS.md 파일을 만드는 것이 오히려 독이 된다는 연구 결과가 나왔습니다. 스위스 ETH 취리히 대학 연구진이 138개 실제 프로젝트를 대상으로 진행한 실험에서 맥락 파일context file이 있을 때 성공률이 더 낮아졌습니다.
AGENTS.md가 뭔가요?
AGENTS.md는 AI 코딩 에이전트에게 프로젝트의 구조와 규칙을 알려주는 설명서입니다. "이 프로젝트는 FastAPI를 쓰니까 uvicorn으로 실행해"라든지 "테스트는 pytest로 돌려"라는 식의 안내를 담습니다.
OpenAI, Anthropic 같은 회사들이 강력히 권장해서 현재 6만 개 이상의 오픈소스 프로젝트가 이런 파일을 만들어 뒀습니다. 개발자들 사이에서는 "당연히 넣어야 하는 것"으로 여겨졌죠.
실험 결과: 오히려 성능이 떨어져
연구진은 Claude, GPT, Qwen 등 4가지 AI 모델로 테스트했습니다. 결과는 예상과 정반대였습니다.
LLM이 자동 생성한 AGENTS.md: 성공률이 평균 3% 떨어짐
개발자가 직접 쓴 AGENTS.md: 겨우 4% 향상
더 충격적인 건 비용입니다. 맥락 파일이 있으면 AI가 20% 이상 더 많은 토큰을 소모했습니다. 돈도 더 들고 성능도 떨어지는 셈입니다.
왜 이런 일이 벌어질까
연구진이 AI의 행동을 추적해봤더니 흥미로운 패턴을 발견했습니다. AGENTS.md가 있으면 AI가 지나치게 많은 일을 합니다.
맥락 파일 없이는 핵심 파일을 바로 찾아가는데, 파일이 있으면 온 프로젝트를 뒤지고 테스트도 과도하게 돌립니다. 마치 "완벽하게 해야 해"라는 강박에 사로잡힌 것 같습니다.
특히 GPT-5.2는 맥락 파일이 있을 때 22% 더 많이 "생각"했습니다. AI가 과제를 더 어렵게 받아들인 겁니다.
문서가 이미 있는데 굳이?
연구진은 기존 문서를 모두 제거한 뒤 실험해봤습니다. 그러자 LLM 생성 맥락 파일이 오히려 도움이 됐습니다. 즉, AGENTS.md는 기존 README나 문서와 중복되는 정보만 제공하고 있었던 겁니다.
그럼 어떻게 해야 할까: 실무 가이드
1. LLM 생성 AGENTS.md는 쓰지 마세요
OpenAI나 Anthropic이 권장해도 무시하세요. 연구 결과가 명확합니다. 자동 생성된 파일은 성능을 떨어뜨립니다.
2. 사람이 쓸 거라면 최소한으로
꼭 필요하다면 개발자가 직접 써야 합니다. 하지만 장황하게 쓰지 마세요. 딱 세 가지만:
• 특수한 빌드 도구 ("uv 써주세요")
• 독특한 테스트 방식 ("make test로 돌려주세요")
• 절대 건드리면 안 되는 파일 ("config.prod.json 수정 금지")
3. 기존 문서가 부실한 프로젝트만 예외
README도 없고 문서도 엉망인 프로젝트라면 AGENTS.md가 도움될 수 있습니다. 하지만 그럴 바에는 차라리 기존 문서를 먼저 정리하세요.
우리가 가져야 할 관점
이 연구는 "더 많은 정보가 더 좋은 결과를 낸다"는 직관이 AI 시대에는 통하지 않을 수 있음을 보여줍니다. 출판에서도 마찬가지입니다. 편집자에게 작가의 모든 의도를 설명해주는 것이 오히려 좋은 편집을 방해할 수 있습니다.
AI 에이전트는 최소한의 맥락에서 최대 성과를 내도록 설계돼 있습니다. 인간처럼 맥락이 많을수록 더 잘하는 게 아니라는 점을 기억해야 합니다.
당신의 프로젝트에 AGENTS.md가 있다면 한 번쯤 의심해보세요. 정말 필요한가요?
