AI 요약
코딩 에이전트가 개발 워크플로우의 중심이 되면서, 전통적인 소프트웨어 문서화 방식에 근본적인 변화가 요구되고 있습니다. 자연언어로 작성된 문서는 코드와 달리 기계적인 피드백 루프가 없어 쉽게 노후화(Rotting)되며, 이는 에이전트에게 잘못된 컨텍스트를 제공하여 조용한 실패를 유발합니다. 저자는 문서를 '유도 가능성', '검증 가능성', '불변성'에 따라 4가지(유도 가능, 검증 가능, 불변 기록, 환원 불능)로 분류하고, 기계가 직접 코드를 분석할 수 있는 부분은 과감히 생략할 것을 제안합니다. 결국 에이전트 시대의 문서는 코드나 테스트로 치환할 수 없는 의사결정의 맥락(Why)과 외부 제약 조건을 기록하는 방향으로 진화해야 하며, 이를 위해 CLAUDE.md와 같은 상시 주입형 컨텍스트를 전략적으로 관리하는 2층 구조의 문서화 전략이 필요합니다.
핵심 인사이트
- 에이전트 컨텍스트 최적화: Claude Code의
CLAUDE.md나 Codex의AGENTS.md는 세션 시작 시 자동 주입되므로, 컨텍스트 창 낭비를 막기 위해 약 30~60행 이내로 극히 짧게 유지해야 합니다. - 데이터 기반의 효율성 검증: ETH Zurich와 LogicStar.ai의 공동 연구 결과,
CLAUDE.md에 디렉토리 구조를 상세히 기술하는 것은 에이전트의 파일 발견 속도를 향상시키지 못하는 것으로 나타났습니다. - 문서의 4단계 분류 체계: 문서를 도출 가능(API 사양 등), 검증 가능(응답 시간 제약 등), 불변 기록(ADR), 환원 불능(결정의 이유) 지식으로 분류하여 관리 효율을 극대화해야 합니다.
- 기계적 피드백 루프 구축: '200ms 이내 응답'과 같은 검증 가능한 제약 사항은 문서가 아닌 테스트 코드나 Linter로 옮겨 실시간으로 피드백을 주어야 합니다.
주요 디테일
- 자연어 문서의 비대칭성: 코드는 컴파일러와 CI/CD를 통해 오류를 즉각 수정할 수 있지만, 문서는 구현과 괴리되어도 오류를 내뱉지 않아 에이전트의 행동을 조용히 악화시킵니다.
- ADR(Architecture Decision Records)의 중요성: 불변의 기록으로서 ADR은 특정 시점의 결정을 보존하며, 에이전트가
superseded(교체됨) 상태를 기계적으로 판단하여 최신 결정을 따를 수 있게 합니다. - 'Why not'의 기록: 과거에 왜 특정 설계를 채택하지 않았는지 기록하지 않으면, 에이전트가 개선을 시도하다 과거에 실패했던 설계로 회귀할 위험이 있습니다.
- 2계층 구조 전략: Layer 1(상시 주입용 파일)에는 금지 사항과 빌드 명령 등 핵심 가드레일을 두고, Layer 2(
docs/디렉토리)에는 상세한 환원 불능 지식을 분산 배치합니다.
향후 전망
- 문서화의 자동화 및 축소: 코드에서 직접 유도 가능한 정보(디렉토리 구조, API 사양)는 문서에서 사라지고, 에이전트가 실시간으로 코드를 스캔하여 파악하는 방식이 표준이 될 것입니다.
- 컨텍스트 엔지니어링의 부상: 개발자의 역할이 문서를 길게 쓰는 것에서, 에이전트에게 필요한 핵심 맥락만을 선별하여 컨텍스트 효율을 높이는 관리형 작업으로 전이될 것입니다.
출처:hatena