검증 리포트
에이전틱 시대의 문서화 혁신 핸드북의 출처·링크·정합성 검증 결과
검증 기준일
2026년 5월 24일 기준으로 주요 외부 참고 문서와 내부 정합성을 재검토했습니다.
검증 방법론
- 공식/원문 문서를 우선 확인
- 2026년 기준 도구별 로딩 방식, API 스펙, MCP 보안 용어를 재검토
llms.txt를 공식 보장 표준처럼 표현하지 않도록 문구 조정- 신규 챕터 추가 후
meta.json, 목차, 책 registry 정합성 확인 - 빌드/타입체크/책 registry 검증 명령 실행
확인한 주요 출처
| 주제 | 출처 | 반영 내용 |
|---|---|---|
Codex AGENTS.md | OpenAI Codex: Custom instructions with AGENTS.md | 전역/프로젝트 scope, AGENTS.override.md, fallback filenames, 32 KiB 기본 제한 |
| Codex Skills | OpenAI Codex: Skills | metadata-first discovery, SKILL.md, scripts/references/assets, repo/global skills |
| Codex Plugins | OpenAI Codex: Build plugins | plugin manifest, skills/MCP/apps/hooks 묶음, marketplace 배포 |
| Claude Code memory | Claude Code: How Claude remembers your project | CLAUDE.md, CLAUDE.local.md, @import, .claude/rules/, path-scoped rules |
| Claude Code Skills | Claude Code: Skills | Skill body lazy load, supporting files, skill precedence와 공유 방식 |
| MCP | Model Context Protocol: Understanding MCP servers | Tools, Resources, Prompts의 역할 구분 |
| MCP schema | Model Context Protocol Schema Reference | ToolAnnotations가 힌트이며 보안 경계가 아니라는 점, input/output schema |
| MCP security | MCP Security Best Practices | 명시 동의, scope minimization, MCP 서버 보안 고려사항 |
| OpenAPI | OpenAPI Specification v3.2.0 | 3.2.0 최신 published version, HTTP API 계약, JSON Schema, version history |
| OpenAPI 3.2 release | OpenAPI Initiative: Announcing OpenAPI v3.2 | streaming media types, query, tag 구조, OAuth metadata |
| LLM security | OWASP Top 10 for LLM Applications | prompt injection, supply chain, excessive agency, vector/embedding weakness 기준 |
| AGENTS.md 형식 | AGENTS.md | 에이전트용 README 개념과 공통 파일명 흐름 |
| llms.txt | The /llms.txt file | /llms.txt가 제안임을 명확히 하고 Markdown 색인 용도로 제한 |
검증 결과 요약
| 항목 | 결과 |
|---|---|
| 챕터 제목/설명 일관성 | 신규 agent-surfaces, agent-security, templates 챕터를 목차와 meta.json에 반영 |
| 용어 통일 | "AI-readable"에서 "agent-operable" 관점으로 확장 |
| 도구별 최신성 | Codex/Claude Code 로딩 방식, Skills, Plugins, MCP 기준 반영 |
| API 최신성 | OpenAPI 3.2.0, streaming, query, OAuth metadata, tool schema 연결 반영 |
| 보안 최신성 | MCP annotation의 한계, scope minimization, OWASP LLM 위험 범주 반영 |
llms.txt 표현 | 공식 보장 표준·SEO 보장처럼 오해될 표현 제거 |
| 유지보수 전략 | 지침 드리프트, Skill/Plugin/MCP freshness, RAG freshness, smoke test 추가 |
| 외부 링크 | 주요 참고 출처 링크 수동 확인 |
로컬 검증
| 명령 | 결과 |
|---|---|
pnpm --filter handbook run check:books-registry | 통과 |
pnpm --filter handbook run typecheck | 통과 |
pnpm --filter handbook run build | 통과, 정적 페이지 1044개 생성 |
남은 한계
도구 동작은 계속 변한다
Codex, Claude Code, OpenAPI, MCP, llms.txt 생태계는 빠르게 변합니다.
특히 Skills/Plugins, MCP 보안·권한 모델, OpenAPI 3.2 tooling 지원 범위는 릴리스에 따라 바뀔 수 있으므로 분기별 재검토가 필요합니다.
다음 검증 주기
- 2026년 8월: Codex/Claude Code Skills, Plugins, MCP, OpenAPI 3.2 tooling 지원 재확인
- 도구 메이저 릴리스 발생 시:
project-rules,agent-surfaces,agent-security,api-docs,maintenance우선 재검토 llms.txt관련 주요 제공자 채택/거부 입장 변화 시:readme-onboarding문구 재검토