Agent-friendly documentation

Docs that teach an AI about a project have the same shape as docs that onboard a teammate. The goal is not volume; it is a reliable entry point, clear ownership, and executable evidence.

1. AGENTS.md — the top-level entry point

# Example workspace

Several apps and services. Web, API, workers, and PostgreSQL.

## Service map
| Role | Path | Stack |
|---|---|---|
| web | apps/web | Next.js |
| console | apps/console | Next.js |
| api | services/api | Spring |
| worker | services/worker | Python |

## Documentation
- docs/RULES.md       — global rules
- docs/shared/*.md    — technical standards
- docs/agent/{role}/  — work instructions by role
- docs/service/{role}/ — product and operations context

The first screen should answer what is being built and where to find its contracts. Put the reading order and ownership before a large folder listing.

2. RULES.md — global rules

## §1. Package managers
Use pnpm for frontend packages and uv for Python.

## §2. Change boundaries
Do not change data or secrets outside the requested ownership boundary.

## §3. SQL = SSOT
Verify schema declarations and migrations together.

Number rules that both people and agents must follow. Service files should link to the global rules and record only their exceptions.

3. rules.md per role — only local constraints

# console — absolute rules

Follow ../../RULES.md for global policy.

## Data boundary
Administrative writes require authentication, an audit event, and an advisory lock.

## Public boundary
Never copy internal paths or production hosts into educational examples.

Rules should be executable decisions with failure evidence, not a second copy of the architecture document.

4. features/ — focused context

docs/agent/console/features/
├── content.md       — content list, editing, verification
├── users.md         — permission and audit behavior
└── README.md        — dependency matrix

For a search change, load the search feature and its data contract first. A feature doc should own its API, database, UI states, and verification command as one unit.

5. Skill and agent prompts — domain signposts

---
name: workspace-console
description: For console and content-contract work.
  Next.js · PostgreSQL · authenticated writes · accessibility checks.
  TRIGGER — console, content, audit log.
---

# Entry docs
1. docs/RULES.md
2. docs/agent/console/rules.md
3. docs/agent/console/features/{feature}.md

State the scope, reading order, and narrow verification command. This reduces both token use and accidental edits.

6. Good documentation traits

• Scannable — headings and short tables reveal structure
• Concrete — pair principles with safe placeholders
• Explicit links — validate relative and public routes automatically
• Current — update docs in the same change as the contract
• Focused — split by audience and ownership when a file grows
• Failure-aware — document error states and recovery beside the happy path

7. Bad documentation traits

• Copying whole files and creating drift
• Dumping every entity field until the important contract disappears
• Exposing real secrets, production hosts, or project names in teaching examples
• Explaining a changing UI only with screenshots

8. The docs folder contract

docs/
├── RULES.md                  — global rules
├── shared/*.md               — shared technical standards
├── agent/{role}/             — AI work instructions
│   ├── rules.md
│   └── features/
└── service/{role}/           — product and operations context
    ├── prd.md
    ├── api.md
    └── improvements.md

Reflect audience, owner, and update cadence in the path. Public learning content should use placeholders such as apps/web and services/api, never internal paths copied from a real repository.

9. Automated validation

# Example repository commands
pnpm content:check
pnpm links:check

Check links, UTF-8, frontmatter, translation pairs, proper-name leakage, and example secrets in CI. If a doc changes a runtime contract, run that service's tests too.

10. CHANGELOG — chronological evidence

# Changelog

## 2026-08-10 — public content generalized
- Replaced real service names and hosts with placeholders
- Renamed a search note to a role-based public slug

Each entry should include date, context, impact, verification evidence, and a rollback clue. Explain which users changed, not only which files changed.

Common traps

• Writing docs once and never updating them
• Putting everything in README until the entry point is unusable
• Letting rules and actual commands diverge
• Copying internal service names, hosts, and paths into learning content
• Overusing Mermaid where a mobile-friendly table would be clearer

Closing

Agent-friendly documentation is human-friendly documentation that reads quickly. Clear audience, boundaries, and failure criteria give people and AI the same evidence to work from.

Next

• philosophy/06-docs-for-agent-and-human
• agent-tooling/09-claude-md-pattern