코딩 에이전트가 실제로 읽는 것 — 공식 문서가 아닌 지침 파일 (2026)

지침 파일이 가장 지배적인 문서 영역입니다

세부적으로 분석해 보면, 60.5%는 두 가지 카테고리로 나뉩니다. 에이전트 지침 파일은 "가장 자주 사용되는 문서 유형(1,074개 이벤트, 35.4%)"이며, "에이전트 풀 리퀘스트에서 가장 자주 변경되는 파일 중 하나"입니다. 계획, thoughts/ 디렉터리, 검증 로그 등의 에이전트 작업 노트는 25.1%를 차지합니다.

반면 API 레퍼런스는 문서 상호작용의 1.3%인 40개의 이벤트에 그쳤습니다. 이 격차에 대해 논문은 다음과 같이 요약합니다. 지침 파일은 API 레퍼런스보다 약 27배 더 많은 상호작용을 받습니다.

저자들이 제시하는 권장 사항은 구체적이고 실용적입니다. "에이전트 기여자를 지원하기 위해 제한된 문서 리소스를 할당하는 프로젝트의 경우, 이 차이는 지침 파일의 정확성과 명확성을 우선시해야 함을 시사합니다." "API 문서 작성을 중단하라"는 뜻이 아닙니다. API 문서는 이 연구에서 관찰하지 않은 인간과 도구들을 위한 것입니다. 다만 에이전트를 위해 1시간을 어디에 쓸지 고민 중이라면, 트래픽이 몰리는 곳은 바로 AGENTS.md라는 의미입니다.

에이전트는 링크를 따라가지 않습니다

이 발견은 거의 모든 도구가 제공하는 조언을 조용히 무너뜨립니다. "문서 읽기 이후에 추가적인 읽기가 뒤따르는 경우가 많지만(전이 확률 0.270), 참조 링크 따라가기(Follow-reference)는 전혀 관찰되지 않았습니다."

"전혀 관찰되지 않았다"는 것은 에이전트가 한 문서에서 다른 문서로 참조를 타고 이동한 사례가 단 한 건도 없었다는 뜻입니다. 저자들의 결론은 신중하게 유보적입니다. "이 패턴은 에이전트가 풍부하게 링크된 문서를 탐색할 것이라고 가정하기보다, 로컬에서 검색 가능한 구조를 가진 독립형(self-contained) 문서를 연구해야 할 동기를 부여합니다. 그러나 이것이 링크 관리(link hygiene)가 행동에 아무런 영향을 미치지 않는다는 것을 입증하는 것은 아닙니다."

여러분의 지침 파일이 대부분 링크 포인터로만 채워져 있다면 깊이 고민해 볼 문제입니다. "이유는 docs/architecture.md를 참조하세요"라는 문장은 문법적으로 완벽할지 몰라도, 에이전트는 아무런 행동도 취하지 않을 수 있습니다.

문서 참조와 코드 편집은 분리되어 있습니다

이 부분에서 논문은 자체적인 불확실성에 대해 매우 신중한 태도를 취합니다. 솔직히 요약하자면, 두 행위의 연결고리가 없는 것이 아니라 아직 명확히 규명되지 않은 상태입니다. 문서 읽기에서 코드 편집으로 바로 이어지는 인접 전이 확률은 0.002입니다. 보정되지 않은 3개 이벤트 리프트(lift)는 1.05로 사실상 무의미합니다. 단계 보정 모델을 적용하면 1보다 높은 OR 1.33 [1.09, 1.62]이 됩니다. 문서 생성은 반대 방향으로 움직입니다. 보정되지 않은 리프트는 1.67로 높게 나타나지만, "보정된 신뢰구간에는 1이 포함됩니다." 저자들의 표현대로라면 "두 연결고리 모두 사양 전반에 걸쳐 일관되지 않습니다."

즉, 에이전트는 문서를 읽은 후 대부분 추론을 하거나 다시 문서를 읽습니다. 문서 참조 영역 내에서 가장 강한 전이는 0.270(CI 0.232–0.307)의 확률로 다시 문서를 읽는 것이며, 외부로 나가는 가장 강한 움직임은 0.245(CI 0.205–0.295)의 확률로 추론 단계로 가는 것입니다.

아무도 문서를 바탕으로 검증하지 않으며, 문서를 참조할수록 테스트는 줄어듭니다

"명시적인 문서 기반 검증 시퀀스는 관찰되지 않았으며, 문서 참조는 즉각적인 테스트 감소와 관련이 있습니다(리프트 0.23, 클러스터 CI 0.08–0.45; 보정된 OR 0.39 [0.25, 0.60])." 다른 부분에서는 단호하게 "검증 이벤트 제로(0)"라고 밝히고 있습니다.

