결론부터. 코딩 에이전트의 문서 상호작용 60.5%는 AGENTS.md, CLAUDE.md, thoughts/ 같은 ‘에이전트 전용 파일’이었다. 우리가 흔히 생각하는 기술 문서 — API 레퍼런스, 아키텍처 문서, 트러블슈팅 가이드 — 는 각각 1.3%, 0.4%에 불과했다. 문서 도구 투자의 우선순위를 다시 정해야 한다는 얘기다.
베이징대 연구팀이 8월 20일 공개한 “From Agent Behaviour to Agent-Friendly Documentation”(arXiv:2608.20195)의 결과다.
무엇을 측정했나
연구팀은 두 개의 공개 데이터셋을 썼다.
| 데이터 | 규모 | 단위 |
|---|---|---|
| SWE-chat | 세션 557개, 이벤트 94,813개 | 실제 에이전트 코딩 세션 트랜스크립트 |
| AIDev | PR 33,097개 | 에이전트가 연 GitHub 풀리퀘스트 |
SWE-chat에서 문서 상호작용은 총 3,033건. 세션의 56.7%가 최소 한 번은 문서를 읽거나 고쳤다. 관측은 리포지토리 내 파일 경로 기반이라 브라우저로 읽은 외부 문서나 모델 가중치 안의 지식은 안 보인다. 이 논문의 모든 주장은 이 관측 범위 안에서다.
Figure 1. 전체 결과 요약. (a) 문서 유형별 비중, (b) 문서 열람 후 3이벤트 내 행동, (c) 트리거 분포, (d) 후보 스테이지별 근거, (e) 코드-문서 선행 관계. (arXiv:2608.20195 Figure 1)
핵심 발견 1: 지배적인 문서 유형이 새로 생겼다
Table 1 분포가 이 논문의 중심 결과다.
| 문서 유형 | 이벤트 | 비중 |
|---|---|---|
| 에이전트 인스트럭션 파일 (AGENTS.md 등) | 1,074 | 35.4% |
| 에이전트 워킹 노트 (계획, thoughts/, 검증 로그) | 760 | 25.1% |
| 태스크/요구사항 | 301 | 9.9% |
| 설정 | 205 | 6.8% |
| README | 197 | 6.5% |
| API 레퍼런스 | 40 | 1.3% |
| 트러블슈팅 | 11 | 0.4% |
인스트럭션 파일 단독으로 API 레퍼런스의 약 27배 상호작용을 받는다. 문서 리서치 전통은 API 레퍼런스 품질이 중심이었는데, 에이전트 소비자의 실제 행동은 정반대다.
여기서 내 해석을 하나 얹으면: 에이전트 시대에 문서의 중심 카테고리 자체가 이동하고 있다. 워킹 노트(25.1%)는 에이전트가 자기 쓰는 문서까지 포함한 수치고, 이걸 빼도 인스트럭션 파일만 47.2%다.
핵심 발견 2: 문서 읽고 곧바로 코드 수정은 거의 없다
“문서 읽고 → 코드 수정”이라는 상식적 그림의 인접 전이 확률은 0.002. 문서 1,328회 읽기 뒤 바로 코드를 고친 건 3번이었다. 대신 문서 읽기 뒤에는 추가 문서 읽기(0.270)나 추론(0.245)이 이어진다.
3이벤트 범위로 보면 코드 수정 리프트는 1.05로 기저와 차이가 없고, 스테이지 보정을 하면 OR 1.33 [1.09, 1.62]로 살짝 올라간다.
보정 전후가 일치하지 않아서 저자는 이 연결을 “미해결”로 분류했다.
더 흥미로운 건 검증 쪽이다. 문서를 읽은 직후에는 오히려 테스트 실행이 리프트 0.23, 빌드가 0.15로 줄어든다. 이건 보정 후에도 유지되는 유일한 강한 신호다. 그리고 “문서를 기준으로 코드를 검증한” 명시적 사례는 0건이었다.
핵심 발견 3: 실패해서 문서를 찾는 게 아니다
트리거 분포를 보면 문서 상호작용의 70.2%는 자기 주도 (에이전트 자신의 판단 40.8% + 구현상 필요 29.4%)였고, 실패 유발은 7.5%에 불과했다. 자기 주도가 실패 유발의 9.3배다.
실패 에피소드 2,034건의 첫 복구 행동을 봐도 문서 읽기는 5.4%(109건)뿐. 에이전트는 코드를 다시 읽거나(31.0%) 같은 행동을 재시도하고(19.9%), 문서를 찾지 않는다. “막히면 문서”라는 통념은 이 데이터에서 지지되지 않는다.
핵심 발견 4: 문서는 코드를 따라간다
AIDev 풀리퀘스트의 41.5%가 문서를 변경한다. 코드 수정 대비 문서 생산 비율은 0.87배로, 문서가 입력이자 출력이다.
근데 순서가 비대칭이다. 코드와 문서를 모두 바꾸는 멀티커밋 PR에서 순서가 관측되는 경우, 코드가 먼저인 경우가 82.5%다. 전체 비율로는 코드 먼저 47.3%, 같은 커밋 42.6%, 문서 먼저 10.0%. 문서는 코드를 안내하지 않고, 코드 변경 뒤에 뒤따라오는 기록에 가깝다.
관측된 모델: 상담·생산 두 이엽 구조
연구팀이 처음 가정한 모델은 인간 개발자 정보 탐색 연구에서 온 선형 여정이었다: Discover → Retrieve → Interpret → Apply → Validate → Update.
데이터는 이 모델을 세 가지 이유로 기각한다.
- Validate와 Escalate 스테이지는 관측 0건
- Apply는 75건으로 약하게 관측될 뿐
- 마지막 단계인 Contribute/Update가 1,401건으로 오히려 최대
대신 나온 그림은 느슨하게 결합된 두 개의 이엽이다. 상담(consultation) 이엽은 스스로 반복하며(Orient → Discover → Retrieve → Interpret, 읽기→읽기 전이 0.270) 추론으로 빠진다. 생산(production) 이엽은 문서를 쓰고 고친다. 두 이엽 사이의 연결은 어느 분석에서도 일관되게 강하지 않다.
설계 시사점 — 지원되는 것과 아닌 것
저자가 조심스러운 부분이 이 논문의 미덕이다. 데이터가 지지하는 시사점:
- 인스트럭션 파일이 가장 중요한 문서 표면이다. 한정된 문서 리소스가 있다면 AGENTS.md의 정확성과 명확성이 우선이다.
- 문서 읽기는 연쇄적으로 일어나므로(0.270) 링크를 따라가는 문서보다 자기완결적이고 로컬에서 검색 가능한 구조가 유리하다.
- 워킹 노트는 새로운 유지보수 표면이다. 리포지토리 위생 도구와 리뷰 체크리스트에 이 카테고리가 아직 없다.
- 실행 가능한 문서(러너블 예제, 도ctest, 스키마 계약)만이 검증을 관측 가능하게 만들 수 있다는 가설.
데이터가 지지하지 않는 통념들:
- 액션어빌리티(읽으면 바로 행동하게 쓰라는 조언) — read→act 결합이 관측 안 됨
- 검증가능성 — 검증 이벤트 0건
- 문서=실패 복구 자원 — 트리거 7.5%, 복구 5.4%
정리
“에이전트 친화적 문서” 담론의 상당 부분은 직관 위에 서 있었다. 이 논문은 그 위에 행동 데이터를 올려놓는다. 에이전트의 문서 세계는 인간용 문서 세계와 다르고, 지금 당장 영향력 있는 문서 표면은 인스트럭션 파일이다. 다음에 문서 개선 예산을 배정한다면 API 레퍼런스 다듬기 전에 AGENTS.md부터 점검하는 순서가 이 데이터와 맞다.
원문: arXiv:2608.20195, 추출 파이프라인·코딩 스킴·이벤트 데이터 공개 예정.
더 실습해보고 싶은 분들께
에이전트 하네스와 컨텍스트 관리를 직접 다뤄보고 싶다면: