agent-docs-architecture

Agent docs architecture

Agent-facing docs fail in one of two ways: everything is crammed into a single entry file that no one can navigate, or the guidance is scattered with no declared order, no source of truth, and no way for an agent to tell which doc answers its question. Both leave an agent guessing, and a guessing agent hallucinates.

This skill lays out the structure that prevents that. The goal is a layered tree where a thin entry doc routes to deeper guides, one rulebook is shared verbatim across tools, every doc's job is declared, and one doc is named as ground truth. The machine-readable manifest that binds these pieces together -- entry-doc path, rulebook path, source-path-to-domain routing, skill order -- lives in examples/setup.yaml. Treat that file as the contract and this skill as the rationale.

When to use

• Setting up agent docs (AGENTS.md, CLAUDE.md, a docs/ tree) in a repo that has none, or has an overgrown single file.
• Auditing an existing tree for the failure modes below: inlined entry doc, drifted cross-tool rules, no routing table, no declared source of truth.
• Adding a new domain guide and wanting it to match the house shape rather than being one more ad-hoc file.

When not to use

• The repo has no agents and no intent to add them; a plain README is enough.
• You are writing product or API docs for end users. This skill is about docs an agent reads to do work in the repo, not docs a customer reads.

---

1. Layer the tree; keep the entry doc thin

The entry doc (AGENTS.md or CLAUDE.md) is a switchboard, not an encyclopedia. It states the project in two sentences, names the hard rules, and links out to deeper docs. It does not inline setup steps, domain walkthroughs, or troubleshooting -- those live in leaf docs and go stale the moment they are duplicated at the top.

Target shape:

AGENTS.md                 <- thin entry: what this is, STOP-gate, routing table
CLAUDE.md                 <- byte-identical AI footer (see section 2)
docs/
  rules.md                <- the one shared rulebook
  setup.md                <- environment, toolchain, dev loop
  domains/
    <domain>.md           <- one guide per feature area (routing in setup.yaml)
  guides/
    <topic>.md            <- safety / domain guides (authored per section 8)
  ground-truth.md         <- the source of truth (see section 6)
examples/
  setup.yaml              <- machine-readable manifest binding all of the above