Executive Summary

이 보고서가 딛고 선 숫자는 넷이다. 앞의 둘은 에이전트가 여는 문서의 구성이 우리 예상과 다르다는 쪽을 가리키고, 뒤의 둘은 그 문서가 읽힌 뒤에 무슨 일이 일어나지 않았는지를 가리킨다. 넷 다 분모와 조건이 붙어 있어서, 조건을 떼면 전부 틀린 문장이 된다.

이 연구가 재미있는 이유는 결과보다 먼저 그 결과를 만든 계측기를 의심했다는 데 있다. 논문은 두 개의 공개 데이터셋을 쓰는데, 둘을 절대 합치지 않는다. 저자들의 표현으로는 "we never pool their units", 두 데이터셋의 단위를 한 번도 섞지 않았다는 뜻이다. 하나는 과정을 보고 다른 하나는 산출물을 본다.

과정 쪽은 SWE-chat이다. 실사용자와 코딩 에이전트가 주고받은 세션 약 6,000건, 툴 호출 355,000건에서 559건을 층화 표집했고 이벤트 파싱에 실패한 2건을 빼 557세션이 남았다. 여기서 개발 이벤트 94,813건이 나왔다. 산출물 쪽은 AIDev로, 에이전트가 연 풀리퀘스트 932,791건과 저장소 116,211개가 원 코퍼스이고 큐레이트한 부분집합 33,596건 중 분석 가능한 33,097건을 썼다. 앞의 것이 섹션 2~4를, 뒤의 것이 섹션 5를 떠받친다. 두 숫자를 한 문장에 넣는 순간 논문이 하지 않은 주장을 하게 된다.

1.1계측기는 무엇을 못 보는가

이 글에서 가장 자주 오해될 숫자를 먼저 처리해 두는 편이 낫다. "API 레퍼런스 1.3%"는 에이전트가 API 문서를 안 본다는 뜻이 아니다. 계측기가 보는 것은 저장소 경로로 해석되는 파일 접근뿐이다. 브라우저로 여는 API 웹사이트, 이미 모델 가중치 안에 들어가 있는 지식, 소스 코드 안의 docstring은 전부 계측 바깥이다. 그러므로 저 숫자의 정확한 뜻은 하나다. 저장소 안에 파일로 놓인 API 레퍼런스를 여는 일은 거의 없었다.

반대 방향의 편향도 하나 있다. 지시문 파일 수치는 실제 노출의 하한이다. 런타임이 세션 시작 시점에 자동으로 주입하는 컨텍스트 파일은 툴 호출로 남지 않고, 에이전트가 나중에 명시적으로 다시 열거나 고칠 때만 이벤트가 된다. 이건 추측이 아니라 벤더가 문서에 써 둔 동작이다.

편향 방향이 이쪽이라는 사실은 우리 논지를 약화시키지 않고 강화한다. 지시문 파일의 실제 몫은 아래에서 볼 35.4%보다 크면 컸지 작지 않다는 뜻이기 때문이다. 논문이 자기 수치의 편향 방향을 스스로 밝힌 대목이라 그대로 옮겨 둔다.

1.2보이지 않던 게 아니라 못 보고 있었다

이 섹션의 중심 장면은 연구자들이 자기 파이프라인에서 잡아낸 결함 두 건이다. 둘 다 결과 발표 뒤에 누가 지적한 것이 아니라 논문 안에 스스로 적어 놓은 것이다.

첫째, 어떤 에이전트 계열은 파일 작업을 셸 명령으로 우회한다. 그래서 셸 히어독 안에 든 경로를 파싱하지 않으면 그 계열 전체가 문서 이벤트 0건으로 잡혔다. 둘째, 툴 출력이 문자열이 아닌 형식으로 오는 경우를 추출기가 받지 못하고 있었다. 그 형식을 지원하자 세션 9건과 이벤트 4,358건이 한꺼번에 복구됐고, 그중 문서 이벤트가 77건이었다.

같은 이유로 논문은 에이전트별 비교를 금지한다. 표에는 Gemini CLI 9/12, Claude Code 238/380, Cursor 0/11 같은 값이 실려 있지만, 저자들은 이 차이가 행동 차이가 아니라 추출 커버리지 차이와 교락돼 있다고 못박는다. 방금 본 셸 우회 사례가 바로 그 교락의 실물이다. 그러니 "어떤 에이전트가 문서를 더 잘 읽는다" 류의 문장은 이 데이터로 쓸 수 없다.

1.3이 숫자들을 어디까지 믿을 것인가

인용하기 전에 붙여야 할 단서가 넷이다. 하나, 문서 유형을 가르는 2단 분류기의 2단계는 언어 모델이 맡았다. 모호한 경로 527개 중 500개를 모델이 라벨링했고 사람 검증(κ·α)은 하지 않았다. 그래서 아래 나올 작업 메모 25.1%는 잠정치다. 둘, 코퍼스의 87%가 단일 에이전트 계열이고 라벨이 붙은 세션 중 Claude Code가 83.8%다. 셋, 불확실성은 클러스터 부트스트랩 2,000회 재표집으로 냈고 다중비교 보정은 하지 않았으므로 인접한 계층 간의 작은 차이는 해석하지 않는다. 넷, 동료 심사를 거치지 않은 preprint다. 저자는 2인, 2026년 8월 20일 제출, 현재 v1만 있다.

마지막 항목에는 반대편 무게도 달아 둬야 공평하다. 논문은 추출 파이프라인과 코딩 스킴, 이벤트 수준 데이터를 공개하고 본문의 모든 표를 분석 출력에서 직접 생성한다. 검증 가능한 형태로 내놓았다는 뜻이고, 이 글이 그 표들을 그대로 옮겨 쓸 수 있는 이유이기도 하다.

