Anthropic's Official Counter-Example: Replacing "Fix the Login Bug" with a Six-Field Task Brief

Open the Claude Code best practices page and look at the table under "Provide specific context in your prompts." The last row's "Before" column says: "fix the login bug."

The "After" is much longer: "Users report login failures after session timeout. Check the auth flow in src/auth/, especially token refresh. First write a failing test that reproduces the problem, then fix it." It names the symptom, where to look, and what "fixed" means.

Everyone has sent that "Before" version. The agent draws its own boundaries and decides for itself when it's done. You get back a diff and have to reverse-engineer what it did, and whether it can be merged depends on judgment calls you never saw.

The solution is a short brief with six fields. Each field closes a gap the agent would otherwise fill by guessing.

Three Vendors, One Checklist

The vendors building these agents say the same thing in their own docs.

Anthropic's guide says to "reference specific files, explain constraints, and point to example patterns," and describes the most useful spec as one that "names the files and interfaces involved, states what's out of scope, and ends with end-to-end verification steps."

OpenAI's Codex prompting guide says a useful prompt "names the behavior you want, points to relevant code or a repro, preserves important constraints, and states how to verify the change."

GitHub's guidance for Copilot coding agents lists the elements of an ideal task: a clear problem description, "complete acceptance criteria for what a good solution looks like," and "direction on which files need changes."

Put these side by side and you get those six fields. Order doesn't matter much — what matters is having all six.

Why do all three vendors' docs converge on the same checklist? Because they're all dealing with the same underlying mechanism: a coding agent is essentially a loop making decisions in a vast action space, choosing at each step which file to read, which line to change, when to stop. The real function of a prompt isn't "describing the task" — it's shrinking that action space — narrowing an infinite possibility of repo exploration down to a predictable path.

It's worth noting that CLAUDE.md, AGENTS.md, and the Codex guide — despite coming from competing vendors — all list "acceptance criteria" and "scope boundaries" as core elements. This tells us the problem isn't a flaw in any particular model, but the inherent structure of task delegation: any executor — human or agent — will fill gaps with their own default assumptions when goals, boundaries, and stopping conditions are missing. Humans clarify by asking follow-up questions in meetings; agents can only guess silently.

The Six Fields: Bad vs. Good

We'll use the login bug from Anthropic's table throughout, set in a TypeScript repo.

1. Goal

Bad: Fix the login bug.

Good: Users with expired sessions get a 401 when they re-login. After the fix, an expired user can log in successfully on the first attempt.

Why it changes behavior: The agent needs a stopping point it can recognize. "Fix the bug" has no stopping point. Symptom plus "what fixed looks like" gives it one — which is exactly what Anthropic's "describe the symptom" row means.

The key concept here is the stopping condition. Agents don't have the human intuition of "close enough"; their loop needs a decidable termination signal. When a prompt only says "fix the bug," the model falls back on the "looks done" standard it acquired during training — and that standard is often not what you actually want.

Writing "symptom" and "what fixed looks like" separately is really giving the agent two things: an observation description for locating the problem (an expired user gets 401), and a target state for judging completion (succeeds on the first attempt). This "current vs. target" pattern also appears in test-driven development acceptance criteria, SRE incident ticket templates, and user stories in product requirement docs — they all solve the same problem: letting the executor know that "done" isn't a feeling but a checkable fact.

2. Files in Scope

Bad: omit it. The agent greps the whole repo and reads everything matching "login."

Good: Start with src/auth/session.ts and src/auth/refresh.ts. Put new tests in tests/auth/.

Why: Every file the agent reads consumes context window, and Anthropic's docs say performance "degrades as the window fills." Pointing at the right files saves that budget for the fix itself. It also tells the agent where you expect the diff to appear, so changes showing up elsewhere are conspicuous to both of you.

3. Out of Scope

Bad: omit it, or write Keep it clean.

Good: Don't touch the login UI, the public API shape, package.json, or the lockfile. Don't reorder files you're not changing. If the fix looks like it needs any of these, stop and tell me.

Why: The agent will fix things it notices along the way. Renaming a helper or tidying an import turns a two-file fix into a review of everything adjacent. Codex's own bug-fix example includes the line "don't change the API shape." "Stop and tell me" gives the agent a legitimate action instead of silently widening the change.

4. Constraints

Bad: Write good code.

Good: Keep the fix minimal. Write a failing test that reproduces the timeout first, then fix it. No new dependencies. Follow the existing refresh pattern in src/auth/refresh.ts.

Why: Constraints determine how the agent gets to the finish line. "Make the minimal fix and add a regression test if feasible" comes from OpenAI's example prompt; Anthropic's example says "avoid mocks" and "build from scratch using only libraries already in the codebase." "Write good code" constrains nothing, because the agent already thinks it's writing good code.

5. Done When

Bad: Make sure it runs.

Good: Done means npm test -- tests/auth passes and npm run lint exits 0. Run both before telling me you're finished.

Why: In Anthropic's words, "Claude stops when the work looks complete. Without a check it can run, 'looks complete' is the only signal available, and you become the verification loop." A command with a pass/fail result lets the agent run it itself, read the output, and retry. If you add only one field, add this one.

