Nobody Reads My Docs Anymore—Not Even the AI Agents

개요

AI 코딩 에이전트가 개발자 문서에 대한 접근 방식이 변화함에 따라, 문서 작성의 가치는 에이전트가 코드로부터 직접 얻을 수 없는 "잔여물(residue)"에 집중해야 함을 강조합니다.

주요 내용

* AI 에이전트의 문서 소비 변화: 개발자는 라이브러리 URL을 복사하여 AI 에이전트에 붙여넣고 작업을 지시하는 방식이 일반화되고 있으며, 직접 문서를 읽는 경우는 드뭅니다.
* AI 에이전트 대상 문서 실험 결과: AI 코딩 에이전트를 대상으로 작성한 상세한 에이전트 전용 매뉴얼은 실제로 거의 읽히지 않았으며, 오히려 강제로 읽게 했을 때 성능이 저하되었습니다.
* "잔여물"의 중요성: 에이전트의 문서 가치는 해당 작업에 필요한 정보에서 에이전트가 코드, API 이름, 사전 학습 내용으로부터 이미 파악 가능한 정보를 뺀 "잔여물"로 정의됩니다.
* 가독성과 검증 가능성: 문서가 코드와 일치하는지 여부가 중요하며, 검증 가능한 정보(함수 서명, 매크로, 플래그)의 불일치는 에이전트가 코드를 통해 수정할 수 있지만, 검증 불가능한 정보(단위, 기본값, 순서)의 불일치는 치명적인 오류를 유발합니다.
* 에이전트 친화적인 코드베이스 원칙:
* 가독성 표면의 진실성 유지: 문서와 코드 간의 불일치, 특히 검증 불가능한 규칙의 불일치를 최소화합니다.
* 핵심 정보는 검증된 경로에 배치: 에이전트가 파일을 열 때 참조할 가능성이 높은 곳(예: 예제 테스트, 특정 명칭의 파일)에 중요한 정보를 배치합니다.
* API 설계로 오류 표면 축소: 개발자가 실수할 여지를 줄이는 API 설계를 통해 문서화의 필요성을 줄입니다.
* 함정(Warts) 명시: API의 잠재적 함정을 명확하게 문서화하고 규칙을 제시합니다.
* 복사-붙여넣기 가능한 레시피 제공: 일반적인 사용 패턴에 대한 정확한 템플릿을 제공합니다.
* 선택 표면(Selection Surface) 제공: 도구의 용도와 범위를 명확히 하여 에이전트가 도구를 선택하도록 돕습니다.
* 에이전트 기여 가이드라인 (AGENTS.txt): 에이전트가 코드를 확장할 때 따라야 할 아키텍처적 불변성을 명시합니다.
* 클린 에이전트 평가로 증명: 새로운 에이전트를 사용하여 실제 빌드 작업을 수행하고, 정확성과 비용을 측정하여 문서화의 효과를 검증합니다.
* "agent-ready" 도구: 코드베이스 감사, 문서 템플릿 생성, 클린 에이전트 평가 기능을 제공하는 Claude Code 플러그인입니다.

시사점

AI 에이전트 시대의 문서 작성 전략은 에이전트가 코드에서 직접 얻을 수 없는 고유한 정보, 즉 "잔여물"에 집중하고, API 설계를 통해 오류 가능성을 줄이며, 에이전트가 정보를 쉽게 찾고 활용할 수 있도록 구조화하는 방향으로 전환되어야 합니다.