그리고 하나만 미리 말해 둔다. 계측 도구가 곧 결론을 만든다면, 지금 이 보고서를 만들고 있는 파이프라인도 같은 종류의 대상이다. 그 이야기는 섹션 6에서 한다.

분모부터 다시 확인하자. 557세션에서 나온 개발 이벤트는 94,813건이고, 그중 문서 상호작용은 3,033건이다. 전체의 3.2%다. 문서 이벤트가 하나라도 있는 세션은 316건으로 56.7%(클러스터 95% CI 52.6~60.5%)였다. 아래 표의 백분율은 전부 이 3,033건을 분모로 한다. 에이전트가 하는 일 전체의 분포가 아니라, 에이전트가 문서를 열었을 때 그 열림이 어디로 갔는지의 분포다.

표를 볼 때 눈이 가야 할 자리는 위쪽 두 줄과 아래쪽 아홉 줄이다. 위 두 줄은 에이전트를 위해 존재하는 파일이고, 아래 아홉 줄은 우리가 보통 "기술 문서"라고 부르는 장르다. 전자가 1,834건, 후자가 323건이다.

문서 유형별 이벤트 분포(n=3,033). 60.5%의 세션 클러스터 95% CI는 53.9~66.5%다. 고전적 기술 문서 9개 장르는 API 레퍼런스·트러블슈팅·아키텍처·스키마·설치·예제·테스트·컨트리뷰팅·체인지로그를 말한다.

컨트리뷰팅 가이드는 1건이다. 트러블슈팅은 11건. 지시문 파일은 API 레퍼런스보다 약 27배 자주 열렸다. 이 대비를 눈으로 보는 편이 빠르다. 아래 막대는 위 표의 상위 열 줄을 같은 축에 올린 것으로, 오렌지 두 개가 에이전트용 범주다.

2.160.5%를 혼자 인용하면 안 되는 이유

논문은 이 경계가 논쟁적이라는 것을 스스로 밝힌다. README와 설정, 요구사항까지 사람용으로 치면 고전적 문서 몫은 10.6%가 아니라 33.8%가 된다고 병기한다. 반대로 작업 메모를 아예 문서로 치지 않으면 분모가 2,273으로 줄어 지시문 파일 단독이 47.2%가 된다. 이것도 저자가 직접 계산해 병기한 대안이다. 어느 쪽이든 지시문 파일이 제일 크다는 순위는 바뀌지 않지만, 60.5%라는 값 자체는 범주 경계를 어디에 긋느냐에 따라 움직인다.

더 중요한 흔들림은 가중 방식 쪽에 있다. 기본 수치는 이벤트를 하나씩 세는 방식이라 이벤트를 많이 낸 세션이 많이 반영된다. 세션마다 같은 무게를 주면, 또는 에이전트 계열별로 재가중하면 값이 달라진다.

아래 표에 나오는 조회와 생산은 논문이 다섯 가지 상호작용 유형을 둘로 묶은 것이다. 조회는 읽기 1,328건과 검색 282건, 발견 5건을 합친 1,615건이고, 생산은 편집 1,007건과 생성 394건을 합친 1,401건이다. 이 구분을 붙들고 봐야 다음 표의 가운데 줄이 무슨 말인지가 잡힌다.

가중 방식별 민감도. 가운데 줄이 이 표의 핵심이다.

2.2범주가 없으면 현상도 안 보인다

이 표에서 진짜 새로운 항목은 60.5%가 아니라 두 번째 줄이다. 에이전트 작업 메모, 그러니까 계획서와 thoughts/ 디렉토리와 브레인스톰과 리뷰 로그. 이 범주는 기존 문서 분류 체계 어디에도 없었다. 논문이 밝힌 대로, 2024년 이전에 만들어진 파일 유형 분류 체계에는 agent_instruction도 agent_working_note도 없다. 그 체계로 이 데이터를 돌리면 에이전트 문서 상호작용의 과반이 "잔여" 버킷으로 떨어진다.

그러니까 이 논문이 새 현상을 발견한 방법은 새 관측 장비를 만든 것이 아니라 범주를 두 개 추가한 것이었다. 섹션 1의 계측 결함 두 건과 정확히 같은 구조다. 무언가를 셀 칸이 없으면 그것은 데이터에 나타나지 않고, 나타나지 않으면 관리 대상도 아니다.

한 가지 덧붙일 것은, 이 분포가 우연이 아니라는 점이다. AGENTS.md 표준 사이트는 사람용 문서와 에이전트용 문서를 의도적으로 갈라 놓자고 명시적으로 제안했다.

논문이 잰 분포는 그 설계가 행동으로 나타난 결과이기도 하다. 다만 여기에 비어 있는 칸이 하나 있다. 분리가 실제로 읽히는지는 표준이 설계했지만, 분리가 도움이 되는지는 아무도 설계하지 않았다. 그 질문이 섹션 3과 4다.

여기서부터가 이 논문이 다른 문서 연구와 갈라지는 지점이다. 무엇을 열었는지가 아니라 열고 나서 무엇을 했는지를 본다. 문서를 조회한 이벤트 1,615건을 앵커로 잡고, 그 직후 창에서 다섯 가지 행동이 나타나는 비율을 세션 전체 기저 93,198건과 비교했다.

