AI-readable Design Principles
Structure, density, declarative writing, navigability, and executable completion criteria.
Key takeaways
- AI-readable docs are designed so agents can locate context, understand the contract, and know how to verify completion, not just written as shorter prose.
- Five principles drive the design: structured format, information density, declarative rules, navigable structure, and executability.
- Maximize information value (project-specific insight per consumed token) by omitting generic background like "what REST is" and keeping only this project's endpoints and constraints.
- Write declarative rules and give every change procedure an explicit "Done when" list so the agent knows what completion means.
- Keep
AGENTS.mdstartup instructions concise and move long procedures to Skills or MCP Resources loaded only when needed.
AI-readable documentation is not just shorter prose. It is documentation designed so agents can locate the right context, understand the contract, and know how to verify completion.
Principle 1: Structured Format
Agents handle structured text better than free-form prose. Use frontmatter, headings, tables, code blocks, stable IDs, and explicit links.
---
title: User Authentication API
description: JWT-based authentication and authorization
version: v2.3
status: stable
owner: auth-team
last-reviewed: 2026-05-24
---Why Frontmatter
Frontmatter lets search, RAG, docs tooling, and agents judge relevance before reading the entire body.
Principle 2: Information Density
information value = project-specific insight / consumed tokens| Omit when possible | Keep |
|---|---|
| What REST is | This project's endpoints and constraints |
| Git basics | This project's branching and commit rules |
| Docker concepts | This project's runtime settings |
| TypeScript basics | This project's type conventions |
Principle 3: Declarative Rules
Agents follow precise rules better than vague taste statements.
## Commit Convention
- Format: `<type>: <description>`
- Allowed types: feat, fix, docs, refactor, test, chore
- Description: lowercase start, no period, 50 characters or lessPrinciple 4: Navigable Structure
Agents jump through headings and file paths. Make titles unique and task-oriented.
| Anti-pattern | Problem | Better |
|---|---|---|
| Long prose | Wastes context | Tables, lists, code blocks |
| "As above" | Ambiguous in retrieved chunks | Explicit references |
| Giant single page | Poor retrieval | Split by topic |
| Screenshot-only docs | Text may be missed | Text plus image |
| Duplicated facts | Drift | Single source of truth |
| No date/version | Freshness unclear | updated, review_after, version |
Principle 5: Executability
Good agent documentation tells the agent what done means.
## Change Procedure
1. Update `src/api/orders.ts`.
2. Update `openapi/orders.yaml`.
3. Run:
\`\`\`bash
pnpm test orders
pnpm openapi:check
\`\`\`
Done when:
- tests pass
- OpenAPI diff has no breaking change
- `docs/api/orders.md` reflects the changeFormat Guidance
llms.txt
Use llms.txt as a Markdown index proposal, not as a crawler or SEO guarantee.
# Project Name
> One-line project summary
## Docs
- [API Reference](/docs/api.md): API contract
- [Runbooks](/docs/runbooks/index.md): operational proceduresAGENTS.md and CLAUDE.md
Keep startup instructions concise. Put long procedures in Skills or runbooks.
AGENTS.md -> short rules loaded at task start
Skill -> procedure loaded when needed
MCP Resource -> external context fetched when neededChecklist
| Item | Check |
|---|---|
| Frontmatter exists | [ ] |
| Generic background is omitted | [ ] |
| Rules are declarative | [ ] |
| Headings are specific and navigable | [ ] |
| Commands and completion criteria exist | [ ] |
| Long references are split into Skills or MCP Resources | [ ] |