에이전틱 시대의 문서화 혁신
AI 에이전트가 읽고 실행할 수 있는 문서 체계를 만드는 실전 가이드입니다. AGENTS.md·CLAUDE.md 지침, 스킬, MCP, API 문서, 지식기반, 보안과 팀 거버넌스까지 다룹니다.
최근 수정된 챕터
AI 에이전트가 코드베이스의 과거 설계 결정, 검토한 대안, 트레이드오프를 이해하도록 ADR을 구조화하고 유지하는 실무 방법과 팀 운영 규칙을 정리합니다.
Prompt injection, MCP tool poisoning, Plugin 공급망, excessive agency를 줄이는 문서 보안 기준
문서 내용을 성격에 따라 규칙 파일, Skill, Plugin, MCP로 나누는 방법입니다. 반복 절차는 Skill, 팀 배포 단위는 Plugin, 외부 컨텍스트는 MCP Resource·Prompt·Tool로 분리합니다.
AI가 읽는 데 그치지 않고 실행까지 할 수 있는 문서를 쓰는 5가지 원칙입니다. frontmatter 메타데이터, 핵심 우선 밀도, 선언적 서술, 표와 목록, 완료 조건과 실패 시 조치를 다룹니다.
AI가 초안을 쓰고 검증은 코드로 고정하는 문서 운영 루프입니다. 소스 스캔, 문서 설계, AI 초안, 결정적 검증, 에이전트 smoke test, 소유자 리뷰, 발행·모니터링 순서로 진행합니다.
AI 에이전트가 코드와 문서를 읽고 쓰는 시대입니다. 이 핸드북은 사람이 읽는 문서를 넘어, AI 에이전트가 지침을 읽고 반복 작업을 실행하며 외부 컨텍스트를 가져와 검증까지 해내는 문서 체계를 다룹니다.
대상 독자
개발자, PM, 테크니컬 라이터 등 AI 시대에 문서를 쓰는 모든 사람. 기본지식은 AI에게 물어보면 되는 시대, 에이전트가 바로 사용할 수 있는 맥락을 어떻게 설계할지 다룹니다.
관련 읽기
문서가 하네스 안에서 어떤 역할을 맡는지까지 보려면
하네스 엔지니어링을 함께 읽길 권합니다.
핵심 전제
- 기본지식은 AI에게 물어보면 된다 — 문서에 모든 것을 담을 필요가 없다
- AI가 실행 가능한 문서가 필요하다 — 구조화·선언적·파싱 가능한 포맷
- 사람과 AI가 협업하여 문서를 만든다 — 설계→생성→검증→유지의 새 프로세스
- 문서 표면이 늘어났다 —
AGENTS.md,CLAUDE.md, Skills, Plugins, MCP, OpenAPI,llms.txt가 서로 다른 역할을 맡는다 - 보안 경계가 필요하다 — 외부 문서, Tool, Plugin, RAG 색인을 모두 같은 신뢰도로 취급하면 안 된다
- 문서화 ROI가 커진다 — AI가 매 작업에서 읽고 재사용하면 한 번 쓴 문서의 영향 범위가 넓어진다
핸드북 구조
목차
왜 문서화가 변해야 하는가
사람→사람에서 AI↔사람으로, 문서화 패러다임의 전환
AI-readable 문서 설계 원칙
구조화된 포맷, 핵심 우선 밀도, 선언적 서술
AI와 협업하는 문서 작성 프로세스
소스 스캔→초안→검증→smoke test의 문서 운영 루프
프로젝트 규칙 문서
AGENTS.md, CLAUDE.md, path-scoped rules 작성법
문서에서 스킬·플러그인·MCP로
반복 절차, 배포 단위, 외부 컨텍스트를 분리하는 방법
에이전트 문서 보안
Prompt injection, Tool poisoning, 권한 경계 설계
API 문서 & 스펙
OpenAPI 3.2, tool schema, MCP Resource 연결
README & 온보딩 문서
README, llms.txt, 문서 색인의 역할 분리
아키텍처 결정 기록 (ADR)
AI가 코드베이스를 이해하는 핵심 열쇠
런북 & 운영 문서
진단·승인·조치를 분리한 에이전트 운용형 런북
사용자 가이드 & 튜토리얼
AI가 사용자 질문에 답변할 때 참조하는 구조
지식기반 (KB) & 내부 위키
RAG, MCP Resource, freshness, citation 설계
문서 유지보수 전략
코드-문서 동기화, 지침 드리프트, 에이전트 검증 루프