이것은 관찰 데이터에서의 상관관계일 뿐 인과관계를 주장하는 것이 아니며, 저자들 역시 인과관계를 주장하지 않습니다. 하지만 이는 에이전트가 작업을 마친 후 문서와 대조하여 검증할 수 있도록 문서를 작성해야 한다는 대중적인 아이디어가 이번 연구에서는 전혀 나타나지 않았음을 의미합니다.

에이전트는 막혔을 때가 아니라, 스스로 원해서 문서를 읽습니다

문서 참조는 70.2%가 스스로 시작한 것이며, 실패(에러)로 인해 유발된 경우는 7.5%에 불과했습니다. 실패 에피소드 중 문서 참조 루프로 피드백되는 비율은 5.4%에 그쳤습니다. 또한 문서는 코드를 이끌기보다 뒤따라가는 경향이 있습니다. "두 가지를 모두 변경하는 멀티 커밋 풀 리퀘스트 중에서, 코드가 문서보다 먼저 수정되는 경우가 4.7배 더 많았습니다."

저자들의 자체적인 설명이 흥미로운 부분입니다

인간 개발자의 행동을 설명하는 문헌과 일치하지 않는 루프를 발견한 저자들은 두 가지 가설을 제시하며 어느 하나를 선택하지는 않았습니다.

"에이전트는 컨텍스트 창(context window)이 제한되어 있기 때문에 추론 과정을 파일로 외재화할 수 있으며, 이로 인해 문서가 참조용이 아닌 일종의 작업 기억(working memory) 역할을 하게 됩니다. 계획 파일과 thoughts/ 디렉터리가 두드러지게 나타나는 것은 이러한 가능성과 일치합니다. 또는, 더 저렴한 오라클인 테스트 스위트가 직접 호출되기 때문에 텍스트 문서로 검증하지 않는 것일 수도 있습니다. 어떤 경우든, 우리는 텍스트 문서가 명세서(specification) 역할을 하는 것을 관찰하지 못했습니다."

이 단 하나의 가설은 60.5%라는 수치 전체를 새롭게 바라보게 만듭니다. 에이전트가 "읽는" 내용의 상당 부분은 불과 10분 전에 자신이 직접 작성한 노트일 수 있습니다. 정보를 둘 다른 곳이 없었기 때문입니다. 이는 현재 아무런 도구도 해결해주지 못하는 문제를 낳습니다. "계획, thoughts/ 디렉터리, 검증 로그는 리포지토리에 영구적인 아티팩트로 쌓입니다. 현재 리포지토리 정리 도구, 코드 리뷰 체크리스트, 문서 품질 지표에는 이러한 파일들을 분류할 카테고리가 없습니다."

수치의 한계를 정확히 파악하는 것이 헤드라인보다 중요하며, 이 논문의 한계점(limitations) 섹션은 이례적일 정도로 솔직합니다.

60.5%는 에이전트가 읽는 모든 것이 아니라, 문서 상호작용 중에서의 비율입니다. 분모는 전체 94,813개의 개발 이벤트 중 3,033개의 문서 상호작용입니다. "에이전트가 읽는 분량의 60.5%"가 아닙니다. 이를 에이전트 전체 활동에서의 비율로 인용하는 것은 왜곡입니다.

이 수치의 4분의 1은 명백히 잠정적인 것입니다. 이는 대부분의 2차 요약본에서 누락되는 경고이며, 저자들은 다음과 같이 명시했습니다. "agent_working_note 카테고리는 문서 이벤트의 25.1%를 차지하며 핵심 발견 중 하나이지만, 이는 500개의 모호한 경로에 대한 언어 모델 분류(모호한 이벤트의 98.4%)에 의존하고 있으며, 27개의 경로는 키워드 규칙으로 처리되었습니다. 이 라벨들에 대한 인간의 검증은 수행되지 않았습니다... 따라서 검증이 이루어지기 전까지 이 카테고리의 정확한 비율은 잠정적인 것으로 취급되어야 합니다." 저자들은 수치보다 정성적인 발견이 더 견고하다고 덧붙입니다. 에이전트가 작성한 작업 문서는 정확한 비율이 얼마든 간에 원시 경로에서 명확히 드러나는 "크고 이전에는 분류되지 않았던 클래스"라는 점입니다.

