How to give coding agents persistent project context

What belongs in persistent agent context?

Keep persistent context layered. Repository instructions should describe how an agent operates: commands, conventions, safety limits and local workflow. Decision records should describe why a boundary exists and what alternatives were rejected. Retrieval should select the records that apply to the current task. Checks should test the subset of consequences that can be expressed objectively. Mixing all four into one giant instruction file makes ownership unclear and encourages stale copies.

The right context is therefore small and current, not comprehensive. A task about a payment boundary might need one data-residency decision, one API contract and one required check. Returning twenty loosely related documents creates the same failure mode as returning none: the important constraint is hard to distinguish from background material.

• Keep instructions operational and decisions authoritative.
• Prefer repository-native records over copied summaries.
• Return why a record matched so the agent can challenge a bad scope.
• Expire or supersede context instead of silently appending revisions.

How can teams test that context survived the task?

Test the observable workflow rather than asking a model whether it remembers. Record which decisions were retrieved, which citations appeared in the plan or pull request, which files they applied to and which checks ran. A small fixture repository can then verify that a known task returns the expected decision and that a forbidden change produces the expected evidence. This is a more useful regression test than measuring prompt length or assuming that a larger context window restores architectural memory.

When the context source changes, compare the decision IDs and evidence rather than only the generated prose. The goal is stable project authority, not identical wording.

How should context be served to several coding agents?

Use one source of authority and thin adapters for each agent. Codex, Claude Code, Cursor and an IDE extension may use different instruction filenames or MCP configuration, but they should receive the same decision IDs, scope explanations and citations. Generate a small route to the repository-native records instead of maintaining a separate policy document for every vendor. The adapter can translate the response shape; it should not rewrite the decision.

A useful context response is deliberately compact. Include the records that apply, the reason for the match, required and prohibited behaviour, checks to run, and a stable link to the full record. If an agent asks for more detail, let it retrieve the rationale on demand. This keeps prompt context focused and makes it possible to compare what different agents saw for the same task.

• One source record, many vendor-neutral routes.
• Explicit status and scope in every response.
• Stable citations that survive prompt-template changes.
• Evidence that the adapter did not silently broaden the decision.

What should a context contract measure?

Measure a context contract by the decisions an agent receives and the evidence it produces, not by the number of tokens injected. For a labelled task, record whether the expected decision was returned, whether an out-of-scope or superseded record was excluded, whether the agent cited the result and whether the required checks ran. A small fixture can cover common paths, capabilities, repositories and known conflicts.

Also measure change over time. When an instruction file, decision status or resolver rule changes, compare the returned IDs and reasons for a fixed task set. A larger answer is not necessarily better: irrelevant records can hide the one constraint that matters. Track context size, retrieval latency and citation completeness alongside authority precision so teams can see whether a change improved governance or only made prompts longer.

• Expected decision recall for labelled tasks.
• Exclusion of superseded and out-of-scope records.
• Citation completeness in plans and pull requests.
• Context size and latency alongside authority precision.

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.