Architecture context for AI coding agents: what to hand-write, what to generate

The failure is quiet. A context file says the ingest worker writes directly to the warehouse. That stopped being true when a queue was introduced last quarter, and nobody updated the file because nobody reads it. An agent asked to add retry logic then writes it in the wrong place, the change is plausible, the tests pass, and the review catches it only if the reviewer knows that part of the system.

Two properties make this worse than the human version. Agents do not accumulate suspicion across sessions, so the same wrong line misleads every session forever. And they produce code fast enough that a wrong premise generates several plausible artefacts before anyone reads any of them.

The practical consequence is that context files need the same freshness discipline as configuration, not the discipline of a README. Anything in them that a commit can invalidate needs either an owner or a generator.

Write down what the agent cannot infer from the code. Toolchain and commands, including the non-obvious ones. Invariants that are true but unenforced. Boundaries the compiler does not check. Naming conventions. The reason something odd is odd, so the agent does not tidy it away.

Delete what the agent can read for itself. A file listing, function signatures, the framework in use, the test runner if it is declared in the manifest. Initialisation commands that generate a draft context file tend to include a lot of this, and every line of it is a line that can go stale for no benefit.

Say what is out of bounds. Directories not to touch, generated files not to hand-edit, migrations not to rewrite. Negative instructions are cheap, stable, and prevent the most expensive category of mistake.

Keep the architecture section short and link out. Two or three sentences on the shape of the system, then a pointer to ARCHITECTURE.md and to the current diagram. A long architecture description inside a context file is the part most likely to be wrong and the part nobody diffs.

# AGENTS.md

## Commands
- `make dev` starts the stack. Do not run `docker compose up` directly.
- `make test-integration` needs `make dev` running first.

## Invariants the compiler does not enforce
- `pkg/domain` must not import `pkg/api` or any driver.
- The ingest queue is at-least-once. Every consumer must be idempotent.
- `events` is append only. Corrections are new rows, never updates.

## Do not touch
- `internal/gen/` is generated. Change the template, not the output.
- Existing migrations are immutable. Add a new one.

## Architecture
Three services and a warehouse. The current map lives in
ARCHITECTURE.md; the live diagram is regenerated from this repo daily.

Split the file by decay rate, exactly as you would an architecture document. Invariants, boundaries and conventions change a handful of times a year and are worth writing carefully by hand. The inventory, which services exist, what they depend on, which module owns what, changes constantly and should not be maintained in prose at all.

For the inventory half, connect the repository read only through repository sync on GitHub, GitLab or Azure DevOps, pinned to a branch or a tag. The diagram and an architecture doc are regenerated daily, so the map the agent is pointed at is a day old at worst rather than a quarter old.

Reference rather than copy. Pasting a generated inventory into the context file recreates the drift problem one level up, because the paste has no update mechanism. A link to the current architecture doc does not go stale.

A file is a snapshot the agent trusts. A tool call is a question it can ask at the moment it matters, which is strictly better for anything that changes. The MCP server exposes thirty-six tools to Claude Code, Cursor, ChatGPT and Claude Desktop: nine outcome-level ones and twenty-seven fine-grained canvas tools. Two of the nine cover the repository. repo_status answers which repository and which branch or tag a diagram tracks, when it last synced, the commit it reflects and whether daily sync is on; repo_refresh syncs it now.

The same server exposes the diagram itself. create_diagram, create_blank_diagram, get_diagram, edit_diagram, list_diagrams, export_diagram and get_design_guide are the rest of the nine, and the twenty-seven canvas tools cover the primitives underneath. An agent that has just changed the architecture can update the picture in the same session, which is the only workflow where the diagram and the change genuinely happen together.

The handshake and the listings are anonymous. initialize, ping, tools/list, prompts/list and resources/list answer without credentials, so an agent, or a directory crawler, can read the whole tool surface before an account exists. Only tools/call requires a key.

This is also the cleanest answer for teams where the agent is doing most of the writing. The documentation problem stops being remember to update the diagram and becomes the agent has a tool for it, which is a much easier thing to make habitual. See agents for the wider picture.

# No key: the handshake and the listings are public.
curl -s https://datadef.io/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# 36 tools come back: 9 outcome-level, 27 canvas primitives.
# tools/call is the one that needs a key.

• MCP server documentation
• Diagrams for AI agents
• Diagrams as context for coding agents
• ARCHITECTURE.md: the codebase map
• Repo to diagram: repository sync