표를 읽을 때는 오른쪽 두 열을 함께 봐야 한다. 비보정 lift는 원자료 그대로의 비이고, 보정 오즈비는 개발 단계·세션 내 위치·로그 세션 길이·에이전트 계열을 통제한 로지스틱 GEE 모형의 값이다. 두 열이 같은 방향을 가리키는 행만 결론으로 쓸 수 있다.

문서 조회 직후 행동(앵커 1,615 / 기저 93,198). 앵커를 읽기 이벤트만으로 좁혀도(n=1,328) 결론은 바뀌지 않는다.

위 두 행은 방향이 갈린다. 문서 생성은 비보정에서 유의하게 올라갔다가 보정하면 구간이 1을 물고, 코드 편집은 비보정에서 차이가 없다가 보정하면 올라간다. 논문은 이 둘을 미결(unresolved)이라 부르고 결론으로 삼지 않았다. 우리도 그렇게 한다. 어느 쪽으로 보정해도 남는 발견은 아래 두 행, 테스트와 빌드의 감소뿐이다.

같은 다섯 행을 1.0 기준선 위에 놓으면 그 비대칭이 한눈에 들어온다. 가운데 세로선이 "차이 없음"이고, 점 두 개가 모두 왼쪽에 있는 행만 감소로 읽을 수 있다.

3.11,328번 읽고 3번 고쳤다

위 표는 "직후 창" 기준이라 사이에 다른 행동이 끼어도 잡힌다. 창을 좁혀 바로 다음 이벤트만 보면 그림이 더 선명해진다. 문서를 읽은 직후에 코드 편집이 오는 확률은 0.002 [0.000, 0.005]다. 문서 읽기 1,328번 중 3번이었다는 뜻이다.

그럼 나머지 1,325번은 무엇으로 이어졌을까. 가장 흔한 다음 행동은 또 다른 문서 읽기(0.270)였고 그다음이 추론(0.245)이었다. 문서 읽기는 고립된 사건이 아니라 연속으로 일어난다. 읽고, 또 읽고, 생각한다. 그 흐름이 코드로 넘어가는 지점은 인접 전이로는 거의 잡히지 않는다.

그리고 논문이 단계 모형에 넣어 두었던 Validate(검증)와 Escalate(사용자에게 상신)는 3,033건 전체에서 0건이었다. 여기서 정확한 표현을 붙여야 한다. 이것은 "에이전트가 검증을 하지 않는다"가 아니다. 조회 뒤에 테스트나 빌드를 실행하는 정의된 툴 호출 패턴이 0건이라는 뜻이다. 정확히 말하면, 문서를 근거로 무언가를 검증했다고 볼 만한 툴 호출 흔적이 한 건도 남지 않았다. 논문 자신이 이 단서를 두 번 반복해 적어 두었다.

3.2막혀서 문서를 여는 게 아니었다

문서를 여는 계기도 통념과 다르다. 우리는 보통 에이전트가 막히면 문서를 찾아본다고 생각한다. 데이터는 반대쪽을 가리킨다. 자발적으로 문서를 연 것이 2,129건(70.2%, CI 66.7~73.3%)인데, 실패가 유발한 조회는 228건(7.5%, CI 6.0~9.3%)에 그친다. 9.3배 차이다. 내역을 보면 에이전트 자체 판단 1,236건, 구현 필요 893건, 사용자 지시 618건 순이고, 테스트 실패로 문서를 연 것은 7건, 빌드 오류 때문은 4건이었다.

실패 뒤의 행동을 따로 보면 더 분명하다. 실패 에피소드 2,034건에서 첫 복구 행동은 코드 읽기 631건(31.0%), 그대로 재시도 404건(19.9%), 관측 구간 내 무행동 318건(15.6%), 바로 편집 312건(15.3%), 코드 검색 251건(12.3%) 순이었다. 문서 읽기는 109건, 5.4%다. 툴 오류가 났을 때 다음 행동이 문서 읽기일 확률은 0.020이다.

3.3오즈비 0.39를 어떻게 읽을 것인가

관측 연구라서 인과는 말할 수 없다. 문서를 읽어서 테스트를 덜 돌린 것인지, 테스트를 덜 돌릴 만한 국면에서 문서를 열게 되는 것인지 이 데이터로는 가릴 수 없다. 논문은 양성 해석도 하나 제시한다. 에이전트가 더 싼 오라클을 갖고 있기 때문일 수 있다는 것이다. 테스트 스위트를 직접 부르면 되는데 굳이 산문을 대조할 이유가 없다는 뜻이다.

그러니 이 글의 주장은 "문서를 읽으면 게을러진다"가 아니고 "문서가 해롭다"도 아니다. 훨씬 좁고 그만큼 확실한 문장 하나다. 산문이 명세로 기능한 흔적이 행동 로그에 남지 않았다. 문서가 정답을 규정하고 에이전트가 그것과 대조해 자기 결과를 확인하는 절차, 우리가 "에이전트 친화적 문서"를 말할 때 암묵적으로 가정하는 바로 그 절차를 이 데이터에서는 찾을 수 없다.

문서 이용에 관한 우리의 머릿속 그림은 대체로 선형이다. 찾고(Discover), 가져오고(Retrieve), 해석하고(Interpret), 적용하고(Apply), 검증하고(Validate), 갱신한다(Update). 논문은 이 여섯 단계를 코딩 스킴에 넣고 3,033건을 분류해 봤다. 결과는 선이 아니었다.

표에 실린 후보 단계는 열 개다. 위의 여섯에 더해, 첫 쓰기 이전 국면인 방향 잡기(Orient), 읽기 바로 뒤에 또 읽기가 오는 재방문(Revisit), 실패 뒤 첫 복구 행동이 문서 읽기였던 복구(Recover)를 따로 세웠다. 각 단계의 정의는 개념이 아니라 관측 가능한 툴 호출 패턴이다. 맨 윗줄의 기여·갱신은 상호작용 유형이 편집이거나 생성인 이벤트를 가리킨다.

