Skip to main content
reopt Handbook
reopt Handbook
Agentic Documentation

Paradigm Shift

Why Documentation Must ChangeAI-readable Design PrinciplesAI-assisted Writing Process

Practice by Document Type

Project Rule DocumentsFrom Docs to Skills, Plugins, and MCPAgent Documentation SecurityAPI Docs and SpecsREADME and OnboardingArchitecture Decision RecordsRunbooks and OperationsUser Guides and TutorialsKnowledge Bases and Internal Wikis

Operations

Maintenance StrategyTeam Documentation Culture

Appendix

TemplatesVerification ReportUpdates
Handbook›에이전틱 시대의 문서화 혁신›README and Onboarding
한국어English

README and Onboarding

Split README, llms.txt, agent instructions, and detailed docs by audience.

Key takeaways

  • Keep README as the human entry point and move agent rules, machine indexes, and deep references to their own surfaces.
  • Each surface has a distinct reader: README.md for humans, AGENTS.md for coding agents, CLAUDE.md for Claude Code, llms.txt for LLMs and tools, and docs/** for both.
  • llms.txt is a proposal to place a Markdown index at /llms.txt; treat it as a clear index you control, not as a guarantee of search ranking, crawler behavior, or model-provider adoption.
  • Distinguish related files by job: llms.txt/llms-full.txt for the index, sitemap.xml for URL discovery, robots.txt for crawl policy, and the internal RAG index for actual retrieval.
  • Validate that every llms.txt link resolves to a real file, ideally in CI or a scheduled job.

README still matters in the age of AI agents, but it should not carry every detail. Keep README as the human entry point and move agent rules, machine indexes, and deep references to their own surfaces.

Surface Roles

SurfaceReaderRole
README.mdhumansoverview, quick start, major links
AGENTS.mdcoding agentscommands, rules, validation, prohibitions
CLAUDE.mdClaude CodeClaude-specific memory and imports
llms.txtLLMs, tools, RAGMarkdown index for important docs
docs/**/*.mdhumans + agentsdetailed guides, ADRs, runbooks, APIs

Concise README

# Project Name

One-line description.

## Quick Start

\`\`\`bash
pnpm install
pnpm dev
\`\`\`

## Documentation

- [Architecture](docs/architecture.md)
- [API Reference](docs/api.md)
- [Contributing](CONTRIBUTING.md)

## Agent Instructions

- [AGENTS.md](AGENTS.md)
- [CLAUDE.md](CLAUDE.md)

Treat llms.txt as a Proposal and Convention

llms.txt is a proposal to put a Markdown index at /llms.txt so LLMs and tools can find important content without parsing a full HTML site.

Do Not Overclaim

llms.txt is useful, but it does not guarantee search ranking, crawler behavior, or model-provider adoption. Treat it as a clear index you control, not as an AI SEO magic file.

# Project Name
> One-line project summary

## Docs
- [Getting Started](/docs/setup.md): installation and initial setup
- [API Reference](/docs/api.md): public API contract
- [Runbooks](/docs/runbooks/index.md): operational procedures

## Agent Instructions
- [AGENTS.md](/AGENTS.md): shared agent instructions
- [CLAUDE.md](/CLAUDE.md): Claude Code instructions

Related Files

FileUse
/llms.txtshort Markdown index
/llms-full.txtoptional longer index
sitemap.xmlURL discovery for crawlers
robots.txtcrawl policy
internal RAG indexactual retrieval pipeline

Validation

awk -F'[][]|[()]' '/^- \[/{ print $4 }' llms.txt | while read -r path; do
  case "$path" in
    http://*|https://*) continue ;;
    /*) target=".$path" ;;
    *) target="$path" ;;
  esac

  if [ ! -e "$target" ]; then
    echo "missing: $path"
    exit 1
  fi
done

Checklist

ItemCheck
README stays focused on human onboarding[ ]
AGENTS.md is separate from README[ ]
CLAUDE.md imports or cleanly separates from AGENTS.md[ ]
llms.txt contains only real links[ ]
llms.txt is not marketed as SEO guarantee[ ]
links are checked in CI or a scheduled job[ ]

References

  • The /llms.txt file
  • AGENTS.md

Related docs

RAG and Retrieval-Augmented Generation

Vercel Enterprise AI Platform · Build retrieval pipelines with indexing, permission filtering, reranking, and evaluation.

Maintenance Strategy

Keep docs, instructions, Skills, Plugins, MCP Resources, and validation loops from drifting.

Updates

Change log for the Agentic Documentation handbook.

Verification Report

Harness Engineering · Link, consistency, source, and static validation report for the Harness Engineering handbook.

API Docs and Specs

Connect OpenAPI 3.2, tool schemas, MCP Resources, and contract tests.

Architecture Decision Records

Capture architectural decisions so agents understand why the codebase is shaped this way.

On this page

Surface RolesConcise READMETreat llms.txt as a Proposal and ConventionRelated FilesValidationChecklistReferences