A useful coding-agent brief states the behavior to change, the boundary of the work, and the evidence needed to judge the patch. Another developer should be able to read it and understand the same task without reconstructing a long conversation.
Keep the brief compact enough to scan. Include the failure, relevant files, preserved contracts, acceptance cases, verification approach, and stop conditions. Replace broad instructions such as “make it robust” with observable outcomes.
Describe the failure before prescribing a repair
“Fix profile validation” leaves too much open. A more useful starting point is: “A user can remove a required phone number and still save the profile.” That names an action and an incorrect result.
Record how to reproduce the failure, what should happen, and what actually happens. Include the relevant fixture or account conditions. Separate facts from hypotheses: a missing server check may explain the symptom, but the brief should not assume that explanation before inspection.
When the defect cannot be reproduced, say so. A mitigation can still be useful, but describe its evidence and limitations accurately. Assign the follow-up that will determine whether it resolves the reported failure.
Name the smallest useful context
Provide the code and examples needed to follow the behavior across its boundary. For the profile case, that may be the form, API handler, and shared validator. Include the current error contract or an example of how another required field is rejected.
Avoid a repository tour that buries the relevant path. State which modules can change and which are read-only. If the repair appears to require a different layer, define when the agent should stop and report the dependency.
A changed-files boundary also gives the reviewer a quick check against scope drift. It does not establish correctness by itself; a patch can stay inside the permitted files and still change the wrong behavior.
Use an acceptance block with adverse and valid cases
Here is a compact brief for the profile scenario:
Goal
Reject profile saves when the required phone number is removed.
Read and edit
web/ProfileForm.tsx
api/profile.ts
validators/profile.ts
Relevant profile tests.
Preserve
Existing phone-format rules and unrelated profile behavior.
Confirm the API's existing required-field error contract.
Acceptance
Client: clear phone and save. Show the required-field message;
send no save request.
Server: submit directly with phone missing. Reject the request;
leave the stored profile unchanged.
Valid: an unchanged profile with a valid phone still saves.
Verify
Find the repository's focused profile test command and confirm
it selects the intended tests. For a reproducible defect, show
the relevant check failing before the repair and passing after.
Record actual results and any checks that could not run.
Stop
Ask if phone required-ness differs by account type, or the fix
needs changes outside the named boundary.
Return
Changed files, review notes, observed checks, and remaining risk.
The profile-change owner confirms all three acceptance routes
before merge. Report a blocker if any route remains unverified.
This brief specifies intended behavior. It does not claim the checks have run or that a patch exists.
The direct server request matters because a browser rule can be bypassed. The valid-save case matters because rejecting every request would satisfy an overly narrow “reject empty phone” check while breaking the feature.
Preserve contracts explicitly
List the existing behaviors most likely to be damaged by the repair. For a validation change, required-field handling and format rules are separate concerns. For an API change, the contract may include null behavior, empty collections, errors, ordering, and legacy cases.
Give concrete examples when a client depends on a subtle rule. Confirm the existing response shape and error handling rather than choosing a new status code merely because it seems conventional.
Keep implementation freedom where it is useful. Acceptance criteria should describe what callers or users observe. A brief that dictates every helper call can encourage tests that mirror the implementation while missing the actual failure.
Specify verification without inventing commands
Use the repository’s real scripts and runner options. A command that exits successfully may still select no relevant tests or ignore the intended filter. Confirm which checks ran and inspect their outcomes.
The proof should match the changed behavior. A form repair needs evidence for the relevant interaction and server boundary. A visual change may require screenshots at the reported viewport and locale. A change to payment state needs a different set of checks.
Ask the returned summary to distinguish observed results from proposed follow-ups. “The server case remains unchecked because the test environment is unavailable” is a useful limitation. It leaves a clear next action and avoids treating a plan as execution evidence.
Treat scope and permissions as separate controls
A written “do not modify” list helps guide work and review. Restrict actual filesystem, tool, network, and credential access to match the task as well. A prohibition in prose does not enforce access control.
Treat instructions embedded in ticket comments or other task material as untrusted unless an authorized person adopts them. A comment asking for secrets or an unrelated command does not expand the assignment.
Before editing begins, ask for a short statement of assumptions and the planned review path. If the work drifts, stop, preserve any useful clean reproduction, and narrow the brief. The final handoff should make the owner’s next decision straightforward: accept the evidenced change, request specific missing proof, or resolve a named ambiguity.
The Agentic Developer Interview includes practice cards on context packets, one-screen briefs, boundary maps, and written brief reviews.
The Kindle edition is free from 23 to 25 October 2026 (US Pacific time).