Treat context as a working set
A useful context window contains the evidence most likely to change the agent's next decision. It does not need every fact the system can retrieve.
A coding agent can know React, Postgres, or OAuth perfectly and still put a route in the wrong package, bypass a tenant guard, or miss the test that defines the behavior. The missing knowledge is usually local: a convention encoded in a nearby file, a rule scoped to one directory, or a decision that only appeared in review.
Loading more can help, but it can also bury the constraint that matters among unrelated files and stale instructions. Research on multi-document question answering found that models did not use relevant information equally well at every position in a long input. That study was not about coding agents, so the practical lesson is narrower: capacity alone is not evidence that a model will find and apply the right repository fact. Start with a ranked, task-shaped working set and revise it as the work unfolds.
Record provenance before the first edit
A context receipt separates evidence the agent had before coding from rules reconstructed after a diff already exists.
A reviewer can always search the repository after the work is done. That may uncover the right rule, but it cannot show whether the rule was available when the agent chose a route, reused an abstraction, or crossed a sensitive boundary. Provenance makes that timing visible.
When Brief assembles a packet, it writes a local receipt for the task, repository and branch state, source paths, scope, and token estimate. Diff review can then look for matching pre-coding proof. The receipt does not show that the agent obeyed every source and it does not certify the resulting code. It establishes which evidence was available, when it was gathered, and whether review is judging the same scope.
Keep repository instructions narrow
Current evidence supports concise, maintained instructions more than automatically generated manuals.
A 2026 preprint evaluated repository context files on SWE-bench and on 138 tasks from 12 Python repositories. In those experiments, LLM-generated context files did not improve average resolution rates and increased inference cost by roughly 20 to 23 percent. Developer-written files produced a small, statistically uncertain average gain and still increased cost. Both kinds of file encouraged more exploration and testing.
That result is a useful boundary, not a verdict on every AGENTS.md or CLAUDE.md file. The study covered particular agents, models, repositories, and benchmark tasks. It does suggest a practical rule: keep the entry point short, include only requirements that can change the task, and retrieve path-specific detail when the work reaches it.
Use a five-layer working model
A practical packet can be organized into five layers: intent, repository structure, local evidence, live execution state, and team memory.
Intent says what should be observably different when the task is done. Repository structure gives the agent a map of packages, boundaries, and likely paths. Local evidence supplies the files, rules, owners, tests, and examples that constrain the change. Live state is what the agent learns from searches, build output, failing tests, and the diff it has created. Team memory carries forward approved lessons without turning every past comment into permanent law.
These layers should not receive equal weight. A copy change may need one component, its styles, a voice rule, and a focused test. An authentication change may need session helpers, tenant boundaries, migrations, threat assumptions, and integration checks. Risk changes the working set. A generic token target does not.
- Intent: the requested outcome, constraints, repository, branch, and risk
- Map: architecture, package boundaries, owners, and likely paths
- Evidence: applicable rules, nearby code, tests, docs, and reusable patterns
- Live state: tool results, errors, decisions, changed files, and remaining uncertainty
- Memory: approved review lessons, known failure modes, sources, and provenance
Put stable, dynamic, and executable context in different places
The best place for a rule depends on when it applies and whether software can enforce it more reliably than prose.
Stable context belongs in a short repository entry point: how to build, where architecture docs live, and what proof a change needs. Path-specific rules belong close to the code they govern and should appear only when a task crosses that boundary. Procedures and specialist knowledge can be loaded on demand. Deterministic requirements belong in types, tests, linters, hooks, or CI, where they can fail loudly instead of hoping the model remembers a sentence.
This is progressive disclosure. OpenAI describes its repository guidance as a map rather than a thousand-page manual. Cursor separates always-on rules from rules attached by path, relevance, or an explicit request. Brief treats these files as sources for a router: it scans the repository, identifies what applies to the task, and sends the agent a compact starting packet with paths and a token estimate.
Refresh context inside the agent loop
The initial packet should orient the agent, but searches, tool output, tests, and the evolving diff must update what it sees next.
Coding is not a one-shot retrieval problem. The first search suggests a file; that file names a helper; a test exposes an invariant; the build reveals a generated artifact. RepoCoder found that iterative retrieval and generation outperformed one-pass retrieval for repository-level code completion. That task is narrower than an autonomous pull request, but it gives a concrete reason to refresh retrieval as new code evidence appears.
The tools also shape what becomes context. SWE-agent's work on the agent-computer interface showed that file, shell, and test interfaces can materially affect software-engineering benchmark results. For a long run, preserve the goal, changed artifacts, decisions, failures, unresolved questions, and next action. Drop repetitive logs and superseded hypotheses.
Watch the working set change across one route task
For a sensitive change, each new fact should alter either the implementation path or the proof required before handoff.
Suppose the request is “Add an endpoint that renames a workspace.” The first line defines an outcome, but it does not identify the permission boundary, mutation pattern, or proof. The pre-edit packet adds only the sources that can settle those decisions. Tool output can then reveal a new dependency and trigger one bounded refresh.
The table is illustrative: the names describe a common route pattern rather than files in a particular customer repository. Its useful feature is the audit trail. A reviewer can see which fact arrived at each state and which decision it changed.
| State | Context available | Decision and proof |
|---|---|---|
| 1 · Request | Rename a workspace through a new endpoint; repository and branch are known. | Define the observable response and keep UI changes out of scope. |
| 2 · Before editing | Closest route, shared workspace permission guard, mutation helper, audit convention, contract test, and source paths. | Reuse the guard and mutation boundary; record the packet receipt before code changes. |
| 3 · After test and diff | A failing audit assertion and a diff that reaches a shared package make one package rule newly relevant. | Fetch that rule, update the audit path, rerun focused checks, and hand off the refreshed receipt with remaining risk. |
Run this 10-minute check before the first edit
The aim is to expose missing decisions early, not to produce a perfect dossier for a small task.
Use the list as a stoplight. If the task is low risk and every answer is obvious, start. If a security, data, deployment, or ownership boundary is unclear, gather that evidence before choosing an implementation.
- Write the observable outcome and one explicit exclusion.
- Confirm the repository, branch, and whether existing local changes affect the task.
- Find the closest implementation worth reusing or explain why it does not fit.
- Load only the repository and path-scoped rules that can change this work.
- Name the test, runtime check, or browser proof that matches the requested behavior.
- Record source paths and a context receipt before editing.
- Refresh the packet when tool output or the diff crosses a new boundary.
- Hand off commands run, results, changed scope, and unresolved risk without filling gaps by inference.
Measure decisions and outcomes
A context system is useful when it helps an agent choose the right path earlier and produces a change that survives verification and review.
Token count is a cost metric, not a quality score. Better measures follow the work: Was an applicable rule present before the relevant edit? Did the agent reuse the intended abstraction? Did it run the right boundary test? How many corrective review comments followed? Was the generated code retained rather than rewritten?
Cursor reported that adding semantic search increased code retention by 0.3 percent across its experiment and 2.6 percent for repositories with at least 1,000 files. That is a vendor result for Cursor's own agent, retrieval stack, and product traffic, not a general benchmark. Its choice of metric is still useful: evaluate whether retrieved context changes the fate of the code, then pair the outcome with provenance so the input is inspectable too.
Common questions
Questions worth asking next
Is context engineering the same as prompt engineering?
No. Prompt engineering shapes an instruction. Context engineering selects and structures the evidence the model needs to act on that instruction.
Should I put my entire codebase in a long context window?
Usually no. Start with a repository map and the evidence most likely to affect the task, then let the agent retrieve more as it discovers dependencies. A larger window is capacity, not a reason to spend it indiscriminately.
Are AGENTS.md or repository rules enough?
They are a useful entry point, especially for stable commands and principles. They do not replace path-scoped evidence, live tool feedback, executable checks, or approved lessons from prior work.
Does Brief upload the repository to build context?
Not in the default local-only mode. The local scanner builds the packet on the developer's machine. Optional derived sync is a separate, explicit setting.