왜 문서화가 변해야 하는가
문서의 소비자가 사람에서 코딩 에이전트·RAG·MCP 클라이언트로 확장된 시대에, 읽히는 문서에서 작동하는 agent-operable 문서로 전환해야 하는 이유와 새 평가 기준.
핵심 요약
- 문서의 소비자가 사람만이 아니라 Claude Code·Codex·Cursor·RAG·MCP 클라이언트로 확장되었습니다.
- 좋은 문서는 에이전트에게 지침·절차·컨텍스트·검증 네 가지를 주고, AI-readable을 넘어 agent-operable이어야 합니다.
- "기본 지식은 AI에게" 맡기되 내부 규칙·결정 이유·운영 예외·비즈니스 계약은 반드시 문서화해야 합니다.
- 긴 규칙 파일은 핵심 지침 준수율을 떨어뜨리므로 정보 가치 = 고유 인사이트 ÷ 소비 토큰으로 밀도를 높입니다.
- 잘 구조화된 규칙 하나는 모든 에이전트 세션에서 재사용되는 복리 효과를 냅니다(1회 작성, N회 활용).
문서화의 오래된 공식
지난 수십 년간 기술 문서화의 공식은 단순했습니다.
사람이 작성하고 → 문서에 담기고 → 사람이 읽는다.
Wiki, Confluence, Notion, GitBook처럼 도구는 바뀌었지만 패러다임은 크게 변하지 않았습니다. 문서의 독자는 사람이었고, 문서의 가치는 사람이 얼마나 빠르게 이해하느냐로 측정되었습니다.
2024년 이후 이 공식은 구조적으로 흔들렸습니다. 2026년 현재 문서의 소비자는 사람만이 아닙니다. Claude Code, Codex, Cursor, Copilot 계열 에이전트, 사내 RAG, MCP 클라이언트가 문서를 직접 읽고 작업 계획·코드 변경·검증 루프에 씁니다.
새로운 등식: 사람 ↔ 문서 ↔ 에이전트
문서는 더 이상 "읽히는 결과물"만이 아닙니다. 좋은 문서는 에이전트에게 다음 네 가지를 제공합니다.
| 역할 | 설명 | 대표 표면 |
|---|---|---|
| 지침 | 작업 방식, 금지사항, 검증 명령을 전달 | AGENTS.md, CLAUDE.md, .claude/rules/ |
| 절차 | 반복 워크플로우를 재사용 가능한 단위로 제공 | Skills, commands, runbooks |
| 컨텍스트 | API 스키마, ADR, KB, 정책 문서를 검색 가능하게 제공 | OpenAPI, Markdown, MCP Resources |
| 검증 | 변경 후 무엇을 확인해야 하는지 정의 | CI, smoke test, eval checklist |
핵심 전환
문서의 목표가 "사람이 이해한다"에서 "사람과 에이전트가 같은 기준으로 작업한다"로 확장되었습니다. 그래서 최신 문서화는 AI-readable을 넘어 agent-operable이어야 합니다.
"기본 지식은 AI에게" — 문서에 모든 걸 담을 필요 없다
전통적인 문서화는 자기 완결성을 추구했습니다. "이 문서만 읽으면 모든 걸 알 수 있어야 한다"는 원칙은 초보 독자에게는 도움이 되지만, 문서를 금세 비대하게 만듭니다.
예시: API 인증 문서
기존 방식 — 모든 배경 지식을 문서에 포함:
## API 인증
### JWT란?
JSON Web Token(JWT)은 RFC 7519에 정의된 개방형 표준으로...
### OAuth 2.0이란?
OAuth 2.0은 인가 프레임워크로...
### 우리 API의 인증
Bearer 토큰을 Authorization 헤더에 포함하세요.에이전틱 방식 — 프로젝트 고유 정보와 실행 가능한 계약만 남김:
## API 인증
Bearer 토큰을 `Authorization` 헤더에 포함한다.
- 토큰 발급: `POST /auth/token` (`client_credentials`)
- 만료: 1시간, 갱신 불가. 만료 시 재발급한다.
- Rate limit: 토큰당 100 req/min
- 실패 응답: `401 { "code": "TOKEN_EXPIRED" }`
검증:
- `pnpm test auth-token`
- `pnpm openapi:check`생략하면 안 되는 것
"기본 지식은 AI에게"가 프로젝트 고유 맥락까지 생략하라는 뜻은 아닙니다. AI가 알 수 없는 내부 규칙, 아키텍처 결정 이유, 운영 예외, 비즈니스 계약은 반드시 문서화해야 합니다.
AI가 문서를 소비하는 방식
AI 에이전트는 문서를 사람처럼 훑지 않습니다. 파일을 컨텍스트로 읽고, 구조를 기준으로 관련 내용을 찾고, 명령·경로·금지사항을 작업 계획에 반영합니다.
토큰 경제학
컨텍스트 윈도우가 커져도 무제한은 아닙니다. 장황한 문서는 다음 비용을 만듭니다.
- 매 세션 로딩되는 규칙 파일이 길수록 핵심 지침 준수율이 떨어진다
- 같은 설명이 여러 파일에 반복되면 충돌과 드리프트가 늘어난다
- 긴 참고문서는 Skills, MCP Resources, 별도 레퍼런스로 분리하지 않으면 매 작업 비용이 된다
파싱 특성
AI 에이전트는 다음 단서를 잘 활용합니다.
- 제목 계층:
#,##,###가 문서의 탐색 구조가 된다 - 코드 블록: 실행할 명령, 설정, JSON Schema를 명확히 구분한다
- 표: 비교, 의사결정, 위치 안내에 강하다
- 파일 경로: "어디를 봐야 하는가"를 직접 알려준다
- 검증 명령: 작업 완료 조건을 추측하지 않게 만든다
에이전트의 문서 접근 경로
AGENTS.md / CLAUDE.md -> 프로젝트 진입 지침
↓
path-scoped rules / nested docs -> 작업 영역별 세부 규칙
↓
Skills / runbooks -> 반복 절차 실행
↓
OpenAPI / ADR / KB / MCP -> 근거 컨텍스트 조회
↓
CI / smoke test / eval -> 변경 검증문서 표면의 확장
2026년의 에이전틱 문서화는 단일 README 문제가 아닙니다. 표면별 역할을 구분해야 합니다.
| 표면 | 용도 | 잘못 쓰는 방식 |
|---|---|---|
README.md | 사람이 프로젝트를 빠르게 이해하고 시작 | 모든 세부 규칙을 README에 누적 |
AGENTS.md | 여러 코딩 에이전트가 공유할 프로젝트 지침 | 도구별 세부 기능까지 모두 강제 |
CLAUDE.md | Claude Code가 세션 시작 시 읽는 기억/지침 | 긴 절차와 레퍼런스를 모두 포함 |
.claude/rules/ | 경로·파일 유형별 Claude Code 규칙 | 전역 규칙과 충돌하는 예외를 방치 |
| Skills | 반복 절차와 참고자료를 필요할 때 로드 | 변하지 않는 프로젝트 사실을 skill로 숨김 |
| Plugins | 팀·조직에 배포할 skills, MCP, 앱 통합 묶음 | 실험 중인 절차를 곧바로 전사 배포 |
| MCP Resources | 외부 문서·스키마·KB를 컨텍스트로 제공 | 신뢰 경계와 최신성 검증 없이 노출 |
llms.txt | 웹 문서 색인을 Markdown으로 제공하는 제안/관례 | 검색 순위나 크롤링 보장을 기대 |
문서화 ROI의 구조적 변화
전통적인 문서는 온보딩 때 몇 번 읽히고 잊히기 쉽습니다. 에이전틱 문서는 매 작업에서 재사용됩니다.
| 항목 | 전통적 문서화 | 에이전틱 문서화 |
|---|---|---|
| 작성 대상 | 사람 독자 | 사람 + 에이전트 |
| 사용 빈도 | 온보딩·장애 대응 때 간헐적 | 코드 변경·리뷰·검증 때 반복적 |
| 품질 기준 | 이해 가능성 | 이해 가능성 + 실행 가능성 + 검증 가능성 |
| 유지보수 방식 | 사람이 기억해서 수정 | CI, 에이전트 검토, 링크/스키마 검증과 결합 |
복리 효과
잘 구조화된 프로젝트 규칙 하나는 팀의 모든 에이전트 세션에서 반복적으로 참조됩니다. 문서 1회 작성 → 작업 N회 활용. 이것이 에이전틱 문서화의 복리 효과입니다.
새로운 원칙 요약
AI 에이전트 시대의 문서화는 세 가지 기준으로 평가해야 합니다.
1. 핵심 밀도
정보 가치 = 프로젝트 고유 인사이트 / 소비 토큰 수범용 개념 설명보다 프로젝트 고유 맥락, 예외, 결정 이유, 검증 명령을 남깁니다.
2. 구조화
- Markdown 제목 계층
- 언어 태그가 있는 코드 블록
- 비교 표와 위치 안내 표
- frontmatter와 명확한 파일명
- 실행 명령과 완료 조건
3. 작동 가능성
사람에게 보기 좋은 문서와 에이전트에게 작동하는 문서는 서로 다릅니다.
| 사람에게 좋은 것 | 에이전트에게 좋은 것 |
|---|---|
| 스크린샷, GIF | 텍스트 설명, 코드 블록 |
| 감성적 도입부 | 즉시 핵심 정보 |
| 암묵적 팀 관행 | 명시적 규칙과 금지사항 |
| 긴 배경 설명 | 결정 이유와 현재 계약 |
| PDF, Figma 링크 | Markdown, OpenAPI, MCP Resource |
균형이 중요하다
AI 가독성만 추구하면 사람이 읽기 어려운 문서가 됩니다. 목표는 사람과 AI 모두에게 잘 작동하는 문서입니다. 잘 구조화된 Markdown은 양쪽 모두에게 효과적입니다.
이 핸드북의 방향
이 핸드북은 네 가지 질문에 답합니다.
- 설계: AI가 잘 읽는 문서는 어떤 구조인가?
- 프로세스: AI와 함께 문서를 쓰는 워크플로우는 무엇인가?
- 표면:
AGENTS.md,CLAUDE.md, Skills, Plugins, MCP,llms.txt를 어떻게 나눌 것인가? - 운영: 문서와 코드, 지침과 실제 작업 사이의 드리프트를 어떻게 줄일 것인가?