Why one line is not enough
“Fix the checkout bug” is a complete sentence to you, because you know which bug it is and what fixed looks like. A coding agent knows none of that. It does what the brief says and guesses the rest: which files to open, what counts as done, what it may change on the way and which tests matter. It tends to stop when the work feels finished, which is not the same as when it is.
The fix is the same habit as briefing a new hire: write down what a capable colleague would ask you before starting. The difference is that an agent rarely asks. Unless the brief tells it when to stop, it keeps going.
The parts of a brief
- 1What and whyThe outcome, and what happens today.
- 2WhereThe files or folders to start in, and one to copy.
- 3Done whenA short list a reviewer could tick off.
- 4The checkThe command that proves it, run before saying done.
- 5Must not changePublic APIs, behavior, dependencies, file formats.
- 6Out of scopeWhat to leave alone, even if it looks wrong.
- 7Stop and askAnything that cannot be undone.
- 8Hand backWhat changed, why, what ran and what is left.
Not every brief needs all eight at length, and facts that hold for every task do not belong in the brief at all. The test command, the folder map, the conventions and standing rules such as “ask before a migration” go in AGENTS.md or CLAUDE.md, the file the agent reads at the start; the guide to that file covers what to put in it. Then each brief only says what is new.
1. Start from the kind of task
Different jobs fail in different ways, so each needs a different part spelled out. Decide which kind you are writing before you write it.
| Kind of task | The brief adds | The check |
|---|---|---|
| Bug | Steps to reproduce, expected and actual, the exact error, a test that fails before the fix | The new test fails before the fix and passes after; the rest of the suite stays green |
| Feature | The outcome for the user, where it goes, a done-when list, a file to copy | A test for each done-when item, plus lint and build |
| Refactor | “Behavior must not change”, the folders it covers, the tests that must stay green, what is out of scope | The same tests pass before and after, with no edits to the tests |
| Investigation | The question, what you already know, “change nothing”, what to hand back | A written answer with evidence: files, lines, commands run and their output |
| Upgrade | The version to move to, the changelog to read, what must keep working, when to stop and ask | The build and the full test suite pass on the new version |
A bug: reproduce it, then fail a test
Give the steps that show the bug and what you expected to happen against what did. Paste the exact error or log line rather than describing it. Then ask for a test that fails because of the bug before any fix. A test that was red and turned green is evidence; a test written after the fix may only confirm what the agent already did.
A feature: a done-when list
Describe the outcome, not the keystrokes, and end with a list a reviewer could tick off. Point to an existing file that does something similar, so the new code follows your patterns instead of the agent’s defaults.
Done when: - [ ] The reports page has an Export CSV button next to Print. - [ ] The file has one row per invoice, with the columns on screen. - [ ] Amounts are plain numbers with two decimals, no symbol. - [ ] The filters on the page apply to the export. - [ ] npm test and npm run lint pass.
A refactor: behavior must not change
Say it in those words and name the tests that must pass before and after. Forbid editing them: an agent that may change the tests can always make them pass. Name the folders the refactor covers, too, so it does not spread.
An investigation: change nothing, report back
When you want an answer, not a change, say so plainly, or the agent may fix the first thing it finds. Ask for the evidence along with the conclusion.
Question: why have nightly export jobs taken over an hour since October 28, 2026? They took about ten minutes before. Change nothing: no edits, no commits, no migrations and no data changes. Read the code, job logs, metrics and query plans. Hand back: the likely cause, the files and lines involved, the evidence for it, and the fixes you would consider, with risks.
2. Name the check that proves it
The single most useful line in a brief is the command that proves the work is done: the test command, the linter, the type checker, the build, or a request against the dev server with the response you expect. Without one, the agent decides for itself when it has finished. “Make sure it works” is not a check, because nothing can fail it.
Ask the agent to run the check before it reports back and to show you the output. A summary that says “all tests pass” is a claim; the pasted result of npm test is something you can read.
3. Say what is out of scope
Agents are keen to help, and a bug fix can come back with renamed variables, a reformatted folder, a new helper nobody asked for and an upgraded library. Each of those may be fine on its own, but together they turn a five-line fix into a review nobody wants. Name what to leave alone, and add the rule to note other problems instead of fixing them.
4. Say when to stop and ask
Anything that cannot be undone needs a stop written into the brief: dropping a table, deleting data, running a migration against a shared database, force-pushing, rewriting history, deleting branches, sending messages to real people, or touching production. Write it as a stop, not a caution. “Be careful with the database” changes nothing; “before you run any migration, stop and show me the SQL” does.
Uncertainty deserves the same rule. “If the fix seems to need a schema change or a new dependency, stop and ask” turns a risky guess into a question you can answer in a minute.
5. One task per brief
A brief that says “fix the export bug, and also tidy up the date helpers while you are there” tends to come back partly done, with the parts tangled together in one diff. Split it. One task per brief, each with its own check, gives you changes you can review and merge one at a time.
For something genuinely large, ask for a plan first and no edits: the steps, the files each will touch, the risks and what it needs you to decide. Claude Code has a plan mode for this, and in any agent you can ask for the plan in the brief. Then brief each step on its own.
6. Ask for the hand-back
End the brief with what you want to read when the agent is done: what changed and why, the commands it ran and their results, anything left undone or skipped, and anything it noticed outside the task. Say whether it should commit and open a pull request, or leave the changes uncommitted for you. A clear hand-back means reading a summary instead of reverse-engineering a diff.
A bug brief, before and after
Here is one bug written twice, for a made-up online shop. The first is how most tasks get typed; the second adds each part from above.
Before
2/10 Needs work
- Has: What to make
- Missing: Who it's for
- Missing: Background facts
- Missing: Length
- Missing: Format
- Has: What to avoid
- Missing: What good looks like
- Missing: An example
- Missing: If unsure
- Missing: Layout
After, with what was added marked
10/10 Excellent
- Has: What to make
- Has: Who it's for
- Has: Background facts
- Has: Length
- Has: Format
- Has: What to avoid
- Has: What good looks like
- Has: An example
- Has: If unsure
- Has: Layout
Scores from the Grader’s free checks, with the coding agent target. The example shop and file names are made up.
The second version is longer, but every line saves a guess: the steps show what failing looks like, the test written first tells the agent when it is done, the stop rule covers the one risky turn the fix could take, and the hand-back says how to report.
Check a brief before you send it
Edit the feature request below into a brief an agent can finish: where the code is, a done-when list, the check, what must not change and when to stop. The score follows the Grader’s free checks for coding agents.
1/10 Needs work
- Missing: What to make
- Missing: Who it's for
- Missing: Background facts
- Missing: Length
- Has: Format
- Missing: What to avoid
- Missing: What good looks like
- Missing: An example
- Missing: If unsure
- Missing: Layout
Edit it and watch the score. It is worked out in your browser, and nothing is sent anywhere. Open in the Grader
Key takeaways
- A coding agent does what the brief says and guesses the rest, so write what a new teammate would ask about first.
- Start from the kind of task: a bug needs a failing test, a feature a done-when list, a refactor unchanged behavior, an investigation no changes.
- Name the command that proves the work is done, and ask to see its output.
- Say what is out of scope, and write a stop before anything that cannot be undone.
- Give one task per brief, and ask for a plan first when the change is large.
- Keep standing facts in AGENTS.md or CLAUDE.md, so each brief only says what is new.
Questions
What is a good prompt for Claude Code?
A brief with the outcome, where in the code to start, what must not change, the command that proves it works, when to stop and ask, and what to report at the end. For a bug, add steps to reproduce and ask for a failing test first. Put the facts every task needs, such as the test command and folder layout, in CLAUDE.md so you do not repeat them.
How do I prompt Codex or Cursor’s agent?
The same way. The parts of a good brief do not depend on the agent: outcome, location, done-when, a check to run, scope and a stop rule. What differs is the file of standing facts each one reads; Codex and Cursor read AGENTS.md, and the AGENTS.md guide covers what goes in it.
Should I ask a coding agent for a plan first?
For a change that spans several files, or one where you are not sure of the approach, yes. Ask for the steps, the files each step touches, the risks and what it needs you to decide, with no edits yet. Read and correct the plan, then let the agent work through it or brief each step separately. Claude Code has a plan mode built for this.
How long should a task for a coding agent be?
As long as it takes to remove the guesses, and no longer. A small bug brief is often a dozen lines; a feature with a done-when list can be a page. If a brief keeps growing, it is usually several tasks, and splitting it into one brief per change, each with its own check, works better.
What should a coding agent never do without asking?
Anything that cannot be undone: dropping a table, deleting data, running a migration on a shared database, force-pushing, rewriting history, or touching production. Write a rule to stop and show you first, in the brief and as a standing rule in AGENTS.md or CLAUDE.md. The Agent Brief Check flags briefs that mention such steps without one.
Prompts to use with this
- Brief a coding agent to fix a bugYou are handing a bug to Claude Code, Codex or another coding agent and want a root-cause fix with proof, not a guess.
- Brief a coding agent to build a small featureYou are handing a well-defined feature to Claude Code, Codex or another coding agent and want a plan first, code that fits the codebase, and tests as proof.
- Brief a coding agent to refactor without changing behaviorYou need a coding agent to clean up code while tests keep passing and behavior stays the same.
- Brief a coding agent to speed up a slow code path, measured before and afterSomething in your code is too slow, and you want an agent to find the cause and prove its fix with measurements rather than guesses.