Give coding agents persistent project context in layers: concise repository instructions for universal working rules, versioned decision records for durable rationale, deterministic retrieval for task-specific discovery, and CI checks for constraints that can be enforced objectively.
Persistent context is not one file
Codex supports AGENTS.md, Claude Code supports CLAUDE.md, and GitHub Copilot supports repository custom instructions. These files are effective entry points because the relevant agent loads them automatically. They are not a complete project memory system.
If every architecture choice, product rule and rejected alternative is placed in the global instruction file, the file becomes difficult to review and every task pays the context cost. More importantly, instruction prose is guidance; it does not prove that the code complies.
Use four layers
Separate information by how broadly it applies and how strongly it must be controlled. Each layer can then evolve without overloading the others.
- Entry instructions: build commands, repository map, universal conventions and the route to deeper records.
- Decision records: context, rationale, alternatives, consequences, status and relationships.
- Retrieval: a read-only query that finds the relevant accepted record and returns a citation.
- Enforcement: tests or policy checks for constraints with objective evidence.
Make retrieval task-shaped
An agent should not load the entire decision log before every task. It should be able to ask the repository a domain question, inspect the returned record and follow related decisions when necessary. Stable IDs make the result citable in a plan or pull request.
Deterministic retrieval is useful when reproducibility matters: the same query against the same repository state returns the same ranked records instead of depending on an embedding refresh or another model call.
Keep authority human-reviewed
Agent-written memory is useful for local discoveries, but it should not silently become team policy. Promote important findings into reviewed records. When a decision changes, supersede it explicitly and update or retire the corresponding check.
# AGENTS.md
Before changing product behaviour, query the repository decision record.
Cite any governing decision in the implementation plan.