Context Engineering for AI Coding Agents
On this page
Learning Objective
Treat what the agent sees as the main lever on what it produces. Identify the five kinds of context a coding agent needs, durable rules, task specifics, relevant code, examples and feedback, and learn where each one should live so the agent gets the right information at the right time.
Concept Explanation
When an agent produces poor code, the instinct is to blame the model. Far more often the cause is context: the agent did not know the convention, did not see the helper that already exists, did not know how the feature is tested, or had its window filled with irrelevant output. Context engineering is the discipline of deciding what the agent should see at each step, and for coding agents it is the highest-leverage skill you can develop.
A coding agent needs five kinds of context. Durable project rules are true for every task: how to build and test, coding conventions, architectural boundaries, things never to do. They belong in a project instruction file the agent loads automatically (Day 7). Task specifics are true for this task only: the goal, the constraints, acceptance criteria and what is out of scope. They belong in your prompt or a spec file (Days 8 and 10). Relevant code is the existing implementation the change touches and the patterns it should follow; the agent finds much of it by searching, but naming the key files and a good example saves exploration and prevents it from inventing a new pattern. Examples show the expected shape: a similar endpoint, a test in the house style, a past pull request. Feedback tells the agent whether it is succeeding: test results, type errors, lint output, screenshots, logs.
Each kind has a natural home and a natural time. Durable rules load at the start of every session. Task specifics arrive with the task. Relevant code and examples are best pulled just in time, when the agent needs them, rather than pasted in up front. Feedback arrives continuously through tools. Problems come from putting context in the wrong place: rules repeated in every prompt, task details buried in the instruction file where they confuse unrelated tasks, or entire directories pasted into chat.
There is also context you should keep out. Long logs, generated files, lockfiles, unrelated modules and earlier failed attempts all compete for attention. Tell the agent which directories to ignore, keep test output concise, delegate broad searches to subagents that return summaries, and start a fresh session rather than dragging a failed attempt into a new one.
A useful mental model is onboarding a strong contractor who has never seen your codebase. You would not hand them the entire repository and say "add billing". You would explain the house rules once, give them a clear ticket, point them at the module and a similar feature, and show them how to run the tests. Agents need exactly the same, every time, because every session starts with no memory.
| Kind of context | Example | Where it lives | When it loads |
|---|---|---|---|
| Durable rules | Test command, conventions, forbidden patterns | CLAUDE.md or AGENTS.md | Every session |
| Task specifics | Goal, constraints, acceptance criteria | Prompt or spec file | With the task |
| Relevant code | The module to change, its callers | The codebase, named in the prompt | Just in time, by search |
| Examples | A similar endpoint and its tests | Named files, past pull requests | Just in time |
| Feedback | Test failures, type errors, screenshots | Tools the agent runs | Continuously |
Worked Example: A Context-Rich Task Brief
This brief gives a coding agent all five kinds of context for a real task. Durable rules are not repeated because they already live in the project's AGENTS.md.
Task: Add rate limiting to the public search endpoint.
Goal and constraints (task specifics)
- Limit GET /api/search to 30 requests per minute per API key; anonymous callers by IP, 10/min.
- Return 429 with a Retry-After header and our standard error body.
- No new infrastructure: use the existing Redis client.
- Out of scope: other endpoints, admin bypass, UI changes.
Relevant code (start here instead of exploring everything)
- src/api/search/route.ts the endpoint
- src/lib/redis.ts shared Redis client
- src/api/errors.ts standard error responses
Example to follow
- src/api/login/rateLimit.ts and its tests: same sliding-window approach, same key format.
Feedback (how to know you are done)
- npm test -- src/api/search must pass, including new tests for 429 and Retry-After
- npm run typecheck && npm run lint
- Show me the test output and a summary of the diff when finished.The brief is short because the durable rules live elsewhere and the code is referenced, not pasted. The example file does the heavy lifting: it tells the agent the approach, key format and test style without a paragraph of explanation.
Real-World Examples
- Anthropic's Claude Code best practices recommend giving the agent specific file references, examples to follow and a way to verify its work, and report that agents perform markedly better when they can check results against tests or screenshots.
- Shopify's CEO Tobi Lütke popularized the phrase context engineering in June 2025, describing it as the art of providing all the context for a task to be plausibly solvable by the model, and the term was quickly adopted by practitioners building coding agents.
Review Questions & Answers
The agent knows only what it reads and is told. If it missed a convention, an existing helper or how the feature is tested, it will produce plausible but wrong code regardless of how capable the model is.
In a project instruction file the agent loads every session. Repeating them in prompts is error-prone and wastes effort, and they apply to every task.
An example shows the exact pattern, naming, structure and test style the codebase uses, which conveys many conventions at once and reduces the chance the agent invents a new pattern.
Long logs, generated files, lockfiles, unrelated modules and the history of earlier failed attempts, because they compete for attention and can push important details out.