절대적인 비율은 하한선입니다. "문서는 파일 경로로 식별됩니다. 소스 파일에 포함된 독스트링(docstrings), 인라인 주석, 텍스트 설명은 우리 도구로 감지할 수 없습니다." 소스 코드 내 문서화를 선호하는 프로젝트는 과소대표되었으며, 저자들도 이를 인정합니다.

에이전트가 왜 읽는지에 대한 목적은 측정되지 않았습니다. "목적은 측정되지 않습니다... 설계상 우리는 에이전트가 특정 문서를 읽는 이유를 분석하지 않습니다." 이 연구는 의도가 아니라 트리거, 상호작용 유형, 결과만을 보고합니다.

관찰 연구이므로, 문서를 바꾼다고 해서 행동이 바뀐다는 것을 의미하지는 않습니다. 특히 실행 가능성(actionability)에 대해 다음과 같이 밝힙니다. "이러한 분석은 연결고리에 대한 일관된 행동적 증거를 제공하지 않으며, 우리의 관찰 연구 설계는 실행 가능성을 개선하는 것이 행동을 변화시킨다는 것을 보여줄 수 없습니다."

저자들은 가장 자극적으로 인용될 수 있는 비교를 스스로 거부했습니다. "우리는 문서 기반 복구(documentation-based recovery)가 가장 높은 점추정치(63.6%)를 기록했음에도 불구하고 이것이 더 효과적이라고 결론짓는 것을 명시적으로 거부합니다. 관찰 가능한 에피소드가 11개에 불과하여 신뢰구간이 35.4~84.8%에 달하고 모든 대안과 겹치기 때문입니다." 이는 연구 팀이 자극적인 헤드라인을 포기한 사례이며, 그렇기에 나머지 내용들을 신뢰할 수 있는 것입니다.

또한 이 연구는 다른 방향을 가리키는 연구들과 공존합니다. 2026년의 다른 연구들은 컨텍스트 파일이 성능에 미치는 영향을 측정했고 그 효과가 미미하거나 부정적임을 발견했습니다. 또 다른 연구 라인은 모델 기능에 따라 확장되는 큐레이션된 검색을 통한 성능 향상을 측정했습니다. 이는 AI 에이전트에게 메모리를 얼마나 주어야 할까에서 다룬 내용입니다. 본 논문은 성능이 아닌 행동을 측정합니다. 이 두 가지를 조화시키는 것은 앞으로 해결해야 할 과제이며, 이틀 전에 발표된 또 다른 논문은 우리의 측정 방법론이 아직 이를 수용할 준비가 되지 않았다고 주장합니다. 이에 대해서는 에이전트 메모리가 실제로 성능을 향상시킬까에서 논의했습니다.

MemoryLake는 이 연구에 참여하지 않았습니다. 이 연구의 어떤 내용도 당사나 타사의 메모리 레이어를 평가하지 않습니다.

"에이전트는 지침 파일을 무시한다." 연구 결과와 정반대되는 생각입니다. 지침 파일은 압도적인 차이로 가장 많이 읽히는 문서 영역입니다. 약한 것은 읽는 행위와 다음 행동 사이의 연결고리입니다. 이는 완전히 다른 주장이며, 이전에 에이전트가 내가 작성한 지침 파일을 무시하는 이유에서 다루었던 차이점입니다. 즉, 로딩하는 것과 따르는 것은 다릅니다. 이 논문은 이를 더욱 명확히 합니다. 에이전트는 파일을 로드하고 많이 읽지만, 읽는 행위가 행동을 안정적으로 결정하지는 못합니다.

"그러니 문서는 중요하지 않다." 이 논문은 이 코퍼스에서 실행 가능성과 검증 가능성이라는 두 가지 구체적인 주장이 행동적 지지를 받지 못한다고 말할 뿐입니다. 문서가 쓸모없다고 말하는 것이 아니며, 지침 파일의 정확성에 투자할 것을 명시적으로 권장합니다.

"에이전트는 막혔을 때 문서를 읽는다." 실패로 인한 트리거는 7.5%에 불과합니다. 트리거 분포가 가장 정면으로 반박하는 믿음입니다.

"상호 링크(Cross-linking)는 무의미하다." 이 트레이스에서 참조 링크 따라가기(Follow-reference)는 관찰되지 않았지만, 저자들은 링크 관리가 아무런 영향이 없다고 결론짓는 것은 거부했습니다. 이 둘은 서로 다른 진술입니다.

