문서 드리프트(Documentation Drift)는 과거 인간 개발자들에게 큰 문제였습니다. 그들의 시간을 낭비하게 만들었죠. 이제는 코딩 에이전트(coding agents)가 잘못된 행동을 취하게 하거나, 심지어 잘못된 변경 사항을 배포하게 만들 수도 있습니다.

이전에는 지루했던 문서 관련 문제들이 이제는 코딩 에이전트에 의해 잘못된 변경 사항이 배포되는 시점에 영향을 미칠 수 있기 때문에, 완전히 새로운 차원의 중요성을 갖게 되었습니다.

소프트웨어 문서화 도구들은 과거에 전달(delivery) 프로세스 옆에 머물러 있었습니다. 온보딩(onboarding), 감사(audits), 지원(support), 아키텍처 리뷰(architecture reviews), 그리고 왜 특정 모듈이 여전히 SOAP를 사용하는지 이해하려는 가끔씩 나타나는 용감한 영혼들을 도와주었죠. 하지만 코딩 에이전트는 해당 문서를 실행 경로(execution path) 안으로 이동시킵니다. AGENTS.md, CLAUDE.md, 리포지토리 위키(repo wikis), 루브릭(rubrics), 런북(runbooks), 그리고 생성된 요약본에 담긴 단어들이 운영 지침(operating instructions)이 됩니다.

LangChain은 OpenWiki, 즉 코딩 에이전트를 위한 리포지토리 문서 생성 및 유지 관리를 위한 오픈 소스 에이전트 및 CLI를 통해 이러한 기능을 명시적으로 구현하고 있습니다. 에이전트가 리포지토리에서 명령을 실행하기 위한 리포지토리 지식의 문서로서, 리포지토리 문서는 이제 에이전트의 기질(substrate)이기도 합니다.

문서는 이제 런타임(runtime)의 일부입니다

인간은 최악의 문서가 있더라도 언제나 문제를 "해결"할 수 있습니다. 느리긴 하지만 사실입니다. 시니어 엔지니어가 해야 할 일은 지난 분기에 결제 경로(billing path)가 어떻게 이동했는지 기억해내고, 누가 그 문제의 문서 페이지를 작성했는지 찾아내고, blame을 확인하고, Slack에서 대화 내용을 검색한 뒤, 문서를 수정하는 것뿐입니다. 아주 식은 죽 먹기죠.

반면, 코딩 에이전트의 실패는 매우 교묘합니다. 왜냐하면 일을 하고 있다는 구실 하에, 심지어 잘못된 것이라도 커밋(commits)으로 남기 때문입니다. 예를 들어, 결제 경로가 이전 서비스에 있었다는 문서상의 잘못된 가정이나 드리프트(drift)는 diff에 직렬화(serialized)되어 마치 생산적인 작업처럼 보이게 됩니다!

코드 문서화 AI(Code documentation AI)는 하나의 운영 경계(operational boundary)가 되었습니다. 어제의 프롬프트 캐시(prompt-cache) 논의는 컨텍스트 순서가 어떻게 런타임 정책이 되었는지에 관한 것이었습니다. 이것은 그보다 한 단계 더 낮은 계층, 즉 캐싱되고, 검색되고, 요약되며, 준수되는 실제 리포지토리 지식(repo knowledge)에 관한 것입니다.

따라서 빈번하게 수정되는 파일(hot files)은 보통 저주받은 존재로 여겨지지만, 에이전트가 일련의 지침을 따르고 그에 상응하는 문서 세트가 존재한다는 단순한 사실은, 특정 프로젝트의 AGENTS.md 및 CLAUDE.md에 대한 문서가 전체 리포지토리 지식의 일부로서 유지 관리될 수 있음을 의미합니다. 프로젝트 README에 따르면 OpenWiki는 openwiki/ 디렉토리를 생성하거나 업데이트하고, 에이전트 지침을 추가하며, openwiki --init 및 openwiki --update를 지원하고, 문서 업데이트를 위한 GitHub Action 템플릿을 포함합니다.

작은 hot file. 검색된 cold knowledge. 유지 관리 루프.

Hot file은 코드베이스의 전체 이야기를 직접 담는 것이 아니라, 유지 관리되는 리포지토리 지식(repo knowledge)을 가리켜야 합니다.

