In this article
Last updated September 18, 2026
4 min read
The first response to a coding-agent mistake is often to add another instruction.
The context file grows. More conventions appear. Old exceptions remain. Architecture, product rules, commands, and
warnings sit together because all of them might matter one day.
The agent now has more information and can still miss the task.
What current research says
An ETH Zurich study evaluated AGENTS.md-style context files across coding-agent setups. In the evaluated benchmark,
the files did not improve task success and increased cost by roughly 20%. Agents explored and tested more.
This does not prove repository instructions are useless. It is one benchmark with specific agents and tasks.
It shows why the metric cannot be “the agent read more context.”
OpenAI’s harness-engineering account describes a different pattern: repository-local, versioned knowledge with
progressive disclosure. Agents start from a small stable entry point and learn where to find relevant plans,
architecture, and verification status.
Amazon’s CloudAPIBench research adds another warning. Targeted API documentation helped low-frequency API validity,
while poor retrieval could harm performance in other cases.
The common lesson is selection.
Context has four quality dimensions
Relevance
Does the information help this task, module, decision, or check?
Freshness
Does it describe the current code, dependency version, product rule, and operating environment?
Authority
Is it a reviewed source of truth, a generated hint, an old discussion, or a model summary?
Verifiability
Can the agent check the instruction against live files, commands, schemas, or an accountable owner?
A large context package can score poorly on all four.
Build a task context package
For a feature, start with:
- goal and approved specification;
- owning module and public boundaries;
- task-relevant rules and invariants;
- closest existing patterns;
- commands required for proof;
- affected documentation;
- known drift or conflicting sources;
- current workflow state.
Then give the agent paths to retrieve more when needed.
The package should not pretend to contain the whole repository. It should make the next useful source discoverable.
Treat retrieved context as a lead
Search and retrieval can surface the right file. They can also return a stale document, a close but wrong component, or
a snippet without its boundary.
Label retrieved slices as hints to verify.
For every material instruction, the workflow should know:
- where it came from;
- when it was last checked;
- which scope it applies to;
- what live source can confirm it;
- what to do when sources conflict.
This is especially important for AI-generated summaries. Compression saves tokens by dropping information. The summary
should point back to the underlying artifact.
Remove context as deliberately as you add it
Context maintenance needs deletion.
Retire obsolete rules. Merge duplicates. Split broad files by scope. Add review triggers to version-sensitive
instructions. Promote important prose rules into deterministic checks when a script can enforce them.
The goal is a smaller surface with stronger authority.
Measure context by outcome
Compare context strategies using:
- task success;
- correction turns;
- unsupported assumptions;
- files read;
- tokens sent;
- review findings;
- stale-source incidents;
- time to accepted change.
A context package that costs more can still be worthwhile if it reduces important mistakes. A package that causes more
exploration without better outcomes needs redesign.
paqad-ai’s context approach
paqad-ai’s current first-party documentation describes a lean resident rule manifest, task-focused context packages,
structured repository knowledge, and optional retrieval that remains a hint to verify against live files.
The product reports internal footprint measurements, but those should not be converted into a universal result.
The useful principle is independent of the number:
Load the right context, keep its source visible, and verify it against the repository.
More context is not knowledge.
Current, relevant, reviewable context is.
Install paqad-ai: https://github.com/Eliyce/paqad-ai/
Source notes
- ETH Zurich SRI, AGENTS.md study.
- OpenAI, Harness engineering, first-party internal account.
- Amazon Science, CloudAPIBench.
- Eliyce/paqad-ai, first-party product description.