"이것은 에이전트에게 메모리 시스템이 필요하다는 증거다." 그런 것을 증명하지는 않습니다. 단지 에이전트가 작업 기억과 유사한 파일을 작성한다는 점을 관찰하고, 이를 행동 패턴에 대한 두 가지 가설 중 하나로 제시할 뿐입니다.

작업 기억 가설이 맞다면, thoughts/ 디렉터리와 계획 파일의 상당 부분은 에이전트가 가진 유일한 도구인 git 리포지토리를 사용해 메모리 관리를 수행하고 있는 것입니다. 여러분의 리뷰 프로세스 중 어떤 것도 이러한 파일을 분류할 카테고리를 가지고 있지 않습니다. 여기서 세 가지 결론이 도출됩니다.

무엇이 쌓이고 있는지 감사(Audit)하세요. 리포지토리에서 계획 파일, thoughts/ 디렉터리, 에이전트가 생성한 검증 로그를 검색해 보세요. 디렉터리별로 각 파일이 영구적인 아티팩트인지 아니면 임시 메모인지 결정하세요. 대부분의 팀은 자신도 모르게 두 가지 모두를 커밋하고 있었다는 사실을 발견하게 됩니다.

트래픽이 몰리는 지침 파일에 시간을 투자하세요. 에이전트가 1.3%만 열어보는 API 레퍼런스에 공을 들이는 것보다 지침 파일의 정확성과 명확성을 높이는 것이 훨씬 더 효과적입니다. 또한 참조 링크 따라가기(Follow-reference)가 관찰되지 않았으므로, 반드시 전달해야 하는 내용이라면 링크 포인터 대신 독립형 문장으로 작성하는 것이 좋습니다.

조정(Steering)과 기억(Remembering)을 분리하세요. 지침 파일은 항상 켜져 있고 이를 읽는 모든 도구에 의해 크기가 제한되므로, 영구적인 지식(결정 사항, 제약 조건, 기각된 접근 방식)이 가장 먼저 밀려나게 됩니다. 그러면 에이전트는 계획 파일을 작성하여 이를 재구성하려고 시도합니다.

이 마지막 문제를 해결하기 위한 것이 바로 MemoryLake입니다. 메모리를 읽고, 수정하고, 삭제할 수 있는 항목으로 관리하며, 리포지토리에 부작용으로 커밋하는 대신 관련이 있을 때 쿼리하여 사용합니다. 설정은 세 단계로 진행됩니다.

1단계: API 키 생성

MemoryLake에 로그인하고 API 키를 생성합니다. 연결하는 모든 도구에서 하나의 자격 증명만 사용하면 됩니다.

2단계: 첫 번째 메모리 업로드

하나의 주장만 담긴 짧은 항목들을 작성합니다. 현재 계획 파일에 들어가거나 아예 유실되고 있는 내용을 작성하세요:

제약 조건과 함께 내려진 결정 사항. 지침 파일에는 규칙으로만 명시되고 그 이유는 생략되기 쉬운 카테고리입니다.

이미 기각된 접근 방식과 그 이유. 기각된 내용을 명시해 두어야 새로운 세션에서 이를 다시 도출하는 헛수고를 막을 수 있습니다. thoughts/ 파일들이 기록하는 것이 바로 이 재도출 과정입니다.

아무도 알려주지 않는 환경적 사실. CI에서만 실패하는 테스트, 문서화되지 않은 속도 제한(rate limit), 두 마이그레이션 간의 순서 요구 사항 등입니다.

두 번 이상 전달한 수정 사항. 사람이 두 번 이상 말해야 했다면, 종료된 대화 속에 묻어두기보다 검색 가능한 곳에 두어야 합니다.

3단계: AI 및 에이전트 연결

사용하는 도구들을 연결합니다. MemoryLake는 MCP 및 API를 통해 액세스할 수 있으므로, Claude Code, Codex, OpenClaw 등의 MCP 네이티브 에이전트는 MCP 서버를 가리켜 연결하고, 다른 어시스턴트들은 API를 통해 동일한 메모리를 읽습니다. 검색된 내용은 항상 켜져 있는 지침 파일의 크기를 늘리지 않으며, 커밋 기록에도 남지 않습니다.

세 가지 솔직한 한계가 있으며, 첫 번째가 이 글의 핵심입니다. MemoryLake는 이 연구에 참여하지 않았으며, 이 논문은 메모리 레이어가 에이전트 행동을 변화시킨다는 증거가 아닙니다 — 연구 설계는 관찰 기반이며, 저자들은 문서를 개선하는 것이 에이전트의 행동을 변화시킨다는 것을 보여줄 수 없음을 명시했습니다. 메모리는 오직 사용자나 에이전트가 기록한 내용만을 담습니다. 또한 리포지토리를 자동으로 정리해주지 않습니다. 에이전트가 이미 커밋한 계획 파일을 감사하는 것은 수동 작업입니다.