단계별 이벤트 수(n=3,033). 단계는 서로 배타적이지 않아 합이 3,033이 되지 않는다.

저자들은 여기에 더해 초기 스킴에 있던 Compare · Follow-reference · Verify 세 단계를 아예 제거했다. 툴 호출로는 한 건도 관측되지 않았기 때문이다. 남은 그림은 두 개의 덩어리다. 하나는 조회 쪽으로, 읽기가 읽기로 이어지고(0.270) 추론으로 흐른다(0.245). 다른 하나는 생산 쪽으로, 1,401건의 최대 범주이고 문서 편집이 문서 편집으로 이어지는 확률이 0.350이다. 두 덩어리는 얇게만 연결돼 있다.

규모로도 대등하다. 조회 1,615건에 생산 1,401건. 생산이 조회의 0.87배다. 에이전트는 읽는 만큼 쓴다. 아래 도식은 그 두 덩어리와, 둘 사이에 있어야 할 자리가 비어 있다는 사실을 함께 그린 것이다.

저자들은 이 모양에 대해 두 가지 가설을 나란히 놓는다. 하나는 컨텍스트 창이 유한하기 때문에 에이전트가 문서를 외부 작업 기억으로 쓴다는 것이다. 읽은 것을 붙잡아 두지 못하니 다시 읽고, 정리해서 파일로 쓴다. 다른 하나는 앞에서 본 더 싼 오라클 가설이다. 둘 다 데이터와 모순되지 않고, 이 연구는 둘을 가리지 않는다.

4.1효과 문헌은 난장판처럼 보인다

여기까지가 "얼마나 읽히는가"다. 그런데 실무자가 진짜 궁금한 것은 "도움이 되는가"이고, 그건 다른 질문이다. 이 논문은 그 질문에 답하지 않는다. 답하려 한 연구는 따로 있는데, 결론이 서로 엇갈린다. 개선이 있다는 쪽, 없다는 쪽, 내용과 무관하다는 쪽, 조건부라는 쪽이 다 있다.

그런데 각 연구가 개선을 발견한 축을 나란히 놓으면 이야기가 달라진다. 아래 표는 우리가 그 축을 정렬해 본 것이다. 미리 밝혀 둘 것이 있다. 이 정렬은 우리 해석이고, 어느 논문도 이 표를 그린 적이 없다. 각 연구는 서로 다른 것을 쟀을 뿐이다.

지시문 파일의 효과를 잰 여섯 연구를 측정 축별로 정렬한 것. 정렬은 이 보고서의 해석이며 원 논문들의 결론이 아니다.

4.2무작위 규칙도 큐레이트한 규칙만큼 도왔다

위 표에서 가장 아픈 줄은 두 번째다. Zhang 외는 규칙 파일 679개, 규칙 25,532개를 모아 5,000회 이상 실행을 돌렸다. 그리고 무작위로 뽑은 규칙을 붙였을 때와 정성껏 큐레이트한 규칙을 붙였을 때의 성능 향상이 같았다(+13.8pp). 규칙을 뒤섞어도, 도메인이 안 맞아도, 포맷을 안 바꿔도 결과가 동등했다.

여기서 성급한 결론으로 뛰면 안 된다. 이 발견은 "규칙이 무용하다"가 아니다. 규칙은 분명히 듣는다. 다만 내용이 아니라 극성이 듣는다는 것이다. 같은 연구에서 유익한 것으로 분류된 규칙은 전부 금지형("하지 마라")이었고, 유해한 것으로 분류된 규칙은 전부 지시형("이렇게 해라")이었다. 무엇을 쓰느냐보다 어느 방향으로 쓰느냐가 결과를 갈랐다.

여기에 비대칭이 하나 겹친다. 사람은 내용에 공을 들인다. 개발자들이 실제로 컨텍스트 파일에 쓰는 항목을 조사한 연구를 보면 테스트 절차가 75.9%, 구현 세부가 70.8%, 아키텍처가 68.1%다. 정성이 들어가는 쪽은 분명히 내용이다. 그런데 그 정성이 결과에 기여하는 몫은 위 연구가 말하는 것과 따로 논다. 들이는 비용과 얻는 효과가 서로 다른 축에 놓여 있는 셈이다.

나머지 줄도 같은 방향이다. Shepard & Albrecht는 가이드를 정교화했을 때 개선이 전부 커버리지에서 왔고 패치당 정밀도는 움직이지 않았다고 보고한다. 좋은 가이드는 올바른 파일에 도달하게 해 주지 거기서 하는 일의 품질을 높이지 않는다는 뜻이다. Gloaguen 외는 지시는 잘 따르지만 저장소 개요는 도움이 안 되고 비용만 20% 늘었다고 했고, Khatri는 개선 상한을 10~15pp로 잡으면서 아깝게 실패하던 케이스가 통과로 바뀐 사례가 0건이었다고 적었다. 실패의 원인은 문서가 아니라 구현 기량이었다는 것이다.

4.3llms.txt는 공급 측 증거만 넷이다

같은 렌즈를 llms.txt에 대 보면 흥미로운 구조가 나온다. 2026년 8월 10일 개정된 v2 문서가 채택 근거로 드는 것은 넷이다. 수천 개 사이트가 파일을 발행하고, 문서 플랫폼이 자동 생성하고, Chrome Lighthouse가 agentic browsing 감사 항목에 넣었고, 주요 모델 제공사들이 자체 개발자 문서에 발행한다. 넷 다 공급 측이다. 누가 만들었는지의 증거이지 누가 읽었는지의 증거가 아니다.

