Effective context engineering for AI agents: what each one is genuinely good at

On this page#

• How we judged them
• The shortlist
• What we rejected and why
• The one nobody talks about
• Choosing by repo shape
• FAQ

How we judged them#

Effective context engineering for AI agents is not about feeding the model the most information. It is about supplying the smallest set of durable facts that lets an agent make correct changes without violating repository invariants. A useful approach must improve decisions, survive real maintenance, and fail visibly when its assumptions become stale.

An AI coding agent ultimately relies on a large language model: a model that generates responses from the instructions and context available during the current interaction. If a constraint is absent, ambiguous, or buried under irrelevant material, the model cannot reliably treat it as an invariant.

We judge context mechanisms against six criteria:

1. Authority: Can the agent distinguish mandatory rules from background information?
2. Scope: Can a rule apply to one directory or subsystem without contaminating unrelated work?
3. Discoverability: Will the agent receive the context before making a decision?
4. Freshness: Is someone clearly responsible for updating it when the repository changes?
5. Cost: How much irrelevant text must be loaded to recover one useful fact?
6. Recoverability: When the context causes a bad change, can an engineer identify and remove the offending instruction?

The last criterion is routinely ignored. Context is executable influence: it changes what the agent reads, assumes, and edits. Treating a context file as harmless documentation is a mistake.

The right acceptance test is therefore not “did the agent follow the prompt?” It is “could another engineer explain which repository facts authorized this change?” If the answer requires reconstructing a long chat, the context system has already failed.

For implementation-oriented examples beyond this comparison, PairFoundry’s tools are the practical next stop.

Photo by mali maeder on Pexels.

The shortlist#

The strongest options solve different context problems. Repository instructions preserve stable rules, scoped files constrain local work, task briefs describe temporary intent, and retrieval exposes reference material on demand. Combining them deliberately is better than forcing every fact into one enormous instruction file.

| Option | Best for whom | When not to use it | |---|---|---| | Root repository instructions | Teams with stable, repository-wide commands, architecture boundaries, and non-negotiable policies | When the rule belongs to one package, one task, or one developer’s preference | | Directory-scoped instructions | Monorepos and repositories whose subsystems use different conventions or validation paths | When engineers cannot tell which file owns a rule or how nested instructions interact | | Task brief | Engineers delegating a bounded change with explicit acceptance criteria and known non-goals | When the task is exploratory and the desired result is still being discovered | | Curated reference pack | Repositories where agents repeatedly need schemas, protocols, domain terminology, or operational constraints | When the pack merely duplicates files the agent can already locate reliably | | On-demand retrieval | Large repositories where loading all potentially relevant material would bury the working set | When retrieval can silently omit a mandatory invariant |

Root instructions should be short and authoritative. Put build commands, test gates, architectural prohibitions, and repository-wide definitions there. Do not turn the file into an onboarding handbook.

Scoped instructions are the best default for repositories with genuine internal boundaries. A frontend package and a migration subsystem rarely share the same safe-change rules. Local context preserves that distinction without making every task carry the whole repository.

A task brief is temporary context, not permanent policy. It should state the desired outcome, files or systems in scope, acceptance criteria, and forbidden changes. If a constraint should remain true after the task closes, promote it into repository-owned instructions instead of copying the old brief forever.

Official product guidance remains useful for understanding supported behavior; for example, the Claude Code documentation explains the tool’s documented mechanisms. But official guidance cannot identify your repository’s invariants. The vendor knows the agent interface; your team owns the meaning of a safe change.

PairFoundry’s three packs are useful when you want a prepared structure rather than another blank context file.

What we rejected and why#

We rejected approaches that hide authority, accumulate stale prose, or make failures impossible to trace. They may produce an impressive first response, but they do not form a maintainable control surface for a repository where correctness matters after the current chat ends.

One giant context file#

A single comprehensive file looks disciplined and usually becomes a dumping ground. Global rules, package details, task notes, style preferences, and obsolete workarounds acquire equal visual weight. The agent receives more text while the engineer loses a clear answer to “which rule applies here?”

Split context by lifespan and scope:

• Repository-wide invariants belong at the root.
• Subsystem rules belong near that subsystem.
• Temporary intent belongs in the task brief.
• Supporting detail belongs in references loaded only when needed.

The full documentation tree#

Documentation is not automatically good context. Loading everything transfers the repository’s contradictions, historical notes, and audience-specific explanations into the agent’s working set. More context can reduce precision because the agent must infer which statements are current and authoritative.

Documentation should remain navigable, but mandatory rules need explicit promotion. Engineers who need the underlying principles before adopting a structure can use PairFoundry’s free foundations track.