Hot file에는 코드 빌드, 테스트 및 실행을 위한 명령, 서비스 및 패키지 저장 위치, 서비스의 소유권 범위, 적용될 보안 제약 조건, 서비스가 라우팅될 수 있는 위치와 같이 코드의 모든 실행에 적용되는 규칙이 포함되어야 합니다. 모든 에이전트 실행은 파일에 추가된 모든 쓰레기(junk)에 대한 비용을 지불해야 하므로, Hot file이 그 과정에서 내려진 모든 아키텍처 결정 사항들을 모아두는 저장소가 되어서는 안 됩니다.

거대한 프롬프트 덤프(prompt dump)는 게으른 해결책입니다

물론, 그 모든 지식을 가지고 할 수 있는 가장 당연한 방법은 전체 위키를 프롬프트에 포함하는 것입니다. 결국, 컨텍스트가 많을수록 좋지 않겠습니까? 하지만 그 길에는 광기가 도사리고 있습니다. 그리고 그것은 단순히 노이즈 때문만은 아닙니다. 위키의 지식은 특정 부분에서 오래되었을 가능성이 높고, 모델은 단지 가장 관련 있어 보이는 첫 번째 문단에 달라붙기만 할 것입니다.

Chroma의 context-rot 작업은 태스크의 복잡성을 일정하게 유지하면서 입력 길이를 늘리는 데 도움을 주며, 테스트된 18개 모델에 걸쳐 컨텍스트가 커질수록 LLM 성능이 덜 신뢰성 있게 된다는 것을 발견했습니다. 이 에세이의 핵심은 단순히 정보가 컨텍스트 안에 존재하는 것만으로는 충분하지 않다는 것입니다. 그 정보가 어떻게 제시되는지가 중요합니다.

마찬가지로, 대규모 코드베이스에서도 엄청난 양의 Markdown을 작성할 수 있지만, 핵심은 어떤 컨텍스트가 실제로 '핫(hot)'하고 검색되고 있는지, 무엇이 무시되고 있는지, 그리고 추적이나 테스트를 통해 틀렸음이 입증되는지입니다.

Codified Context 논문은 약간 다른 응용 분야로 동일한 아이디어를 설명합니다. 이 논문에서 저자는 세 가지 계층의 컨텍스트 아키텍처(핫 메모리 구성, 전문 에이전트, 콜드 메모리 지식 기반)를 가진 108,000줄 분량의 C# 시스템을 만듭니다. 이 작업은 에이전트에 의해 읽히는 문서화가 에이전트가 정확한 결과를 얻기 위해 의존하는 '지지 기반 인프라(load-bearing infrastructure)'임을 명확하게 보여줍니다.

이는 소프트웨어 문서를 단순히 '느낌(vibes)'의 범주에서 벗어나 실질적으로 사용될 수 있는 영역으로 끌어올립니다. 이 경우 코딩 에이전트에 공급되는 위키 페이지는 설정 파일(config file)과 매우 유사하며, 다음과 같은 특성을 가져야 합니다. 소유자가 있어야 하고, 검토를 거쳐 변경되어야 하며, diff가 쉬워야 하고, 실패할 수 있는 메커니즘을 갖추어야 합니다.

지금까지 저는 이 문제 영역을 문서 품질 (document quality)의 관점에서 정의해 왔습니다. 문서는 검색 가능하고, 읽기 즐거우며, 버전이 관리되고, 작성자가 유지 관리하기 쉬워야 합니다. 하지만 이제 에이전트가 저장소 지식 (repo knowledge)을 바탕으로 작업을 수행하는 동안 이 문서들을 읽게 되면서, 우리는 문서가 포함된 소프트웨어 시스템에 대해 더 날카로운 질문을 던지게 되었습니다. 해당 시스템이 좋은 지식이 갖추어야 할 모든 속성, 즉 출처 (provenance), 범위 (scope), 최신성 (freshness), 그리고 해당 지식이 사용된 작업으로부터의 피드백을 갖춘 채 에이전트가 필요로 하는 컨텍스트 (context)를 제공할 수 있는가 하는 점입니다.

드리프트(Drift)는 실패 모드입니다

