읽는 시간: 약 5~6분
코딩 에이전트를 실전에 붙여 본 팀이라면 한 번쯤 같은 질문을 하게 됩니다.
“AGENTS.md를 길고 자세하게 쓰면, 에이전트가 더 잘하지 않을까?”
직관적으로는 맞는 말처럼 보입니다. 저장소 구조, 테스트 명령, 코드 스타일, 금지 규칙, 리뷰 기준을 더 많이 알려주면 당연히 더 잘할 것 같죠. 그런데 최근 연구를 보면, 결과는 생각보다 정반대입니다.
핵심부터 말하면 이렇습니다.
- LLM이 자동 생성한 컨텍스트 파일은 성공률을 확실히 올리지 못했고, 경우에 따라 소폭 하락했습니다.
- 반대로 추론/실행 비용은 20% 이상 증가하는 경향이 확인됐습니다.
- 즉, 문제는 ‘에이전트가 말을 안 듣는 것’이 아니라, 너무 성실하게 지침을 따르느라 과탐색하는 것입니다.
왜 이 주제가 중요한가
지금 코딩 에이전트 운영의 병목은 모델 지능 그 자체보다, 운영 계층에 가깝습니다.
어떤 컨텍스트를 넣을지, 어떤 도구를 언제 쓰게 할지, 어느 시점에 멈추고 검증할지.
이 세 가지에서 비용과 성공률이 갈립니다. 그래서 AGENTS.md의 실효성은 ‘문서 작성 팁’이 아니라 실제 운영비와 품질에 직접 연결되는 의사결정입니다.
2602.11988이 보여준 것: 많이 준다고 잘하지 않는다
Evaluating AGENTS.md (arXiv:2602.11988)은 이 질문을 정면으로 다룹니다.
비교군은 단순합니다.
None: 컨텍스트 파일 없음
LLM: 에이전트 권장 방식으로 자동 생성된 컨텍스트
Human: 저장소 개발자가 직접 작성한 컨텍스트
그리고 SWE-bench Lite(대중 저장소)와 AGENTbench(개발자 컨텍스트가 실제 존재하는 저장소)를 함께 비교했습니다.
관찰 포인트는 세 가지입니다.
자동 생성 컨텍스트의 성능 이득은 제한적
비용은 꽤 명확하게 증가(약 20%+)
에이전트는 지시를 잘 따른다. 문제는 불이행이 아니라 과이행이다.
정리하면, 컨텍스트의 문제는 ‘부족’보다 ‘과잉’일 수 있다는 메시지입니다.
다른 아카이브와 연결하면 신뢰도가 올라간다
이 논문 하나만 인용하면 “특정 실험 조건의 우연 아닌가?”라는 반론이 가능합니다. 그래서 아래 축으로 함께 묶는 게 좋습니다.
- 기준선: SWE-bench (2310.06770)
- 최신성/오염 저항: SWE-bench Live (2505.23419), SWE-rebench (2505.20411)
- 병목 분해: ContextBench (2602.05892), SWE-ContextBench (2602.08316)
실무 적용: AGENTS.md를 짧고 강하게 다시 쓰는 법
제가 지금 권장하는 운영 원칙은 아래 4줄입니다.
필수 실행 명령만 남긴다 (build/test/lint 진입점)
금지 규칙만 명시한다 (배포/마이그레이션/외부 호출)
리뷰 기준은 3개 이하로 제한한다 (안정성, 테스트, 롤백 가능성)
설명형 문단을 줄이고 체크리스트로 바꾼다
많은 팀이 AGENTS.md를 친절한 온보딩 문서로 쓰는데, 에이전트 관점에서는 그게 노이즈가 됩니다. 사람에게 좋은 문서와 에이전트에게 좋은 문서는 다를 수 있습니다.
운영 관점 결론
이제 질문을 바꿔야 합니다.
- 이전 질문: AGENTS.md를 더 자세히 쓰면 성능이 오를까?
- 지금 질문: 이 작업에 필요한 최소 지시만 남겼나?
코딩 에이전트 시대의 품질은 모델 하나로 결정되지 않습니다.
컨텍스트 설계, 실행 루프, 검증 루프가 함께 만들어냅니다.
그리고 2602.11988이 던진 가장 실전적인 교훈은 이것입니다.
길고 친절한 지침보다, 짧고 실행 가능한 지침이 더 강하다.
Tech-Trappist: https://trappist-tech.vercel.app/
참고 아카이브
- Evaluating AGENTS.md — https://arxiv.org/abs/2602.11988
- SWE-bench — https://arxiv.org/abs/2310.06770
- SWE-bench Live — https://arxiv.org/abs/2505.23419
- SWE-rebench — https://arxiv.org/abs/2505.20411
- ContextBench — https://arxiv.org/abs/2602.05892
- SWE-ContextBench — https://arxiv.org/abs/2602.08316
시각 자료 (Charts)
- Cost impact: https://quickchart.io/chart/render/zf-ed941f7b-008d-4b77-81e5-6d38bc787bc1
- Success delta: https://quickchart.io/chart/render/zf-cbbbc7f4-2264-479a-8ca6-27ad76a7d50b
- Trade-off radar: https://quickchart.io/chart/render/zf-2b011730-b00e-4089-ac6f-6cf8eba8be23
- Benchmark stack map: https://quickchart.io/chart/render/zf-5908f0c2-8966-4ed4-a4e6-4bdf2a292c16