The AI Isn't Following Your Instructions: How to Write Briefs Agents Actually Follow

A brief that agents follow reliably has four parts: the goal, the constraints, the definition of done, and the things you are deliberately not asking for. Missing any one of them is where drift enters. Goal. One sentence, in user terms. "A user can filter the job list by status." Not "add filtering", which says nothing about what is being filtered or by whom. Constraints. The decisions you have already made and do not want reopened. "Use the existing status field. Do not add a new table. Match the styling of the existing search box." Definition of done. The test you will run. "Done means: I select 'booked', the list shows only booked jobs, and the selection survives a page refresh." This is the single highest-value line in the brief, because it gives the agent a target it can check itself against. Non-goals. "Do not add sorting. Do not touch the create form. Do not refactor the list component." That structure takes ninety seconds to write and removes most of the guessing. The definition of done does the heaviest lifting: a brief without one is a brief where you and the agent can disagree about whether the work is finished.

Agents neglect parts of multi-part instructions, so stop giving them. If your message contains the word "and" between two features, split it into two messages. The failure mode named in the survey, "it focuses on one task while neglecting another", is predictable. When an instruction has four requirements, the agent works through them in order and quality degrades down the list. The fourth item gets a token effort or gets forgotten. Compare these two approaches to the same work: Bundled: "Add filtering by status, sort by date, a loading spinner, and fix the mobile layout." You will get good filtering, adequate sorting, a spinner in the wrong place, and no mobile fix. Sequenced: four messages, each with its own definition of done, each committed when it works. You get four working features, and when one breaks you know exactly which change caused it. Sequencing is slower per message and faster per working feature, which is the only speed that counts. It also makes debugging tractable, because each commit isolates one change. The habit to build: before sending an instruction, count the deliverables in it. More than one, split it.

Agents match patterns far better than they interpret adjectives. Replace descriptive words with concrete examples and output quality jumps immediately. "Make it look clean and professional" gives the agent nothing to match. It will pick a default, and the default will not be what you pictured. Instead, point at something: "Style this like the existing pricing card in components/PricingCard.tsx." Now there is a reference in your own codebase, and matching an existing pattern is what agents are best at. The same principle applies to data and behaviour: - Instead of "validate the input properly", give examples: "Reject an empty name. Reject a phone number with letters. Accept '+61 400 000 000'." - Instead of "handle errors gracefully", give the exact behaviour: "On failure, keep the form filled, show the error message above the submit button, and let them retry." - Instead of "format the date nicely", give the format: "25/07/2026". For anything visual, a screenshot is worth several paragraphs. Paste in the thing you want it to look like, or the thing that is currently broken. A useful check before sending: scan your instruction for adjectives. Every adjective is a decision you have delegated to the agent. Some of them you are happy to delegate. The ones you are not should become examples.

Ask for the plan before the code. If the agent's understanding is wrong, you find out in thirty seconds instead of after it has edited nine files. The instruction: "Before writing any code, tell me what you understand the goal to be, which files you will change, and what done looks like. Wait for my confirmation." What comes back is a readable summary you can check against the picture in your head. Three things to look for: - A goal that does not match yours. This is the cheap catch, and the one that saves the most time. - Files you did not expect. A styling task that plans to edit the database layer has misunderstood something. - Assumptions stated as fact. "I will add a new status column" when you already have one. Correct it now, not after. This also surfaces the decisions you left open. When the plan says "I will default the filter to showing all jobs", you get to say yes or no to a choice you never thought about. That is the ambiguity you could not see in your own instruction, made visible. One registrant summarised what they wanted to learn as providing "better instructions for agents". The plan-back loop is how you learn it faster: every mismatch between your intent and the agent's summary is a lesson about which words in your brief were doing less work than you thought. This loop is taught explicitly in buildAcademy, because it is the fastest route from vague prompting to reliable output.

Are longer prompts better? No. Precise prompts are better. A three-line brief with a definition of done beats three paragraphs of description, because length adds instructions the agent must balance rather than decisions it must respect. Should I keep a standing instructions file? Yes. A project file holding your stack, conventions and standing rules ("never add dependencies without asking") saves repeating yourself and keeps output consistent across conversations. Why does it ignore an instruction I gave earlier in the conversation? Earlier instructions carry less weight as a conversation grows. Restate the constraints that matter each time the task changes, or put them in a project file the agent reads every time. What do I do when it confidently does the wrong thing? Roll back rather than correcting forward. Then re-brief with the specific ambiguity closed. Correcting a wrong implementation usually produces a worse result than rebuilding from a clear brief. How do I write a definition of done for something visual? Describe the test as a user action plus an observable result: "On a phone-width screen, the filter dropdown is visible without horizontal scrolling." If you cannot check it by looking, it is not a definition of done.