지침 파일이 일급(first-class) 문서로 격상됩니다. 가장 많이 읽히는 영역임에도 불구하고, 대부분의 리포지토리에서 README보다 덜 검토됩니다.

에이전트가 작성한 노트가 검토 카테고리가 됩니다. 현재는 정리 도구도, 체크리스트 항목도, 만료 지표도 없는 무풍지대입니다.

포인터가 콘텐츠를 대체할 수 없게 됩니다. 참조 링크 따라가기는 관찰되지 않았습니다. 중요한 제약 조건이라면 필요한 곳에 직접 명시하세요.

문서가 실패 복구 계획의 역할에 머무르지 않게 됩니다. 에이전트는 막혔을 때가 아니라 선제적으로 문서를 참조하므로, 매뉴얼보다는 오리엔테이션에 가까운 형태로 작성되어야 합니다.

가장 중요한 시간을 지침 파일에 투자하세요. 코퍼스에서 API 레퍼런스보다 약 27배 더 많이 읽히는 문서 유형입니다.

각 진술을 독립형(self-contained)으로 만드세요. 참조 링크를 타고 이동하는 행위는 관찰되지 않았습니다. 독자가 열어본 파일에서 멈춘다고 가정하세요.

에이전트 작업 노트의 보관 장소와 라이프사이클을 지정하세요. 무엇이 영구 아티팩트이고, 무엇이 임시 메모이며, 무엇이 커밋되지 말았어야 했는지 결정하세요.

문서를 검증 도구로 신뢰하지 마세요. 검증 이벤트는 전혀 관찰되지 않았습니다. 테스트야말로 에이전트가 실제로 활용하는 오라클입니다.

항상 켜져 있는 파일에서 추론 과정을 배제하세요 — 모든 도구는 이 파일들의 크기를 제한하며 추론 과정이 가장 먼저 잘려 나갑니다. 이는 RAG가 메모리가 아닌 이유에서 다룬 문제입니다. 그리고 흩어진 노트들을 검색 가능한 형태로 통합하세요. 이는 프로젝트 문서를 AI 메모리로 전환하기의 형태입니다.

단일 코퍼스 기반의 행동 연구 결과는 잠정적인 것으로 취급하세요. 두 개의 데이터셋, 경로 기반으로 식별된 문서, 저자들이 검증되지 않았다고 밝힌 하나의 작업 노트 카테고리입니다. 유용하지만 완전히 정립된 것은 아닙니다.

코딩 에이전트는 실제로 무엇을 읽을까요? 557개의 세션과 33,097개의 풀 리퀘스트를 분석한 결과, 압도적으로 자신들을 위해 작성된 파일을 읽는 것으로 나타났습니다. 에이전트 지침 파일과 에이전트 작업 노트가 문서 상호작용의 60.5%를 차지한 반면, 전통적인 기술 문서는 10.6%, API 레퍼런스는 1.3%였습니다.

하지만 비율보다 중요한 것은 행동의 순서입니다. 에이전트는 막혔을 때가 아니라 스스로 원해서 문서를 참조하고, 코드로 넘어가기보다 읽기와 추론 단계를 맴돌며, 다른 문서로의 참조 링크를 따라가지 않고, 텍스트 문서와 대조하여 작업을 검증하는 모습은 관찰되지 않았습니다. 저자들의 해석에 따르면, 이 중 상당수는 참조를 찾는 행위가 아닐 수 있습니다. 제한된 컨텍스트 창으로 인해 에이전트가 추론 과정을 파일로 외재화하게 되면서 "문서가 참조용이 아닌 일종의 작업 기억 역할을 하게 되는 것"입니다.

이 가설이 맞다면, 실질적인 결론은 "문서를 더 잘 쓰자"가 아닙니다. 여러분의 리포지토리가 인지하지 못하는 사이에 에이전트의 연습장이 되었으며, 이를 검토할 프로세스가 없다는 점입니다. 조회가 집중되는 지침 파일에 투자하세요. 링크를 따라가지 않으므로 진술은 독립형으로 작성하세요. 그리고 결정 사항, 제약 조건, 이미 기각된 접근 방식과 같은 영구적인 지식은 바이트 제한이 있는 항상 켜져 있는 파일이나 아무도 검토하지 않는 thoughts/ 디렉터리가 아닌 다른 곳에 보관하세요.