- Agent starts every session with an empty context.
- 2 failure modes: load everything, or load nothing.
- Load everything → the budget is gone before the first file is read.
- Load nothing → the agent invents your conventions.
- Fix: split the index from the content.
The Shape
AGENTS.md # always loaded — annotated pointers
GLOSSARY.md # domain vocabulary
docs/
coding-standards/
index.md # hub
typescript.md # leaves
react.md
testing.md
commits.md
adr/
index.md # hub
NNNN-<decision>.md # 1 decision per file
tooling/
index.md # hub
<dependency>.md # how to fetch its current docs
agents/
index.md # hub
<workflow>.md # a workflow the agent runs
apps/<app>/README.md # 1 app: what it is, how to run it
packages/<package>/README.md # 1 package: what it owns, what it exposes
scripts/<script>/README.md # 1 script: what it does
- 3 tiers: always loaded → hub → leaf.
- Tier 1 is read every run. Tier 2 and 3 are read when a pointer fires.
- Depth is the point. The agent pays only for the branch it walks.
Tier 1 — AGENTS.md
- Annotated pointers — link + hint + trigger, for everything loaded on demand.
- Content that must be loaded every time — the facts that are worthless arriving late.
A pointer has 3 parts:
- [docs/coding-standards/i18n.md](./docs/coding-standards/i18n.md) — ICU
catalogs, one namespace per kind of owner. Read it before adding a string.
-
Link — exact path, relative.
-
What — the hint. Enough keywords to decide relevance without opening it.
-
Trigger — when to open it.
Read it before adding a string. -
Pointer without a trigger is a bookmark. It gets followed when the agent already knows it needs it — which is exactly when it did not need the pointer.
-
Trigger turns the index into a dispatch table.
-
Good:
Read it before styling anything. -
Bad:
See also: theming.
Tier 2 — Hubs
A hub is index.md inside a folder whose leaves are too many for tier 1.
docs/coding-standards/index.md
# Coding standards
- [typescript.md](./typescript.md) — types naming, arrow functions naming, no
`export default`, constant naming, where enums live, pattern matching,
validation schemas
- [react.md](./react.md) — one component per file, hook files named after their
hook, props type naming
- [testing.md](./testing.md) — test names, what to test where, mocking at the
network boundary
Tier 3 — Leaves
Split by what the content is, not by topic:
- Coding standards — rules.
- ADRs — decisions, 1 per file, with the alternatives and why not.
- Glossary — vocabulary.
- Tooling — how to fetch current docs for a dependency.
ADRs
- 1 file, 1 decision, title is the decision as a sentence.
0027-the-url-is-the-filter-state.md, not0027-routing.md.
Each ADR records the thing code cannot: what was rejected.
- Code shows the choice. It does not show the 2 alternatives.
- Without that, an agent “improves” the code back into the rejected design.
Agent’s Memory
Most agents ship a private memory: a file they append facts to between sessions, without being asked.
- It is documentation without human reader.
- Nobody opens it. Nobody reviews it. Nobody diffs it. Nobody knows what is in it.
- Stale entry stays wrong forever — correcting it needs a reader, and there is none.
Advice: disable it.
docs/is the memory. For the agent and for the human, same files.