Context engineering for code
Coding with agents · topic coding-with-agents/context
An agent's output quality follows the quality of its context. This topic covers what belongs in a project's standing instructions, how to scope a task so the agent looks in the right places, how to point it at specific files, and how to keep a session from degrading as its context fills.
Concepts
- Project instructions
- A file in the repository the agent reads at the start of every session, holding what it needs to know each time: how to build and test, the conventions to follow, the places not to touch. It is where a recurring agent mistake gets fixed once. Keep it short and factual; long instruction files are followed less reliably than short ones. glossary
- Scoping a task
- Telling the agent where a task lives and where it stops: which module, which layer, which files are in play and which are off limits. Scoping saves context by avoiding exploration of irrelevant code and prevents the well-meaning refactor that spreads a small change across the repository. A scoped brief also makes the resulting diff easier to review. glossary
- Referencing files
- Naming the exact files, functions or documents the agent should read instead of describing them, so it loads the right context on the first try. A path and a line number beat "the config code". Reference the example to imitate, the test to extend and the spec to follow; the agent will otherwise pick whichever similar file it finds first. glossary
- Avoiding context rot
- Keeping the session's context lean so the agent keeps following instructions and remembering the goal: one task per session, summaries instead of raw logs, fresh sessions for new work, and no pasting of whole files it can read itself. When answers drift or earlier rules get ignored, the context is full; compact or restart rather than push on. glossary
Links
- Builds on: Plan, implement, verify, Grounding and memory
- Leads to: nothing yet
- Related: Project instructions
- Competencies drawing on it: Ships a change with a coding agent through plan, implement and verify
Lessons
- Writing project instructions the agent reads every session (tutorial)
- Telling the agent where the task is and where it stops (tutorial)
Your reference
Each lesson above adds its takeaways and its example here once you finish it. Your reference lists every lesson you have finished.
Writing project instructions the agent reads every session
Unlocks when you finish Writing project instructions the agent reads every session.
Takeaways
- The project instructions file is loaded at the start of every session, so a rule there reaches every later session, and a correction in the chat reaches one.
- A mistake that repeats shows when you put two sessions side by side. Fix it once, with one line in the file.
- Write the line so you can check the agent against it: name the action the agent took and what to do instead.
- A long file gets its rules ignored. When you add a line, delete the ones the agent no longer needs.
- Keep the context lean: one task per session, summaries instead of raw logs, and compact or restart when the agent stops following rules it followed earlier.
- Record a decision in the repository and point at it from the instructions file, because the next session never reads the transcript where you made it.
Example
Read the instructions file · open in the lesson
Print the file from inside the copy.
cat AGENTS.mdPrints the lines below (verified in CI from site/examples/coding-with-agents/project-instructions/instructions.py)
# Agent instructions for todo - Python 3, standard library only. No new dependencies. - Tests use `unittest`. Run them with `python3 -m unittest -q`. - `docs/SPEC.md` is the specification for the commands. Follow it. - `legacy/` is the old single-file version, kept for reference. Never edit it and never import it. - Do not edit `todos.json`; the tests use their own lists.
Telling the agent where the task is and where it stops
Unlocks when you finish Telling the agent where the task is and where it stops.
Takeaways
- Scope a task by saying which files are in play and which are off limits. The agent reads less, and the change stays where you put it.
- Reference files by path instead of describing them. Name the example to imitate, the test to extend and the spec to follow, or the agent imitates the first file that looks similar.
- A boundary that holds for every task belongs in the project's instruction file, and the boundary for this task belongs in the brief.
- End the brief with the check that proves the task done, and run it yourself.
- A scoped brief gives the reviewer a small diff, and a small diff is the one that gets read.
Example
Count the lines per file · open in the lesson
Run this from inside the copy. The course prints the same table from its own copy of the fixture, and your wc may pad the numbers differently. The find leaves out hidden files such as .git/ and a .DS_Store, and the sed strips the ./ that find prints.
find . -type f -not -path '*/.*' | sed 's#^\./##' | LC_ALL=C sort | xargs wc -lPrints the lines below (verified in CI from site/examples/coding-with-agents/scoping-and-referencing/files.py)
8 AGENTS.md 28 README.md 16 docs/SPEC.md 28 export.py 57 legacy/todo_v1.py 13 render.py 27 store.py 45 test_todo.py 55 todo.py 18 todos.json 295 total
Sources
AEC-15AGENTS.md: contents, monorepo hierarchies, with a builder widget, Agent Engineer Course (course)Academy claude-code-101Claude Code 101, Claude Academy (course)Academy claude-code-in-actionClaude Code in action, Claude Academy (course)