코딩 에이전트는 API 문서보다 AGENTS.md를 먼저 읽었다
코딩 에이전트를 위한 문서를 만든다고 하면 보통 API 레퍼런스나 상세한 개발 가이드부터 떠올린다. 그런데 실제 에이전트의 작업 기록을 분석한 연구에서는 다른 문서가 훨씬 자주 등장했다. AGENTS.md, CLAUDE.md 같은 지시 파일과 계획·작업 노트였다.
2026년 8월 공개된 논문 From Agent Behaviour to Agent-Friendly Documentation은 공개된 코딩 에이전트 세션과 풀 리퀘스트를 이용해 에이전트가 어떤 문서를 읽고 쓰는지 조사했다.
연구진이 분석한 데이터는 다음과 같다.
- SWE-chat의 파싱 가능한 세션 557개
- 개발 이벤트 94,813개
- 문서 관련 이벤트 3,033개
- AIDev의 에이전트 풀 리퀘스트 33,097개
- 파일·커밋 단위 변경 기록 690,260개
에이전트가 가장 자주 만진 문서
문서 상호작용에서 가장 큰 비중을 차지한 것은 에이전트 지시 파일이었다.
| 문서 유형 | 이벤트 수 | 비중 |
|---|---|---|
| 에이전트 지시 파일 | 1,074 | 35.4% |
| 계획·작업 노트 | 760 | 25.1% |
| 작업 및 요구사항 문서 | 301 | 9.9% |
| 설정 문서 | 205 | 6.8% |
| README | 197 | 6.5% |
| API 레퍼런스 | 40 | 1.3% |
지시 파일과 작업 노트를 합하면 전체 문서 상호작용의 60.5%다. API 레퍼런스는 1.3%에 그쳤다. 지시 파일이 API 레퍼런스보다 약 27배 많이 관찰된 셈이다.
코딩 에이전트의 문서 관련 이벤트 분포. 지시 파일과 계획·작업 노트가 전체의 60.5%를 차지했다. 출처: Gao & Chen, arXiv:2608.20195v1.
이 수치를 "API 문서는 필요 없다"고 해석하면 곤란하다. 연구가 추적한 것은 저장소 안에서 명시적으로 열린 파일이다. 웹 문서, 모델이 이미 학습한 지식, 코드 주석, 런타임이 자동으로 주입한 문맥은 잡히지 않는다. 정확한 결론은 코딩 에이전트가 저장소 안에서 작업할 때 지시 파일과 작업 노트가 매우 큰 비중을 차지했다는 것이다.
문서를 읽으면 바로 코드를 고칠까
그렇다고 보기 어려웠다.
문서를 읽은 직후 코드 수정으로 이어진 경우는 1,328건 중 3건이었다. 문서 읽기 다음에는 추가 문서 읽기나 추론이 더 자주 나타났다. 세 이벤트 안에서 코드 수정이 발생할 가능성도 분석 방법에 따라 결론이 달라졌다.
더 눈에 띄는 결과는 테스트와 빌드였다.
| 후속 행동 | 문서 상담 후 확률 | 평상시 기준 확률 | 비율 |
|---|---|---|---|
| 테스트 실행 | 0.5% | 2.2% | 0.23배 |
| 빌드 | 0.4% | 2.5% | 0.15배 |
연구진이 정의한 관찰 범위에서는 "문서를 읽고 그 내용에 따라 테스트하거나 빌드한다"는 명시적 연속 행동이 한 건도 발견되지 않았다.
이 결과도 조심해서 봐야 한다. 에이전트가 나중에 테스트했거나, 테스트 의도가 문서 읽기와 직접 연결돼 있었지만 도구 호출 순서에 드러나지 않았을 수 있다. 이 연구가 보여준 것은 검증을 하지 않았다는 사실이 아니라 문서 상담과 검증 사이의 연결이 관찰 데이터에 나타나지 않았다는 점이다.
문서는 코드보다 늦게 바뀌었다
문서와 코드를 함께 수정한 여러 커밋짜리 풀 리퀘스트에서는 코드가 먼저 변경되는 경우가 많았다.
- 코드 먼저: 47.3%
- 같은 커밋: 42.6%
- 문서 먼저: 10.0%
서로 다른 커밋에서 순서를 명확히 관찰할 수 있는 경우만 보면 82.5%가 코드 먼저였다. 에이전트가 문서를 읽고 계획대로 구현한 뒤 문서를 갱신한다는 일직선 흐름보다는, 문서를 읽는 과정과 문서를 생산하는 과정이 느슨하게 반복되는 형태에 가까웠다.
흥미로운 점은 에이전트가 AGENTS.md나 CLAUDE.md도 직접 수정했다는 것이다. 한 에이전트가 남긴 결과가 다음 에이전트의 지시가 된다. 잘못된 규칙이나 임시 판단도 같은 방식으로 증폭될 수 있다.
저장소에 적용할 때 바꿀 것
이 연구만으로 좋은 지시 파일의 정답을 알 수는 없다. 문서 품질이 작업 성공률을 높인다는 인과관계를 측정한 연구도 아니다. 그래도 관리 우선순위는 조정할 수 있다.
루트 지시 파일은 짧고 정확하게 유지한다
에이전트가 자주 읽는 파일에 오래된 명령이나 서로 충돌하는 규칙이 있으면 영향 범위가 크다. 빌드 명령, 테스트 방법, 수정 금지 영역, 저장소 구조처럼 작업 전에 반드시 알아야 할 정보만 루트에 둔다.
세부 규칙은 코드 가까이에 둔다
모노레포의 모든 규칙을 루트 문서 하나에 몰아넣으면 관계없는 작업에도 긴 문맥이 따라간다. 패키지나 하위 디렉터리마다 필요한 규칙을 가까운 위치에 두는 편이 낫다.
작업 노트에도 수명을 정한다
계획과 리뷰 로그는 임시 파일처럼 보이지만 다음 에이전트가 읽는 지속 문서가 된다. 완료된 계획을 계속 남길지, 보관 폴더로 옮길지, 일정 기간 뒤 삭제할지 정해야 한다.
문장만 쓰지 말고 실행 가능한 검증을 붙인다
"테스트를 실행하라"는 문장보다 실제 명령과 실패 조건이 낫다. 스키마 검사, doctest, lint, 빌드 스크립트처럼 규칙을 기계적으로 확인할 수 있게 만들면 문서와 검증 사이의 끊어진 고리를 줄일 수 있다. 다만 이 효과는 이번 논문이 입증한 결과가 아니라 후속 실험이 필요한 가설이다.
지시 파일 변경도 코드처럼 리뷰한다
에이전트가 자신의 행동 규칙을 수정할 수 있다면 그 변경은 일반 문서 수정 이상의 의미가 있다. 지시 파일 변경을 별도 diff로 확인하고, 임시 해결책이 영구 규칙으로 남지 않았는지 검토할 필요가 있다.
결론
코딩 에이전트 시대의 핵심 문서는 개발자를 위한 API 설명서만이 아니다. 에이전트가 작업 방향을 정하는 지시 파일과 다음 작업자가 이어받는 계획·작업 노트가 새로운 인터페이스가 됐다.
하지만 많이 읽힌다는 사실이 좋은 결과를 보장하지는 않는다. 이 논문에서 문서 읽기와 코드 수정의 연결은 분석 방식에 따라 달라졌고, 문서 기반 검증 흐름은 관찰되지 않았다. 그래서 문서를 더 많이 만드는 것보다 지시 파일을 짧고 정확하게 관리하고, 중요한 규칙을 실행 가능한 검사와 연결하는 쪽이 현실적인 대응이다.
원문
- Zhijun Gao, Jing Chen, From Agent Behaviour to Agent-Friendly Documentation: An Empirical Study of How Coding Agents Discover, Read, and Write Technical Documentation
- arXiv:2608.20195v1, 2026-08-20
- https://arxiv.org/abs/2608.20195v1
댓글
댓글 쓰기