Context engineering for coding agents: what to put in, what to keep out

What is context engineering?

Everything a coding agent knows about your task at a given moment sits in its context window: the system prompt, your instructions, the files it has read, the output of the commands it has run, and the conversation so far. The model has no other memory of your project. If a fact is not in that window, it cannot use it.

Anthropic's engineering post Effective context engineering for AI agents frames the idea as a shift from prompt engineering. Prompt engineering is about finding the right words for one instruction. Context engineering asks the broader question of which configuration of context is most likely to produce the behavior you want. The post gives the guiding principle as finding the smallest possible set of high-signal tokens that make the desired outcome likely.

For a builder using a coding agent this is practical, not theoretical. Most bad results trace to one of four context problems: the agent lacks a fact it needed, it has too much irrelevant material, it holds two instructions that contradict each other, or the early part of a long session has scrolled out of useful reach.

What goes into a coding agent's context?

It helps to sort context by how long it lives and who controls it. Different layers need different handling.

Two layers are yours to write ahead of time: the always-on instructions and the task description. The rest the agent builds as it works, and you shape it indirectly. The skill is knowing which fact belongs in which layer.

What belongs in CLAUDE.md, AGENTS.md or a rules file?

These are the project files that load before you type anything. Claude Code reads CLAUDE.md. A growing set of tools read AGENTS.md, which its own site describes as plain Markdown with no required fields, where the closest file to the edited one wins and a direct chat prompt overrides everything. Cursor uses rules files in .cursor/rules; its rules documentation lists four modes: always apply, apply intelligently by description, apply to specific files by pattern, and apply only when mentioned.

The rule of thumb: put in the file what you would otherwise re-explain every session, and nothing else. Claude Code's memory documentation lists the triggers for adding a line: the agent makes the same mistake a second time, a code review catches something it should have known, or you type the same correction again.

Claude Code's documentation is direct about two things worth copying into any tool. It says CLAUDE.md is treated as context, not enforced configuration, so wording affects how reliably it is followed, and it recommends instructions concrete enough to verify: "Use 2-space indentation" rather than "Format code properly". It also advises targeting under 200 lines per file, because longer files consume more context and reduce adherence.

The details of each file are covered separately: how to write a CLAUDE.md, what AGENTS.md is and how Cursor rules work. Here is a skeleton that works in any of them.

# Project: <name>
<One sentence on what the app does and who uses it.>

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Tests: `pnpm test` (run before saying a task is done)
- Lint and types: `pnpm lint && pnpm typecheck`

## Facts the code does not show
- <Money is stored as integer cents.>
- <All dates are UTC.>
- <Auth is handled by X; never write your own session logic.>

## Rules
- <API handlers live in src/api/handlers/. One file per route.>
- <Never edit anything under generated/.>
- <Never put a secret key in client code or in a NEXT_PUBLIC_ variable.>

## When unsure
Ask one question instead of guessing. Do not add features that were not requested.

How do you write the context for a single task?

The always-on file covers the project. Each task still needs its own brief. A good one answers five things: the goal, the files to start from, the limits, what to avoid, and how to check the result. Pointing at files beats pasting them, because the agent reads what it needs when it needs it.

Goal: <one sentence: what should be true when this is done>.
Start from: <file or folder paths, e.g. src/billing/invoice.ts and its test>.
Background: <only what the code does not show, e.g. refunds are issued in a separate job>.
Limits: change only the invoice module. No new dependencies. Do not touch the database schema.
Do not: reformat unrelated code, rename existing functions, add features.
Done when: <a command to run, e.g. `pnpm test invoice` passes, and the new test for a zero-amount invoice exists>.
If something in this brief conflicts with the code, stop and ask.

Claude Code's best-practices page makes the same point from the other side: give the agent a check to run. An agent that can run the tests sees its own mistakes, and you stop being the only one who finds them.

A before and after shows the difference. The first version leaves the agent to find everything. The second hands it the few facts it cannot find.

Fix the bug in the checkout, it sometimes charges twice. Here is the whole checkout folder and the last two weeks of logs: <40 pages pasted>

Goal: a double click on Pay must create one charge.
Start from: src/checkout/pay.ts (the handler) and tests/checkout/pay.test.ts.
Background: the payment provider accepts an idempotency key header; we do not send one yet.
Limits: no new dependencies, no schema changes.
Done when: a new test fires two identical requests and asserts one charge, and `pnpm test checkout` passes.

How do you keep a long session from degrading?

Long sessions fill the window with old attempts, dead ends and big tool outputs. Anthropic's post names three techniques for work that outlasts one window. Each has a plain-language version a builder can apply.

Claude Code's best-practices page adds session habits that apply anywhere. Run /clear between unrelated tasks, so the next task does not carry the last one's history. Watch the first minute of a task and stop the agent the moment it drifts. And after two failed corrections, clear the session and write a better prompt instead of sending a third correction on top of a polluted context.

• One task per session. If the next task shares nothing with the last, start fresh.
• Write progress down before you clear. Ask the agent to update a notes file with what is done, what is next and what failed. The next session starts from that file, not from memory.
• Compact with a purpose. A focus instruction keeps the facts you need and drops the rest.
• Keep noisy output out. Ask for test runs that print failures only. A 5,000-line log is worth a summary, not a paste.
• Check what is loaded. In Claude Code, /context shows what is using the window, including memory files.

Should you paste files or let the agent find them?

Prefer letting the agent look things up. Anthropic's post describes a just-in-time approach: the agent keeps lightweight references such as file paths and queries and loads data into context only when needed, as Claude Code does when it reads a file or searches with a command. A path costs a few tokens. A pasted file costs thousands and stays in the window.

Paste when the material is small and certain to matter: an error message, a failing test, a three-line example of the output format. Point when it is large or you are unsure: "look at src/billing", "the pattern is in src/api/users.ts". An example file works better than a paragraph describing a convention, because the agent copies what it sees.

Be careful what you put in context at all. Anything in the window may be sent to the model provider and can end up echoed in code or commit messages. Keep secrets, customer data and keys out. Use placeholders in examples.

What are the common context mistakes?

• A 600-line instructions file. Everything in it competes for attention, and the rules that matter get lost among the ones that do not. Trim, and move narrow rules into scoped files.
• Contradictions. An old line says "use class components"; a newer one says "use hooks". The agent may pick either. Review the file on a schedule. Claude Code's documentation says contradictory instructions may be followed arbitrarily.
• Instructions that restate the code. "This project uses React" is visible in package.json. Spend the line on something invisible.
• Stale instructions. Paths that moved and commands that no longer exist send the agent to the wrong place. Delete what stopped being true.
• Pasting the world. Giving the whole repository when the change lives in one module trades accuracy for the feeling of being thorough.
• Never writing the done-check. Without a command that proves success, the agent says "done" when the code compiles.
• Fighting a bad session. If three corrections have not worked, the window now contains the confusion. Start over with a sharper brief.

A good way to practise is to take an idea and write its brief from scratch. Browse the developer tools ideas on the board, pick one, and write a task brief with the template above. Every idea on the board also has a generated build prompt you can compare yours against. If you want your brief to be a full written specification, see spec-driven development, and for a general method see how to write an app build prompt.