문서 드리프트 (Documentation drift)는 아주 오래전부터 존재해 왔습니다. 저장소 (repository)는 변경되지만, 코드베이스에 대한 문서는 제때 업데이트되지 않습니다. 새로운 엔지니어가 합류하여 특정 코드 조각이 왜 작동하지 않는지 파악하는 데 하루 이틀을 허비하고 나면, 그제야 팀은 다음 대규모 정리 작업 중에 관련 위키 페이지나 해당 기능에 대한 문서를 업데이트합니다.

단 하나의 오래된 아키텍처 노트 (architecture note)가 풀 리퀘스트 (pull request)에 영향을 미쳐 엔지니어가 실수로 잘못된 작업을 수행하게 만들 수 있습니다. 오래된 런북 (runbooks)은 장애 대응 어시스턴트 (incident assistant)가 잘못된 대시보드를 참조하게 만들 수 있습니다. 코딩 에이전트가 팀에서 더 이상 실행하지 않는, 심지어 디스크에 존재하지 않을 수도 있는 테스트 스위트를 실행하는 경우, 에이전트가 테스트를 "성공적으로" 수행하고 잘못된 구현 버그를 라이브 시스템에 푸시하는 결과를 초래할 수 있습니다. 구현 변경에 대한 코드 리뷰 (code review)는 오늘날 이러한 컨텍스트 버그 (context bugs)를 찾아낼 수 있어야 합니다.

이것이 바로 에이전트 대상 문서 (agent-facing docs)가 에이전트 평가 (agent evaluation)와 동일한 루프 안에 있어야 하는 이유입니다. 에이전트 평가는 출시 후에도 계속 실행되어야 한다는 점을 확립했다면, 에이전트 대상 문서 또한 동일한 지속적인 작업 루프 안에 있어야 한다는 점을 확립해야 합니다.

LangChain의 Pendo 사례 연구는 제품 분석 (product analytics), 사용자 행동 (user behavior), 세션 리플레이 (session replay), 코드 컨텍스트 (code context), 그리고 LangSmith 트레이스 (traces)를 코드 수정 (code fixes)과 연결하는 것에 대해 다룹니다. Pendo에 따르면, Novus는 PM이 검토한 평가 (evals)에서 90% 이상의 성공률을 달성했으며 며칠 만에 실제 사용 단계로 전환되었습니다. 이는 그들의 제품인 Novus와 LangSmith가 트레이스 (traces)를 코드와 연결함으로써 가능해졌습니다.

이는 또한 평가 과정에서 수집된 모든 증거가, 애초에 에이전트가 작업을 수행할 때 사용했던 문서를 업데이트해야 함을 의미합니다. 예를 들어, 엔지니어나 검토자가 동일한 사항을 반복해서 수정해야 한다면—예를 들어 에이전트가 특정 작업에 대해 잘못된 서브시스템 (subsystem)을 사용하는 코드를 반복해서 생성하거나, 무언가에 대해 잘못된 컨벤션 (convention)을 사용하는 경우—그 사항은 해당 리포지토리 (repo)의 에이전트 대상 문서에 포함되어야 합니다. 마찬가지로, 트레이스 (trace)가 일련의 도구 호출 (tool calls)을 거치는 과정에서 호출 체인 (call chain) 도중 오래된 API를 경유하게 된다면, 위키 (wiki)에는 해당 API에 대한 현재의 마이그레이션 경계 (migration boundary)가 기술되어 있어야 합니다.

문서 드리프트 (Documentation drift)는 에이전트의 행동을 포착하는 것과 동일한 전달 루프 (delivery loop)에 의해 포착되어야 합니다.

에이전트 대상의 리포지토리 문서 업데이트가 코드의 변경을 유발한다면, 즉 에이전트가 다른 것을 구현하게 함으로써 작동한다면, 해당 문서 업데이트는 풀 리퀘스트 (pull request) 형태여야 합니다.

더 빠른 코드는 오래된 컨텍스트의 비용을 더 높게 만든다