The phrase "you become the verification loop" points to a concrete engineering-economics problem: the agent re-reads context and rebuilds its understanding of the task every turn, while the human reviewer has to reverse-engineer the diff and judge whether the change is acceptable. If the agent can't run checks itself, this expensive loop falls entirely on the human — and repeats every turn.

A runnable command (like npm test) changes the cost structure: the agent can run tests, read output, and retry on failure without human intervention, internalizing "verification" as an automatic loop. This is also why this field matters most among the six — the other five reduce the directional probability of the agent going wrong; only this one can intercept errors on the agent's side directly. The industry calls this pattern a self-verification loop; it's the same idea as "give the agent an executable feedback signal."

6. Report Back

Bad: omit it. You'll get a cheerful paragraph saying the bug is fixed.

Good: When done, reply with: one sentence on the root cause, which files you changed, which commands you ran and their results, and anything you noticed but didn't change.

Why: The same Anthropic guide says to have the agent "show evidence rather than claim success," because "reviewing evidence is faster than re-running verification yourself." OpenAI's version is "report commands and results." Problems the agent spotted outside scope come back as a list you can triage, and the diff stays at the size you asked for.

The Full Brief Template

Keep these headings; the agent will read them as structure.

GOAL
<what's broken, what fixed looks like>

IN SCOPE
<files or directories to read and change>

OUT OF SCOPE
<what not to touch; stop and ask when needed>

CONSTRAINTS
<patterns to follow, dependencies, test-first, size>

DONE WHEN
<commands that must pass before saying done>

REPORT BACK
<what your final message must contain>

Filled in for the login bug:

GOAL
Users with expired sessions get a 401 when they re-login.
After the fix, an expired user can log in on the first attempt.

IN SCOPE
src/auth/session.ts, src/auth/refresh.ts,
new tests in tests/auth/.

OUT OF SCOPE
The login UI, the public API shape, package.json,
the lockfile. Don't reorder other files.
If the fix needs any of these, stop and ask.

CONSTRAINTS
Minimal fix. Failing test first, then fix.
No new dependencies. Follow the pattern in src/auth/refresh.ts.

DONE WHEN
npm test -- tests/auth passes.
npm run lint exits 0.

REPORT BACK
One sentence on the root cause. Files changed.
Commands run and their results.
Things noticed but not changed.

Most of what's login-bug-specific is concentrated in the goal and the paths. The out-of-scope list, the constraint style, and the report-back line carry over almost verbatim to the next task.

What the Brief Can't Do

The brief is a request. Anthropic's docs draw a line between instructions in CLAUDE.md ("advisory") and hooks ("deterministic, guaranteed to happen"). The OUT OF SCOPE field is the same. Nothing stops the agent from stepping over the line, so you have to check.

Two cheap checks after the agent reports back:

**The distinction between advisory and deterministic instructions** is the key to understanding this section. Whatever you write in a prompt or CLAUDE.md ultimately remains part of the model's input, and the model can choose to follow it or ignore it; hooks, CI checks, and branch protection rules are code that executes outside the model, triggered regardless of what the model thinks. Anthropic's docs use these two words precisely to remind users: **don't entrust verifiable rules to prompts; entrust them to the execution layer.**

This is the old software engineering principle of "policy vs. mechanism" replaying in the agent era. Prompts are policy — they express intent; hooks and git checks are mechanism — they enforce outcomes. An effective agent workflow needs both: briefs to express intent, automation to enforce boundaries. With only the former, boundaries are nominal; with only the latter, the agent careens through the action space without guidance.

# Which files did this branch touch?
git diff --stat main...HEAD

# Did the lockfile change?
git diff --name-only main...HEAD -- package-lock.json

Run the agent on its own branch or worktree so scope mistakes stay on that branch. As for done-checks, Claude Code's own Stop hook can prevent a turn from ending until your script passes — Hermes optional.

Two more limitations. Lines that are identical in every brief (your test runner, lint command, style rules) belong in CLAUDE.md (Claude Code) or AGENTS.md (Codex), which the agent reads every session. Briefs are for what changes per task. Also, not every task needs six fields. Anthropic's guide says if you "can describe the diff in one sentence," you can skip planning. Fixing a typo is one sentence. A login bug spanning two files plus a test is not.

One-line Summary

Three agent vendors' docs converge on a six-field brief template — explicit goals, scope, constraints, and done-checks replace vague instructions.

Paragraph Summary

The article contrasts "fix the login bug" with a concrete prompt, noting that vague requests let the agent define its own scope and completion criteria, leaving the user with a diff that's hard to review. Synthesizing coding-agent docs from Anthropic, OpenAI, and GitHub yields six fields: goal, files in scope, out of scope, constraints, done when, and report back. If you add only one, prioritize "done when" — a runnable command that lets the agent self-verify. A full template is provided for direct copy-paste, with a login-bug example filled in. The article closes with a reminder: briefs are advisory constraints and still need post-hoc checks like git diff, and short tasks can omit fields as appropriate.