The 4-part brief that keeps coding agents from drifting

Coding agents usually do not drift because they are incapable. They drift because the task leaves too much room for interpretation. A request like “clean up authentication” sounds clear to a human who already knows the codebase. To an agent, it can mean anything from renaming one helper to replacing the entire authentication stack. The fix is not a longer prompt. It is a brief with four explicit parts : Outcome Context Guardrails Definition of Done Below is the exact structure I use. 1. State the outcome as an observable change Describe what should be different for the user or system when the work is complete. Weak: Fix the login bug. Better: When a user submits an expired magic link, show the existing “Link expired” message and offer a button that requests a new link without leaving the page. The better version gives the agent a destination. It does not prescribe the implementation, but it makes success testable. 2. Give only the context that changes the decision Context is useful when it removes ambiguity. It becomes noise when it is a tour of the whole repository. Useful context often includes: The relevant entry point or route The existing component or service that should be reused A similar implementation elsewhere in the codebase The command used to run the relevant tests A known constraint, such as backwards compatibility Example: The page is implemented in app/auth/verify/page.tsx . Reuse requestMagicLink() from lib/auth/client.ts . The existing error-message styles live in components/auth/AuthNotice.tsx . That is enough to start investigating without pretending we already know the final patch. 3. Add guardrails that define the change boundary Guardrails prevent a small task from becoming an accidental rewrite. A useful set might be: Do not change the public API. Do not add dependencies. Keep the current visual design. Do not edit generated files. Limit changes to the authentication flow and its tests. If a database migration appears necessary, stop and expl