Chat history as project memory#

A long conversation is a poor source of durable truth. Decisions become mixed with abandoned ideas, corrections, and speculative branches. A later agent—or a teammate starting a fresh session—cannot safely distinguish an invariant from something that was merely considered.

When a chat produces a lasting decision, move that decision into a repository-owned artifact. Do not preserve the entire conversation and call it memory.

Automatically generated repository summaries#

Generated summaries are navigation aids, not authority. They can describe visible structure, but they cannot reliably decide which odd-looking boundary is intentional or which duplicated path exists for compatibility. Using generated prose as policy converts an inference into a rule.

Regeneration also creates a dangerous illusion of freshness. A newly generated summary can still encode the wrong interpretation of current code.

Photo by Lukas Blazek on Pexels.

The one nobody talks about#

The underestimated option is a context deletion review: regularly removing instructions that are redundant, unverifiable, or no longer authoritative. Teams discuss adding memory far more often than subtracting it, even though stale context is worse than missing context because it confidently points the agent in the wrong direction.

Review each durable instruction with four questions:

1. What concrete failure does this prevent?
2. Which repository evidence makes it true?
3. Who must update it when that evidence changes?
4. What is the smallest scope in which it remains valid?

Delete instructions that cannot answer those questions. Move narrow rules closer to their owning code. Replace duplicated explanations with one authoritative statement and a link.

This is also why context should be reviewable in ordinary code review. A rule that changes agent behavior deserves the same scrutiny as configuration. The broader context-engineering landscape is organized in PairFoundry’s landscape hub, but subtraction remains the practice most teams postpone.

A smaller context surface is not inherently better. A smaller authoritative surface is better because conflicts become visible and rollback becomes practical.

Choosing by repo shape#

Choose according to where invariants live, not according to which technique sounds most advanced. Repository shape determines the correct context topology: one coherent service needs a compact root; a monorepo needs scoped ownership; a legacy system needs explicit danger boundaries; and a fast-moving codebase needs aggressive deletion.

• Single service with uniform conventions: Use concise root instructions plus task briefs. Add scoped files only when a real subsystem exception appears.
• Monorepo with independent packages: Use a small root for universal rules and scoped instructions for package-specific commands, ownership, and constraints.
• Legacy repository with fragile behavior: Prioritize forbidden changes, required validation, and compatibility boundaries. Do not ask a generated repository summary to infer them.
• Regulated or high-consequence system: Separate mandatory controls from explanatory references. Every instruction should have an identifiable owner and repository evidence.
• Rapidly changing product code: Keep durable context minimal. Use task briefs heavily and review permanent instructions whenever architecture changes.
• Documentation-heavy platform: Use retrieval for background material, but promote non-negotiable rules into explicit instructions that cannot disappear through retrieval failure.

The practical pattern is layered: a small global contract, narrow local contracts, a disposable task brief, and optional references. If two layers disagree, stop and resolve the ownership problem. Asking the agent to “use its best judgment” is not conflict resolution.

Photo by Digital Buggu on Pexels.

Related reading#

• AI coding tools: a short list, with the reasons we rejected the rest
• AI powered coding agents — ranked by how little you have to babysit them

FAQ#

How much context should I give an agent before it starts editing?#

Give it every applicable invariant and enough task detail to identify the correct change—then stop. Do not preload material merely because it might become relevant. Begin with repository rules, local rules, acceptance criteria, and non-goals; let supporting references enter only when the task actually requires them.

How is this different from following the agent vendor’s official setup?#

Vendor documentation explains supported mechanisms; repository context defines what correctness means in your codebase. The Claude Code documentation, for example, can tell you how documented features behave, but it cannot decide your architectural boundaries, compatibility obligations, or required validation commands.

What is the biggest context-engineering mistake in a team repository?#

The biggest mistake is allowing multiple artifacts to state the same rule differently. Engineers then update one copy while agents continue reading another. Give every durable rule one authoritative home, scope it narrowly, and link to it instead of duplicating its wording across prompts and documentation.

How do we roll back when context causes bad changes?#

Revert the bad code and the instruction that authorized it, then record the missing or incorrect invariant in its proper scope. If you cannot identify which context influenced the change, your setup is too opaque. Context must be versioned, reviewable, and separable from transient chat history.

When should we avoid adding new permanent context?#

Do not add permanent context for a one-off task, an unconfirmed interpretation, or a preference with no repository consequence. Use a task brief first. Promote the instruction only when it describes a durable invariant with clear scope, supporting evidence, and an owner responsible for keeping it current.