소비 측 주장은 문서 뒷부분에 딱 한 문장 나오는데, 위 인용이 그것이고 측정도 출처도 붙어 있지 않다. 그리고 공개 학술 문헌에도 그 측정은 없다. 이 보고서가 확인한 범위에서 llms.txt의 효과를 에이전트 행동 데이터로 잰 연구는 존재하지 않는다. 가장 가까운 것이 두 편인데 둘 다 답이 아니다. Volpini 외는 llms.txt 스타일 지시를 포함한 묶음이 RAG 정확도를 약 30% 올렸다고 보고하지만 단독 효과가 아니고 대상도 코딩 에이전트가 아니다.

다른 하나가 더 시사적이다. Borysenko는 코딩 에이전트 9종과 AI 어시스턴트 6종이 문서 포털에 남기는 HTTP 요청 지문을 분석했다. 서버 측에서 에이전트 행동을 직접 잰 드문 연구인데, 발견은 효과 측정이 아니라 계측 붕괴다. 에이전트는 사람이 여러 페이지를 돌아다니며 하던 탐색을 한두 요청으로 압축한다. 그래서 세션 깊이, 체류 시간, 클릭 경로, 이탈률 같은 기존 참여 지표가 문서 소비의 신뢰할 수 없는 지표가 됐다는 것이다.

이건 제안자를 탓할 자리가 아니다. 논문 자신도 실행 가능성이 여전히 바람직할 수 있다고 적었다. 반증된 것은 조언의 유해함이 아니라 그 조언을 뒷받침할 행동 근거의 부재다. 그리고 부재를 부재로 확인하려면 재는 방법이 있어야 하는데, Borysenko의 발견은 그 방법조차 아직 다시 만들어야 한다는 쪽을 가리킨다. 규칙 문서를 규칙별로 실지 테스트하는 하네스가 왜 필요한지는 앞선 리포트에서 다룬 적이 있다.

여기서 데이터셋이 바뀐다. 지금까지가 세션 안의 과정이었다면, 이제 보는 것은 저장소에 남은 산출물이다. AIDev의 에이전트 풀리퀘스트 33,097건 중 문서를 건드린 것이 13,750건(41.5%)이었다. 코드와 문서를 함께 바꾼 PR이 10,586건(32.0%), 문서만 바꾼 PR이 3,164건(9.6%), 코드만 바꾼 PR이 17,988건(54.3%)이다.

그중에서 가장 자주 수정된 문서 파일이 어느 것이었는지가 이 섹션의 출발점이다. 개별 파일 단위로 세면 AGENTS.md가 692건의 풀리퀘스트에서 고쳐졌고, CLAUDE.md가 362건, copilot-instructions.md가 287건으로 뒤를 잇는다. 상위 세 자리를 사람이 읽을 문서가 아니라 에이전트에게 주는 지시문이 나눠 가졌다.

에이전트가 가장 자주 고치는 문서는 에이전트에게 주는 지시문이다. 출력이 다시 입력이 되는 두 번째 루프가 여기서 닫힌다. 그런데 이 대목을 "통제되지 않은 루프가 생겼다"로 쓰면 사실관계가 틀린다. 이건 사고가 아니라 사양이다.

같은 문서가 설명하는 auto memory는 모델이 스스로 기억 파일을 쓰는 공식 기능이고, 매 세션 로드되며 첫 200줄 또는 25KB라는 용량 상한이 붙어 있다. 그러니까 에이전트가 자기 지시문을 고치는 것은 제품이 의도적으로 만든 동작이다. 정확한 문장은 이렇게 된다. 통제되지 않은 루프가 생긴 것이 아니라, 제품이 의도적으로 만든 루프에 아직 리뷰 게이트가 없다.

위 인용문에서 눈여겨볼 대목이 하나 더 있다. 벤더 스스로 지시문을 "강제되는 설정이 아니라 컨텍스트"라고 규정하고, 진짜 막아야 하면 훅을 쓰라고 안내한다. 섹션 4에서 본 네 번째 축, 산문으로는 안 되고 컴파일하면 된다는 이야기가 여기서는 제품 아키텍처로 이미 구현돼 있다.

5.1코드가 먼저 바뀌고 문서가 따라온다

코드와 문서 중 어느 쪽이 먼저 바뀌는지도 셀 수 있다. 다만 조건이 붙는다. 커밋이 여럿이라 순서가 관측되는 PR은 4,386건이고, 그중 코드가 먼저인 것이 2,076건(47.3%), 같은 커밋에 든 것이 1,870건(42.6%), 문서가 먼저인 것이 440건(10.0%)이다. 코드 선행이 문서 선행의 4.7배다. 42.6%는 애초에 순서가 없으므로 "문서가 코드보다 4.7배 늦다"로 일반화하면 안 된다. 조건을 좁혀 코드와 문서가 다른 커밋에 있는 2,516건만 보면 코드 선행이 82.5%(클러스터 CI 78.7~86.0%)다.

