Context engineering for coding agents
Agents do not remember your project; they read what you put in front of them. Good results come from what the model sees: clear instructions, the right files, a plan, and tasks small enough to verify.
What it is
Context engineering is deciding what goes into the model's and in what shape. More text is not better: a long, noisy context makes the model miss instructions and costs more. The aim is the smallest context that contains everything needed to do the task right.
A project instructions file
Most harnesses read a file at the repository root at the start of every session. has become a common convention across tools; Claude Code reads CLAUDE.md (which can point to AGENTS.md). Put in it what an experienced new teammate would need on day one, and keep it short.
# Project notes for coding agents
## Commands
- Install: `npm ci`
- Test (run before every commit): `npm test`
- Lint and types: `npm run lint && npm run typecheck`
## Conventions
- TypeScript strict. No `any`. Prefer small pure functions.
- Database access only through `src/db/*`; never build SQL by string concatenation.
- New endpoints need an authorization check and a test for "user B cannot read user A's data".
## Boundaries
- Do not edit `infra/` or `.github/workflows/` without asking.
- Never read or print `.env` or anything under `secrets/`.
- Ask before adding a dependency.Working method
- Plan first: ask for a plan (many tools have a read-only ), edit it, then approve. Fixing a plan is cheaper than fixing code.
- Small tasks: one change per session or branch, with a test that decides success. Large vague tasks produce large vague diffs.
- Point to examples: "follow the pattern in src/users/handler.ts" beats a paragraph of description.
- State the check: tell the agent how to verify its own work (run this test, this linter, this command).
- Reset often: start a fresh session when the context gets long or the agent gets confused, carrying over only the decisions.
- Give tools, not essays: connect an or a script for a repeated need (query the staging database read-only, open a ticket) instead of pasting data into chat.
Skills, hooks and subagents
Beyond the instructions file, harnesses offer extension points. Skills package a procedure the agent loads only when relevant. Hooks run your code at fixed moments (before a tool runs, after an edit), which is the reliable place to enforce rules the model might forget, such as formatting or blocking a dangerous command. Subagents run a focused task in their own context and return a summary, which keeps the main conversation clean. Treat anything an agent can run as code with your permissions, and review it like code.
Common mistakes
- A giant instructions file full of rules the agent ignores. Short and specific wins.
- Rules that are only prose. If it must never happen, enforce it with permissions, hooks or CI, not a sentence.
- Secrets in the instructions or in pasted logs.
- Letting context fill with failed attempts. Start over with what you learned.
- Trusting the agent's claim that tests pass without running them yourself.
connections on the map
- When to use whatis followed byContext engineering for coding agents
- Context engineering for coding agentsscales intoOrchestration and parallel agents
- Context engineering for coding agentsstates the checks ofThe verification loop
updated on 14/10/2026 · sources to go deeper · report an error
in other domains
- Tool callingai-agentstools and permissions decide what the agent can do
Study before
Unlocks
test what you learned
Loading questions…