Give your AI coding agent better context

Start with a working brief

“Make the search better” leaves an agent to invent the problem. Does better mean faster, more tolerant of spelling errors, easier to use with a keyboard, or more accurate? A useful brief makes that decision visible before implementation begins.

Describe what a person does, what happens today, and what should happen instead. Then identify the constraints that make the task yours: the data source, the existing interface, the supported platforms, and the behavior that must remain stable. A short concrete brief often gives the agent more usable direction than a long history of the project.

The goal is not to prewrite every line of code. Give the agent enough constraints to avoid making product decisions accidentally, while leaving ordinary implementation choices open. If a choice matters to the user, make it an explicit part of the task.

Put context in the right place

Context includes instructions, examples, tool descriptions, retrieved files, and previous results. Anthropic’s context engineering guide frames the problem as selecting useful information within a limited working context. More material is not automatically more useful.

Read the diagram explanation

• Durable rules. Repository conventions and required checks
• Task brief. One outcome and its boundaries
• Relevant evidence. Current files, errors, and examples
• Recent decisions. What changed and what remains open

Put stable project guidance in the repository’s supported instruction file. Put a one-off request in the task. Link to relevant files instead of pasting an entire codebase, and ask the agent to inspect the implementation before proposing changes. Tool-specific instruction names and precedence differ; check the tool’s documentation rather than assuming every file is loaded automatically.

Include negative constraints only when they prevent a realistic mistake. “Do not change the public URL” matters in a routing task. A page of unrelated prohibitions makes it harder to find the actual requirements. If an older note contradicts current code, call out the conflict and establish which source should govern the decision.

Make ambiguity testable

For the article search example, supply a tiny dataset and expected results. The example below is deterministic JavaScript, independent of any model. Save it as context-example.mjs and run node context-example.mjs. The assertions describe the agreement a future implementation must satisfy.

import assert from 'node:assert/strict';
const articles = [
  { title: 'Agent loops', description: 'Tools and feedback', category: 'Foundations' },
  { title: 'Git worktrees', description: 'Parallel coding', category: 'Workflows' },
];
const search = (query, category = 'All') => articles.filter(a =>
  (category === 'All' || a.category === category) &&
  (a.title + ' ' + a.description).toLowerCase()
    .includes(query.trim().toLowerCase())
);
assert.equal(search('  TOOLS  ')[0].title, 'Agent loops');
assert.equal(search(' ', 'Workflows').length, 1);
assert.equal(search('missing').length, 0);
console.log('3 acceptance examples passed');

This example locks down case folding, whitespace handling, category filtering, and the empty result. It does not establish full-text relevance, Unicode normalization, or typo tolerance. If those capabilities matter, add examples for them before choosing an algorithm or service.

Keep context useful over time

Long tasks collect failed hypotheses, stale screenshots, superseded plans, and partial results. Preserve the current state deliberately. A handoff should explain the goal, the chosen approach, exact relevant files, verification already completed, and the next unresolved step. Avoid a transcript-shaped recap that makes the next reader reconstruct the decisions.

For example: “Title and description search works. Category selection is retained when the query clears. Empty results have a reset action. Keyboard focus and screen-reader announcements still need browser verification.” That is useful because it tells the next person where confidence ends.

When a new requirement arrives, update the brief rather than attaching a contradictory instruction at the bottom. For concurrent work, establish a shared contract first; the guide to splitting agent tasks shows how to keep those boundaries explicit.