Agentic Documentation
A practical guide to documentation that AI agents can read, execute, verify, and govern.
Recently Updated Chapters
Capture architectural decisions so agents understand why the codebase is shaped this way.
Reduce prompt injection, MCP tool poisoning, Plugin supply chain risk, and excessive agency.
Split rules, workflows, distribution units, and external context into the right agent surface.
Structure, density, declarative writing, navigability, and executable completion criteria.
Source scan, draft, deterministic validation, agent smoke test, owner review, and freshness monitoring.
AI agents now read repositories, write code, call tools, inspect APIs, and verify changes. Documentation therefore has to do more than explain a system to humans. It must also give agents usable instructions, trustworthy context, safe boundaries, and repeatable validation loops.
Audience
This handbook is for developers, PMs, technical writers, platform teams, and AgentOps teams that need documentation to work across humans and AI agents.
Related Reading
To see where documentation fits in a broader agent operating environment, read
Harness Engineering as a companion handbook.
Core Assumptions
- Generic knowledge can live in the model - keep documents focused on project-specific facts.
- Documents must be executable by agents - use structured, declarative, parseable formats.
- The documentation surface has expanded -
AGENTS.md,CLAUDE.md, Skills, Plugins, MCP, OpenAPI, andllms.txthave distinct roles. - Security boundaries matter - external docs, tools, plugins, and RAG indexes do not deserve the same trust.
- Documentation ROI compounds - one high-quality instruction file can influence every agent session.
Handbook Map
Contents
Why Documentation Must Change
From human-only documentation to human-agent operating context.
AI-readable Design Principles
Structure, density, declarative writing, and executable completion criteria.
AI-assisted Writing Process
Source scan, draft, deterministic checks, agent smoke tests, and owner review.
Project Rule Documents
Design AGENTS.md, CLAUDE.md, and path-scoped rules without drift.
From Docs to Skills, Plugins, and MCP
Split instructions, workflows, distribution units, and external context.
Agent Documentation Security
Reduce prompt injection, tool poisoning, supply chain, and excessive agency risks.
API Docs and Specs
Connect OpenAPI 3.2, tool schemas, MCP Resources, and contract tests.
README and Onboarding
Separate README, llms.txt, agent instructions, and detailed docs.
Architecture Decision Records
Capture decisions so agents understand why the codebase is shaped this way.
Runbooks and Operations
Separate diagnosis, recommendation, action, approval, and rollback.
User Guides and Tutorials
Help agents answer user-facing product questions with grounded instructions.
Knowledge Bases and Internal Wikis
Design KBs for RAG, MCP Resources, freshness, and citation-first answers.