AI Coding Session Brief

Picture Maya typing "add pagination to the orders endpoint" and letting an agent run. The assistant picks offset pagination, because that pattern appears most often in its training and nothing in the prompt steered it elsewhere. Ten minutes later there is a clean diff across the handler, the query layer, two tests, and the API docs. It looks finished. Only in review does the problem surface: this orders table is append-heavy, so offset pagination skips and repeats rows under concurrent inserts. The right shape was a cursor, a different design entirely. Now Maya is unwinding a confident, well-formatted diff instead of correcting one sentence before any code ran.

The brief is the cheap version of that correction. A sentence in the Constraints field, "the table is append-heavy, use a cursor," steers the whole session before the first edit. The assistant carries the constraint through the implementation rather than fighting it afterward. The cost is a minute of writing; the saving is an hour of review-time archaeology.

There is a second reason to scope tightly, and it is measurable. Reviewers catch defects on small, focused changes and miss them on large ones. SmartBear's classic peer-review research found defect-detection ability falls off sharply past 400 lines of code in one sitting, and more recent analyses of large pull-request datasets put detection near 87% for changes under 100 lines and around 28% for changes over 1,000 lines. A brief that names three files and one behavior tends to produce a diff a human can actually read. A vague prompt tends to produce a sprawling one nobody reviews properly. The brief is upstream of review quality: scope the session small and the diff is reviewable; let it sprawl and the review becomes a rubber stamp.

Claude Code's own guidance lands in the same place. Its rule of thumb is blunt: if you could describe the diff in one sentence, skip the plan and just ask. Everything above that line, multi-file work, an unfamiliar area, a real failure mode, is exactly where a written brief earns its minute. The brief is how you decide which side of that line you are on before you start.

Each field does one job, and the difference between a strong entry and a weak one is whether it gives the assistant something concrete to be steered by. Work through them in order.

• Goal. State the behavior that changes, as an outcome. Strong: "GET /api/orders returns cursor-paginated results; existing offset callers keep working during the transition." Weak: "improve the orders endpoint." The weak version is the request with a future tense; there is nothing in it a finished diff can be checked against.
• Files in play. Name them. Strong: "src/api/orders.ts, src/db/orders.ts, tests/orders.test.ts." Weak: "the API layer." Naming files does two things at once: it points the assistant at the right code and it makes any edit outside that list visible the instant it appears in the diff.
• Out of scope. This is the field most people skip and most regret. Strong: "no caching layer, no new dependency, no change to the response schema." Weak: leaving it blank. Agents tend to propose more than you asked, an extra abstraction, a refactor "while we are here," a library. Writing the fence costs one line here; arguing about it in review costs a meeting.
• Constraints. The rules that must hold no matter the approach. Strong: "keep the offset path working; invalid cursor throws rather than returning a partial page; no breaking change to the public signature." Weak: "do it the right way." A constraint the assistant cannot violate is worth more than a preference it can interpret.
• Risks and Edge cases. Strong risk: "append-heavy table, so offset pagination skips and repeats rows under concurrent inserts." Strong edge cases: "empty page, last partial page, invalid cursor, duplicate at the boundary." Weak: "handle errors." Naming the four inputs the happy path skips is what turns "it works" into "it works on the cases that actually break."
• Done means. Make it checkable. Strong: "build green, existing tests pass, four new tests cover the edge cases above, empty and last-page cases verified by hand." Weak: "it works." Claude Code's strongest single recommendation is to give the assistant a check it can run, a test suite, a build, a script, so the loop closes on its own instead of waiting for you to notice each mistake. The Done means field is where you write that check down.

The How it will run and Context to attach fields connect the brief to the session. For run, decide whether to start in plan mode (multi-file or risky) or go direct (small and clear). In Claude Code that is Shift+Tab to enter plan mode and Ctrl+G to open the draft plan in your editor, where you delete the caching step the assistant added and add the line "do not add caching, out of scope." For context, list the files, the failing test, and the project rule to attach, the same rules you would keep in a CLAUDE.md the assistant reads every session.

A brief can look complete while leaving the real work undone. Watch for these.

• The restated task. If your Goal and Constraints are the request reworded, the brief protects nothing. The test is simple: can you find a sentence in it the assistant could get wrong? If not, it is too vague to steer anything.
• The empty fence. A blank Out of scope is the most common way a session sprawls. Name the additions you do not want, even when they seem obvious, because the assistant does not share your sense of what is obvious.
• "Done" with no check. "It works" is not a finish line an assistant can run against. Without a build, a test, or a manual case in Done means, you become the verification loop and every missed edge case waits for you to spot it in review.
• The hallucinated dependency. A real, current risk worth a line in Constraints. A USENIX Security 2025 study of 576,000 code samples across 16 models found 19.7% of suggested packages did not exist, over 200,000 unique fabricated names, and the same fake names recur: 43% reappeared on all ten runs of an identical prompt. Attackers pre-register those names, a practice now called slopsquatting. "No new dependency without asking" in your brief turns an install you would have skimmed into a decision you make on purpose.
• The brief that never gets revisited. The brief is also a review instrument. When the diff returns, read it against Out of scope and Done means: those two fields catch the change that scoped up and the one that stopped short.

On a team the brief earns a second life. Drop the filled-in version at the top of the pull request and the next reviewer knows the intended behavior, the fence, and what was checked before they read a single hunk, which is exactly the context a 140-line diff otherwise hides. A shared brief template also keeps a team honest about scope: when every change ships with a named goal and an out-of-scope line, the 900-line pull request that touches everything stops looking normal. Priya, leading the team, can read ten briefs faster than ten diffs and see at a glance which sessions were scoped and which were a hope.

Use the brief as the first link in a short chain. The AI Use Case Canvas decides whether the work is worth doing; this brief scopes the coding session; the AI Code Review Checklist and the Reviewing AI Code Safely guide check the diff it produces against the very fields you wrote here. On your next real change, before you type a prompt, fill in just three lines, Goal, Out of scope, and Done means, and you will already be ahead of the version of you that started typing.