An agent cannot recover a project rule that exists only in somebody’s head. It fills the gap with the most common pattern from its training data, which may be perfectly reasonable and wrong for your system.

Better context reduces that guesswork. More context does not always help. A repository dump can bury the one interface or decision that controls the task.

Treat context as evidence

Useful context answers five questions:

  1. What behavior should change?
  2. Where does that behavior live?
  3. Which rules must remain true?
  4. What existing example shows the local pattern?
  5. Which command proves the result?

Each answer should point to evidence when possible. A file path beats a description of a file. A failing test beats a paragraph about the bug. An accepted fixture beats “follow our usual format.”

Suppose an endpoint returns the wrong status. Give the route, service boundary, relevant test, failing command, and expected response. Do not paste every controller in the application.

Build a context stack

I separate context by how long it remains useful.

Repository context changes slowly: architecture boundaries, commands, naming rules, security constraints, and ownership. Keep it in versioned files near the code.

Task context is temporary: the current goal, observed failure, allowed scope, acceptance criteria, and stop condition. Put it in the prompt or issue.

Runtime evidence is produced during the work: logs, screenshots, test output, database state, and the final diff. Refresh it instead of relying on an old chat message.

This stack prevents two common failures. The chat stays small, and stable rules survive after the conversation disappears.

Put durable knowledge in the repo

A useful repository usually has:

  • one entry point that explains how to build and test;
  • local instructions for packages with different rules;
  • architecture decisions for constraints that are easy to “simplify” incorrectly;
  • examples close to the code that should copy their shape;
  • tests that encode important behavior.

Do not turn one instruction file into a manual for the whole company. Agents, like people, stop finding rules when the file becomes a pile.

Keep each rule close to the scope it governs. Delete stale instructions in the same change that makes them false.

Watch for poisoned context

Wrong context is often worse than missing context. An outdated command, obsolete API example, or old architecture note gives the agent false confidence.

When output looks inexplicably wrong, inspect the inputs before changing the prompt wording. Check which instruction files were loaded, whether the example is still canonical, and whether the failing output came from the current branch.

Start with a context brief

Before a repository task, I write this:

Goal:
Observed evidence:
Relevant files:
Rules and examples:
Allowed scope:
Verification:
Unknowns:

If I cannot fill a field, I either inspect the repository or mark the unknown. That is safer than letting the model silently choose an answer.

Context quality is an engineering property. Store durable facts, select the evidence for this task, and keep the proof current.