새 연구, AI 코딩을 위한 Agents.md 파일의 가치를 재평가
Source: Hacker News
개요
산업 전반에 걸친 권고에도 불구하고, new ETH Zurich paper 은 AGENTS.md 파일이 AI 코딩 에이전트를 오히려 방해할 수 있다고 결론짓는다. 연구자들은 다음을 권고한다:
- LLM‑generated 컨텍스트 파일을 완전히 생략한다.
- 인간이 작성한 지시사항은 추론할 수 없는 세부 사항(예: 매우 구체적인 도구 사용법이나 맞춤 빌드 명령)으로 제한한다.
저자 및 동기
팀 – Thibaud Gloaguen, Niels Mündler, Mark Müller, Veselin Raychev, 그리고 Martin Vechev – 는 다음과 같은 이유로 연구를 정당화했습니다:
- ~60 000개의 오픈‑소스 저장소에 현재
AGENTS.md와 같은 컨텍스트 파일이 포함되어 있습니다. - 많은 에이전트 프레임워크에는 이러한 파일을 자동으로 생성하는 내장 명령이 포함되어 있습니다.
- 엄격한 실증 연구는 이러한 파일이 실제 코딩 작업을 해결하는 AI 에이전트의 능력을 실제로 향상시키는지 조사한 적이 없습니다.
한 저자는 **Humanity Last Exam benchmark**에도 기여했습니다.
데이터셋: AGENTbench
연구자들은 AGENTbench 를 구축했으며, 이는 니치 저장소에서 가져온 138개의 실제 Python 작업으로 구성된 새로운 데이터셋입니다. 이는 AI 모델이 부분적으로 기억했을 수 있는 SWE‑bench 같은 인기 벤치마크의 편향을 의도적으로 피합니다.
테스트된 에이전트
| 에이전트 | 모델 |
|---|---|
| Claude | 3.5 Sonnet |
| Codex | GPT‑5.2 |
| Codex | GPT‑5.1 mini |
| Qwen | Code |
실험 시나리오
- 컨텍스트 파일 없음
- LLM‑생성 컨텍스트 파일
- 인간 작성 컨텍스트 파일
선택된 모든 니치 저장소는 원래 인간이 작성한 컨텍스트 파일을 포함하고 있었으며, 첫 번째와 두 번째 시나리오는 해당 파일을 제거하거나 교체하여 만들었습니다.
평가 지표
- 작업 성공률 (저장소 단위 테스트에 의해 결정)
- 에이전트 단계 수
- 전체 추론 비용
주요 결과
| Context Type | Success‑Rate Δ vs. No‑Context | Steps ↑ | Inference‑Cost ↑ |
|---|---|---|---|
| LLM‑generated | ‑3 % (성능 저하) | ↑ | +20 % |
| Human‑written | +4 % (소폭 상승) | ↑ | +19 % |
AGENTS.md에 아키텍처 개요나 저장소 구조 설명을 포함해도 모델이 관련 파일을 찾는 데 걸리는 시간을 줄이지 못했습니다.- 에이전트는 일반적으로
AGENTS.md파일의 지시를 따랐으며, 그 결과 테스트, 파일 읽기, grep 검색, 코드 품질 검사 등이 늘어났습니다—특정 작업에 불필요한 행동들입니다. - 추가 컨텍스트는 추론 모델이 더 열심히 생각하도록 만들었지만, 최종 패치의 품질을 향상시키지는 못했습니다.
Authors’ Conclusions
“우리는 모든 컨텍스트 파일이 작업을 완료하는 데 필요한 단계 수를 일관되게 증가시킨다는 것을 발견했습니다. LLM‑생성 컨텍스트 파일은 작업 성공률에 약간의 부정적인 영향을 미치는 반면, 개발자가 작성한 파일은 약간의 성능 향상을 제공합니다.
우리의 추적 분석은 컨텍스트 파일의 지시가 일반적으로 따르며 더 많은 테스트와 폭넓은 탐색을 이끌어내지만, 효과적인 저장소 개요 역할을 하지는 못한다는 것을 보여줍니다. 전반적으로, 우리의 결과는 컨텍스트 파일이 에이전트 행동에 미치는 영향이 미미하며 수동으로 작성된 경우에만 바람직할 가능성이 있음을 시사합니다. 이는 현재 에이전트‑개발자 권고와 관찰된 결과 사이에 구체적인 격차가 있음을 강조하고, 코딩 에이전트를 위한 간결하고 작업‑관련 지침을 자동으로 생성하는 원칙적인 방법에 대한 향후 연구를 촉구합니다.”
커뮤니티 반응
개발자 1 – AGENTS.md 옹호
“연구를 읽었습니다. 저는 저자들이 제시한 것과 정반대로, 실제로 좋은
AGENTS.md파일을 보증하고 있다고 생각합니다.”“
AGENTS.md파일의 가장 큰 활용 사례는 모델이 알지 못하고 프로젝트에서 즉시 추론할 수 없는 도메인 지식입니다. 이는 에이전트가 이 결함 때문에 고생하는 모습을 보면서 시간이 지나면서 서서히 얻어지는 것입니다. 이는 폐쇄형 소스에서는 흔하지만,AGENTS.md파일을 가진 공개 GitHub 프로젝트에서는 매우 드뭅니다—대부분은 최근에 LLM을 중심으로 만든 작은 분위기 코딩 프로젝트이기 때문이죠. 후자의 프로젝트에서 4 % 정도의 향상이 보인다면, 처음부터AGENTS파일의 품질이 매우 다양할 것이고, 고품질.md파일을 갖춘 큰 프로젝트에서는 에이전트와 작업할 때 이 파일들이 매우 귀중합니다.”
개발자 2 – 인간 도구로서의 AGENTS.md
“두 프로젝트에서 약 3개월 동안
CLAUDE.md파일을 관리해 왔는데, 개선 효과가 눈에 띄지만 기대했던 이유와는 다릅니다. 실제 토큰‑레벨 컨텍스트가 제공하는 영향보다, 이를 작성함으로써 코드베이스에 대해 머릿속에만 있던 내용을 명확히 표현하게 되는 것이 더 큰 의미가 있습니다.”
Source: …
Takeaway
- LLM‑generated
AGENTS.md파일은 성능을 저하시킬 수 있고 비용을 증가시킵니다. - 사람이 직접 작성한 파일은 성공률을 약간 올릴 수 있지만, 단계 수와 추론 비용도 늘어납니다.
AGENTS.md의 주요 가치는 AI 에이전트에 직접적인 도움을 주기보다는 개발자에게 문서화 작업을 하게 하는 데 있을 수 있습니다.
향후 연구에서는 불필요한 오버헤드 없이 코딩 에이전트에 실제로 도움이 되는, 원칙에 기반한 간결하고 작업에 적합한 가이드를 탐구해야 합니다.
“we use this weird pattern for X because of a legacy constraint in Y.”
Once that’s written down, the agent picks it up, but so does every new human on the team.
Developers can [review the paper online](https://arxiv.org/abs/2602.11988).
The use of context files, such as `AGENTS.md`, `CLAUDE.md`, or `.cursorrules`, [grew in importance in the second half of 2025](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation), coinciding with a larger push by AI coding agent providers.저자 소개
Bruno Couriol
더 보기 / 덜 보기