머지율 쪽에는 손대지 않는 편이 낫다. 문서를 건드린 PR의 머지율이 81.1%, 코드만 바꾼 PR이 75.0%로 나오지만 저장소 클러스터 구간이 겹쳐서 논문은 결론을 내지 않았다. 헷갈리기 쉬운 이웃 결과가 하나 있어서 미리 갈라 둔다. 다른 연구에서 "문서화 작업 PR의 머지 승인율이 가장 높다(82.1% 대 66.1%)"는 결과가 나온 적이 있는데, 그건 작업 유형을 가른 것이고 이 논문은 파일 접촉 여부를 갈랐다. 다른 질문이므로 섞어서 "문서 관련 PR이 더 잘 머지된다"로 합성하면 둘 다 잘못 인용하는 셈이 된다.

5.2지우는 비용이 더한 비용보다 비싸다

지시문 파일이 계속 자란다는 것은 실무자들 사이의 체감이었는데, 이제 측정치가 있다. Chakrabarti는 저장소 1,867개에서 지시 247,694건의 수명을 추적해, 지시문 파일이 수명 동안 평균 +226% 커지고 커밋마다 순증 4.9개가 붙는다고 보고한다. 더 눈여겨볼 것은 삭제 쪽이다. 오래된 지시일수록 지워질 확률이 낮다(로그 해저드 커밋당 −0.032). 오래 살아남은 규칙일수록 더 오래 살아남는다.

원인은 비용 구조에 있다. 한 줄 덧붙이는 비용은 늘 싸다. 그런데 이미 있는 규칙을 지우려면 그 규칙이 왜 들어왔는지, 지금도 유효한지, 다른 규칙과 어떻게 얽혀 있는지를 확인해야 한다. 저자는 이 상태에 catastrophic remembering이라는 이름을 붙였다. 모델이 학습한 것을 잊어버리는 catastrophic forgetting의 반대말이다. 논문 말미의 수사는 이렇다. 영어가 새로운 코드라면, 왜 우리에겐 아직 주석이 없는가. 수사이지 발견은 아니지만 문제의 모양은 정확히 짚는다.

자라기만 하는 게 아니라 낡기도 한다. Treude와 Baltes는 기존의 README·위키 일관성 검사기를 대표 표본 저장소 356개에 적용해, 23.0%에서 더 이상 존재하지 않는 코드 요소를 참조하는 대목을 찾아냈다. 이름 붙은 명칭은 context rot다.

처방은 두 층위에서 서로 다르게 나왔다. 학계 쪽은 근거를 남기라고 한다. Chakrabarti는 각 지시에 근거 주석을 붙였을 때 검증 가능한 환경에서 초과 지시의 99.3%를 제거할 수 있었다고 보고한다. 벤더 쪽은 용량으로 막는다. auto memory에 200줄 또는 25KB 상한을 걸었고, Skills는 필요할 때만 로드하는 지연 방식을 택했다. 모순이 아니라 같은 병에 대한 다른 층위의 대응이고, 공통 조건이 하나 있다. 지우려면 왜 넣었는지가 남아 있어야 한다. 이름표 없는 기억을 지울 수 없다는 이야기는 앞선 리포트에서 따로 다뤘다.

5.3작업 메모는 어디로 가는가

마지막으로 대비 하나. 섹션 2에서 본 대로 세션 안에서 작업 메모는 문서 상호작용의 25.1%를 차지한다. 그런데 저장소에 남은 것을 세면 이야기가 완전히 달라진다. Abubakar 외가 저장소 36,710개를 훑어 찾아낸 계획 파일은 10개 저장소에 85건이 전부였다.

지금까지의 발견을 문서화 정책의 언어로 옮기면 "지시문을 잘 쓰자"쯤이 된다. 그 번역은 절반도 담지 못한다. 세 갈래 조사가 각각 하나씩 확인한 공백이 있는데, 셋 다 문서를 어떻게 쓰느냐의 문제가 아니라 문서를 무엇으로 취급하느냐의 문제이기 때문이다.

세 트랙이 각각 확인한 공백. 데이터 자산이라면 당연히 있어야 할 스키마·품질 지표·규모 집계 셋이 전부 비어 있다.

데이터 자산에는 스키마가 있고 품질 지표가 있고 규모 집계가 있다. 문서가 에이전트의 입력이 된 지 한참인데 셋 다 없다는 것이 이 보고서가 도달한 지점이다. 그래서 이것은 문서 정책의 문제가 아니라 데이터 설계의 문제다.

6.1우리 CLAUDE.md에는 삭제 정책이 없다

남의 시스템 이야기로 끝내면 값이 싸다. 이 보고서를 만든 파이프라인에 같은 잣대를 대 봤다. 아래는 이 글을 쓰는 시점, 2026년 8월 23일에 이 작업 트리에서 직접 잰 값이다.

2026-08-23 이 작업 트리 실측. 마지막 줄의 파일들은 논문이 새로 정의한 "에이전트 작업 메모" 범주에 그대로 들어간다.

논문의 발견을 하나씩 대 보면 이렇다. 지시문이 append로 커진다고 했다. 우리 CLAUDE.md 646줄에는 삭제 정책이 없고, 오래된 항목일수록 안 지워진다는 조건이 그대로 갖춰져 있다. 에이전트가 자기 지시문을 고친다고 했다. 우리도 그렇게 하고 있고 리뷰 게이트는 사람이 보는 PR 하나뿐이다. 작업 메모가 저장소에 남는다고 했다. 남기는 하는데, 그 산출물 중에서 무엇이 관측이고 무엇이 이전 단계 에이전트의 추정인지를 구별할 컬럼이 없다.

6.2이번 실행에서 실제로 치른 대가

