Ludvík Prokopec ← ALL ARTICLES
NO. 01

Structuring Context for Agentic Development

Context is a budget for both agents and humans. Structure the docs so neither needs a /clear.

Agentic Development · AI Tooling · Documentation · Developer Experience

  • 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

text
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:

markdown
- [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.

markdown
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, not 0027-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.