A coding agent, like Claude Code or Codex, can read every file in a repository and still miss two things the code never states outright:
- a rule the code keeps true but never says, like an order that cannot change once it is filled;
- the other systems that depend on this one.
Miss either, and the agent writes a change that compiles, passes a quick test, and is wrong anyway. This page requires a repository to write both down. The rest of the context an agent needs before it edits already has a home, listed at the end.
Both requirements are satisfied inside the AGENTS.md sections that Agent instructions already mandates. This page sets the bar for what goes in two of them. It does not add a file.
Surface the invariants an agent must not break
An invariant is a rule the code keeps true that the code alone does not make obvious. For example:
- an order cannot change once it is filled;
- money is held in integer minor units rather than a float;
- a position and its account always move in the same transaction.
A compiler catches a type error. Nothing catches an agent that treats a filled order as editable.
Every covered repository states the invariants an agent must not break. They belong in the Architecture and boundaries and Known traps sections of AGENTS.md. Write the rule, then the reason, so the agent can tell a real constraint from a style preference. For the generated domain model the rule is already fixed: never edit a file marked DO NOT CHANGE: THIS FILE WAS GENERATED. See Architecture.
A repository should also spell out the house terms whose meaning an agent cannot guess, where guessing wrong changes behavior. “Fill”, “leg”, and “margin” carry a specific meaning in trading code. Keep this to the terms that carry risk. A full glossary rots faster than anyone maintains it.
Make published contracts and their consumers discoverable
A published contract is any interface another system depends on:
- a Protobuf or gRPC service;
- a Pub/Sub event;
- an OpenAPI endpoint;
- a shared schema.
An agent that changes one without knowing who reads it ships a silent break.
Every covered repository makes two things discoverable:
- the contracts it publishes;
- the systems that consume them.
Both belong in the Architecture and boundaries section of AGENTS.md, stated directly or through a pointer to the list. Architecture owns the contract format and the backward-compatibility rules, and Buf enforces them in CI. Design docs, RFCs and ADRs sets when a contract change needs a design document or an RFC. Code ownership names who reviews a contract path.
Naming the affected consumers in the pull request is a change-time step, not a static one. It belongs to AI change workflow.
What this page does not own
The rest of the context an agent needs is already required elsewhere. This page points to it rather than restating it.
- Repository map, setup, commands, owner declaration, and the marking of generated, vendored, migration, restricted, and prohibited paths are required
AGENTS.mdsections. See Agent instructions. - Who reviews a given path: Code ownership.
- Layering, contract formats, and backward compatibility: Architecture.
- When a change needs a design document, RFC, or ADR: Design docs, RFCs and ADRs.
Enforcement and currency follow Agent instructions. The same shared action checks these sections exist, and the owning team keeps them accurate at least quarterly.
References
- Agent instructions, the
AGENTS.mdstructure these two requirements build on. - Architecture, the contract formats, backward-compatibility rules, and the generated-model edit ban.
- Design docs, RFCs and ADRs, the trigger for when a contract change needs a written decision.
- Code ownership, the reviewer for a contract or high-risk path.