점검이니까 마침 이번에 난 사고도 적어 둔다. 이 보고서의 조사 단계는 세 갈래로 갈라져 있다. 논문 트랙, 업계 트랙, 데이터 트랙. 그런데 이번 실행에서 세 트랙이 전부 같은 트랙을 수행했다. 논문 트랙과 업계 트랙 둘 다 "데이터 트랙을 완료했다"고 보고했고, 자기 몫의 출력 파일은 만들지 않았다. 그러고도 세 단계 모두 상태가 "완료"로 기록됐다. 합성 단계에서 파일 존재를 직접 확인하지 않았다면 데이터 트랙 하나만 갖고 이 글을 썼을 것이다.

기획서에는 이미 이렇게 적혀 있었다. "각 트랙은 자기 출력 파일 하나를 생성했는지 확인하고 끝낼 것(과거 런에서 반복된 실패다)." 산문으로 정확하게 지시돼 있었고, 지켜지지 않았고, 지켜지지 않았다는 사실이 어디에도 기록되지 않았다.

6.3오늘부터 세울 수 있는 장치 넷

조직이 오늘 시작할 수 있는 것으로 옮기면 넷이다. 앞의 셋은 위에서 본 공백 셋과 하나씩 짝이 맞고, 마지막 하나는 지위가 다르니 그 지위를 밝혀서 적는다.

하나, 지시문 파일과 작업 메모를 별개 자산 종류로 등록한다. 분류 체계에 칸이 없으면 감사도 없다. 논문이 새 현상을 발견한 방법이 범주 두 개를 추가한 것뿐이었다는 사실이 근거다.

둘, 에이전트가 쓴 문서와 사람이 쓴 문서를 구별해 기록한다. 생성 주체 한 컬럼이 감사 가능성을 만든다. 지금은 어떤 표준 도구도 이 축을 갖고 있지 않다. 에이전트가 쓴 산출물에 게이트를 세운 사례는 이 글에서 다룬 적이 있다.

셋, 지시문 파일에 수명과 상한을 준다. 무한 append는 실패 모드다. 학계는 근거 주석을, 벤더는 용량 상한과 지연 로딩을 택했다. 어느 쪽이든 공통 조건은 삭제의 근거를 남기는 것이다.

넷, 반드시 지켜야 할 규칙은 산문이 아니라 실행 가능한 형태에 둔다. 검증 시퀀스가 한 건도 관측되지 않은 이상, 규칙은 문서가 아니라 린터·스키마·훅·테스트에 있어야 관측 가능해진다.

네 번째의 지위는 정확히 밝혀 둬야 한다. 이건 논문이 "개입 연구를 위한 가설이지 이 연구의 발견이 아니다"라고 스스로 못박은 제안이다. 다만 서로 무관한 세 갈래가 같은 방향을 가리키고 있다. 논문은 산문 대신 실행 가능한 산출물을 가설로 제시했고, 벤더는 이미 제품 아키텍처로 구현했으며(강제되는 설정이 아니라 컨텍스트, 진짜 막으려면 훅), 별개의 개입 연구인 ContextCov는 같은 제약을 AST 질의와 런타임 셸 shim, 구조 검증기로 컴파일했을 때 준수율이 67.0%에서 88.3%로 올랐다고 보고한다.

여기에도 단서 셋을 붙인다. ContextCov는 이 논문과 무관한 별개 연구다. 논문 참고문헌에 없으므로 "논문의 제안이 검증됐다"로 읽으면 안 된다. 실험 환경은 SWE-bench Lite라는 벤치마크다. 그리고 잰 것은 제약 준수율이지 과제 성공률도 문서 품질도 아니다. 세 갈래가 같은 방향을 가리킨다까지가 정확한 진술이고, 검증됐다는 아니다.

마지막으로 이 보고서가 반증하지 않은 것을 적어 둔다. 실행 가능한 문서, 검증 가능한 문서라는 조언이 틀렸다는 이야기가 아니다. 논문 자신이 그것이 여전히 바람직할 수 있다고 썼다. 확인된 것은 그 조언을 뒷받침할 행동 근거가 아직 없다는 사실 하나다. 그리고 근거가 없는 이유의 상당 부분은 아무도 재지 않았기 때문이다. 재려면 범주가 있어야 하고, 범주를 만드는 일은 문서를 쓰는 일이 아니라 데이터를 설계하는 일이다. 우리 자신의 파이프라인에서도 아직 하지 않은 일이다.

1차 출처

• 1.Gao, Z., Chen, J., "From Agent Behaviour to Agent-Friendly Documentation: An Empirical Study of How Coding Agents Discover, Read, and Write Technical Documentation," 2026-08-20 (v1, 14 pages, 1 figure, 10 tables). arXiv:2608.20195 — 본문의 Table 1·2·3·4·8·9·10 수치 전부의 출처

효과·개입 (학술)

• 2.Zhang, X. 외, "Guardrails Beat Guidance: A Large-Scale Study of Rules, Skills, and Persistent Configuration for Coding Agents," 2026. arXiv:2604.11088v2 — 무작위 규칙 +13.8pp 동등, 금지형과 지시형의 갈림
• 3.Gloaguen, T. 외, "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?," 2026. arXiv:2602.11988v2 — 성공률 불변, 비용 20% 증가
• 4.Khatri, P., "Do Context Files Help Coding Agents? A Two-Agent Ablation Study on Real Repositories," 2026. arXiv:2607.27250v1 — 개선 상한 10~15pp, near-miss 전환 0건
• 5.Lulla, J. L. 외, "On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents," 2026. arXiv:2601.20404v2 — 런타임 −28.64%, 출력 토큰 −16.58%
• 6.Shepard, A., Albrecht, J., "Probe-and-Refine Tuning of Repository Guidance for Coding Agents," 2026. arXiv:2606.20512v2 — 커버리지 +14.5pp, 정밀도 불변(p=0.119)
• 7.Sharma, R. K., "ContextCov: Deriving and Enforcing Executable Constraints from Agent Instruction Files," 2026. arXiv:2603.00822v2 — 준수율 67.0% → 88.3%, SWE-bench Lite 12 repos·300 tasks