AI 지원 개발 (AI-assisted development)은 훨씬 더 많은 결과물을 만들어내고 있습니다. Mixpanel의 보고에 따르면, AI가 워크플로우에 도입된 후 동일한 엔지니어링 팀이 50% 더 많은 풀 리퀘스트 (pull requests)를 생성했습니다. 또한 이 글은 팀들이 MCP와 AI 코딩 에이전트 (AI coding agents)를 관측성 데이터 (observability data)에 연결하여, 에이전트가 트레이스 (traces)를 조사하고 실시간 변경 사항의 증거를 확인할 수 있도록 하는 방식에 대해서도 설명합니다.

코딩 에이전트에서 발생하는 문서 드리프트 (Documentation drift)는 빠르게 악화됩니다. 프로그래밍 에이전트 (programming agents)를 위해 모든 풀 리퀘스트 (pull request)마다 문서를 업데이트해야 하며, 모든 새로운 작업 항목 (work item)마다, 그리고 오래된 문서라는 잘못된 전제를 바탕으로 생성된 모든 변경 사항마다 문서를 업데이트해야 합니다. 리뷰어들은 시간을 낭비하게 됩니다. 재작업 루프 (rework loops)가 배가됩니다. CI (지속적 통합)는 잘못된 것을 증명하게 됩니다. 시스템 전체가 틀린 방향으로 가면서도 분주하게 움직이는 것처럼 보이기 시작합니다.

이 문제는 생성된 작업물에 대해 새로운 실행 엔진 (execution engine)이 추가된, 일종의 레거시 코드베이스 (legacy-codebase) 문제로 나타납니다. 대규모 시스템의 어려운 과제는 새로운 코드를 작성하는 것이 아니라, 로컬 지식 (local knowledge)을 이해하는 것입니다. 즉, 어디에 문제가 숨겨져 있는지, 어떤 추상화 (abstractions)가 단순히 형식화되어 무시해도 되는 것인지, 어떤 테스트가 실제로 실제 실패를 알리는지, 어떤 명명 규칙 (naming conventions)이 실제로 법처럼 중요하게 다뤄져야 하는지, 어떤 서비스 경계 (service boundaries)가 정치적인지를 파악하는 것입니다. 우리는 이미 팀의 관행으로서 레거시 코드베이스 지식 (legacy codebase knowledge)에 대해 작성한 적이 있으며 다양한 접근 방식을 논의했습니다. 이 글의 나머지 부분은 새로운 실행 엔진에 초점을 맞춥니다.

수년 동안 우리는 팀이 레거시 코드베이스 지식을 기록하고 팀 내 다른 구성원들과 공유할 것을 권장해 왔습니다. 하지만 우리가 인식하지 못했던 점은, 에이전트에 의해 작성된 코드 또한 기존 코드만큼 이해하기 어려울 수 있는 자체적인 로컬 컨텍스트 (local context)를 갖게 된다는 사실입니다. 그리고 이 코드 역시 실제로 수명 주기 (lifecycle)를 가지며, 소유권 (ownership)이 존재하고, 텔레메트리 (telemetry)로 모니터링할 수 있으며, 런타임 QA (runtime QA)를 통해 테스트될 수 있다는 점입니다.

에이전트의 코드 출력을 변경할 수 있는 문서는 코드로 작성되어야 합니다. 이는 문서를 코드와 동일하게 취급하는 유용한 운영 규칙이며, 따라서 코드와 동일한 정밀 검토(scrutiny)의 대상이 됩니다. 즉, 버전 관리 시스템(version control)에 기록되어야 하며 롤백(rollback)이 가능해야 합니다.

에이전트 지향 문서(agent-facing documentation)의 변경이 AI 보조 코딩 에이전트(AI-assisted coding agent)가 생성하는 코드의 출력에 영향을 미칠 수 있다면, 이 문서 또한 코드처럼 취급되어야 합니다. 즉, 저장소(repository)에 기록, 검토, 수정 및 추적되어야 하며, 수정 사항을 추적할 수 있어야 하고, 라이브 시스템에 배포되는 등의 과정을 거쳐야 합니다. 에이전트의 성능이 저하될 경우 이를 되돌릴 수 있어야 합니다.

에이전트 지향 문서의 소유권(Ownership)을 가져라

소유권(Ownership)은 지루한 부분입니다. 또한 이것이 제대로 작동할지를 결정하는 부분이기도 합니다.