Context Engineering for Coding Agents
These are notes from my ai-playbooks repo, which has one page per kind of coding-agent task. Each page covers the setup, the steps and their prompts, what usually goes wrong, and how to tell the work is done. The post Your Best Prompt Will Fail in the Next Repo covers why I write them down.
Most of the steps come from one idea, usually called context engineering: an agent does worse as its context window fills with things it doesn’t need, so you decide what goes in at each step and what stays out. The prompt wording is the smallest part of it.
The default loop
Before the first step, the repo needs a clean working tree, a branch for the work, and a test command the agent can run, ideally listed in AGENTS.md.
-
Research. The agent reads the relevant code and writes
research.md, so the later steps work from a short summary instead of the whole repo. On a large repo, sub-agents search each area and hand back only what they found.Read the code involved in <task>. Write research.md: files that matter, how they connect, risks. Do not change any code. -
Plan. The agent turns the research into
plan.md, and you read it before any code exists, because a bad line in a plan becomes hundreds of bad lines of code. It’s also the cheapest review you’ll do: a plan takes minutes to read.From research.md, write plan.md: ordered steps, files touched per step, what stays out of scope, how each step is checked. -
Implement. A fresh session gets only the plan, so none of the research noise comes along. It runs the tests and commits after every step, which keeps each mistake small and easy to undo.
Follow plan.md one step at a time. Run the tests after each step and commit. Stop and ask if the plan doesn't fit what you find. -
Check. Run the tests or the build, then read the diff for anything the plan didn’t include. The prompt asks about tests on purpose: an agent told to make tests pass will sometimes change the tests.
Summarize what changed against plan.md. List anything you did that the plan didn't include, and any tests you modified.
If the check fails, go back to implement with what it found.
The task pages
Each page starts from those four steps and changes them where its task needs it.
Refactoring with pinned tests
Refactoring changes the structure of code without changing what it does, so the first step pins down what it does today. If coverage is thin, the agent writes characterization tests, which record current behavior, right or wrong, and they’re committed on their own. The implement prompt then adds “Do not edit any test file.” Watch for error handling that gets “simplified” away and for cleanup nobody asked for, and list both as out of scope in the plan. The work is done when the same tests pass before and after and the diff on the test files is empty.
Tests ranked by risk
For code with no tests, or too few to change it safely, research lists the behaviors worth protecting, ranked by risk, instead of listing functions. The implementing session writes tests only, and if a test turns up a bug, it records it in notes.md and leaves the code alone. The tests to reject are the ones that assert nothing, lock in a bug or mock the thing under test. To check the rest, break the code on purpose and see whether the tests fail.
An AGENTS.md for an unfamiliar repo
In a repo you don’t know, the first job is a file the agent can work from. Research explores the repo, with sub-agents on a large one, and the agent drafts an AGENTS.md with commands, layout, conventions and gotchas, running every command it lists. Then you add what only people know: files nobody touches, deploy rules, past incidents. One way is to have the agent interview you, one question at a time. The test is a fresh session that sees only the file and the repo. If it can install, build and run the tests from that alone, the file is good enough to start with.
Legacy code in slices
An old system gets rebuilt one slice at a time while the old code keeps running. Research becomes a domain map: what the system does, its entry points, its data flows and anything odd. Each plan picks a seam, a boundary where new code can take over one route or function (the strangler fig pattern), and moves one slice across it. A slice is done when old and new paths give the same results on the same inputs. Removing the old code is a slice of its own, after the new path has run for a while. The risk to watch is drifting into a full rewrite.
Upgrades with breaking changes
For a framework, language or major dependency upgrade, research reads the changelog and migration guide and lists only the breaking changes that touch this codebase, with file references. The plan decides between one jump and a series of intermediate versions. The implement prompt adds “Fix the cause of each deprecation warning instead of silencing it,” and the check reads the lockfile diff line by line for packages the plan didn’t mention.
Clean-room rebuilds from a spec
A clean-room rebuild replaces the four steps. One session writes spec.md from public docs, public interfaces and observable behavior, and you strip out anything that describes the original’s internals. A second session, in a directory with no copy of the original code, gets only the spec, plans, and builds once you approve the plan. Tests come from the spec too, and provenance.md records what each session was given. The method can’t rule out the model reproducing code it saw in training, and it makes no claim about legal independence from the original.
Run notes
The pages only get better from real runs. Each run gets a short note with the repo and commit, the task, what worked, what the page got wrong, and what changed on the page afterwards. A page counts as tested after its second real task, and until then it’s marked as a draft.
Sources
- Effective context engineering for AI agents, Anthropic.
- Best practices for Claude Code, Anthropic.
- Advanced Context Engineering for Coding Agents, HumanLayer, where the research, plan, implement workflow and the “hundreds of bad lines” point come from.