수명·유지보수

• 8.Chakrabarti, K., "Why Does CLAUDE.md Keep Growing? Catastrophic Remembering in Agentic Coding," 2026. arXiv:2608.11095v1 — 지시 247,694건·저장소 1,867개, 수명 동안 +226%, 근거 주석으로 초과 지시 99.3% 제거
• 9.Treude, C., Baltes, S., "Context Rot in AI-Assisted Software Development," 2026. arXiv:2606.09090v1 — 대표 표본 356개 저장소 중 23.0%에서 낡은 코드 참조
• 10.Liu, S. 외, "Context as a Tool," 2025. arXiv:2512.22087v1

아티팩트 기술 연구

• 11.Chatlatanagulchai, W. 외, "Agent READMEs: An Empirical Study of Context Files for Agentic Coding," 2025. arXiv:2511.12884v2 — 컨텍스트 파일 2,303개, 테스트 절차 75.9%·구현 70.8%·보안 14.8%
• 12.Chatlatanagulchai, W. 외, "On the Use of Agentic Coding Manifests: An Empirical Study of Claude Code," 2025. arXiv:2509.14744v1
• 13.Mohsenimofidi, S. 외, "Context Engineering for AI Agents in Open-Source Software," 2025. arXiv:2510.21413v4
• 14.Abubakar, M. A. 외, "An Exploratory Study of Agent Plans for Agentic AI Coding Tools in OSS," 2026. arXiv:2608.04661v2 — 저장소 36,710개 중 계획 파일은 10개 저장소에 85건
• 15.Hora, A., Montandon, J. E., Costa, D. E., "What's Inside a GitHub Repository?," 2026. arXiv:2605.16701v2
• 16.Treude, C., Baltes, S., Cheong, M., "Operationalizing Ethics for AI Agents," 2026. arXiv:2605.05584v1

데이터셋 원논문

• 17.Baumann, J. 외, "SWE-chat: Coding Agent Interactions From Real Users in the Wild," 2026 (ODC-BY, 2026-08-19 스냅샷). arXiv:2604.20779v1 — 과정 증거의 출처
• 18.Li, H., Zhang, H., Hassan, A. E., "AIDev: Studying AI Coding Agents on GitHub," 2026. arXiv:2602.09185v1 — 산출물 증거의 출처

행동·실패 궤적

• 19.Ehsani, R. 외, "Where Do AI Coding Agents Fail?," 2026. arXiv:2601.15195v1 — 문서화 작업 PR의 머지 승인율 82.1% 대 66.1%(본문에서 다른 질문으로 분리한 결과)
• 20.Majgaonkar, O. 외, "Understanding Code Agent Behaviour," 2025. arXiv:2511.00197v1
• 21.Borysenko, O., "Developer Experience with AI Coding Agents: HTTP Behavioral Signatures in Documentation Portals," 2026. arXiv:2604.02544v2 — 에이전트 트래픽 앞에서 세션 깊이·체류 시간·이탈률이 무의미해졌다는 보고
• 22.Volpini, 외, llms.txt 스타일 지시를 포함한 묶음의 RAG 정확도 효과, 2026. arXiv:2603.10700 — 단독 효과가 아니며 대상도 코딩 에이전트가 아님

표준·산업 1차 문서

• 23.agents.md — AGENTS.md 표준 사이트 ("README.md files are for humans" 원문, 채택 저장소 60k+ 자기 보고). agents.md (2026-08-23 열람)
• 24.Howard, J., "The /llms.txt file," v2 (2024-09-03 발행, 2026-08-10 개정). llmstxt.org (2026-08-23 열람) — "coding agents follow them to find API references and tutorials" 원문
• 25.Anthropic, "How Claude remembers your project" (CLAUDE.md · auto memory 200줄/25KB 상한). docs.claude.com (2026-08-23 열람) — "context, not enforced configuration" 원문
• 26.Anthropic, "Agent Skills — Overview" (온디맨드 지연 로딩). platform.claude.com (2026-08-23 열람)
• 27.GitHub, "Adding repository custom instructions for GitHub Copilot." docs.github.com (2026-08-23 열람)
• 28.Cursor, "Rules." cursor.com (2026-08-23 열람) — "rule contents are included at the start of the model context" 원문
• 29.Diátaxis — 문서 프레임워크 홈·개요 (에이전트 독자가 핵심 프레임에 아직 없음을 확인). diataxis.fr (2026-08-23 열람)
• 30.GitHub, Octoverse 2025 / Stack Overflow, Developer Survey 2025 — 코드·에이전트 생태계 규모 대비 문서 소비 통계의 부재를 확인한 근거

페블러스 인접 (교차 링크)

• 31.페블러스, "이름표 없는 기억은 지울 수 없다" — 작업 메모의 계보와 삭제 근거. report/agent-memory-provenance-deletion
• 32.페블러스, 다중 에이전트 공유 자원 충돌 실측 — 우리 에이전트 함대를 우리가 계측한 선례. report/multiagent-shared-resource-turf-war-2026-08
• 33.페블러스, 에이전트가 쓴 지식그래프에 게이트를 세운 사례. blog/agent-written-knowledge-graph-gate
• 34.페블러스, 규칙 문서를 규칙별로 실지 테스트한 하네스. report/agent-loops-harness-over-model