How do you brief a coding agent to get one working feature?
Say what it is, say what it is not, name the example to copy. Three sentences beats three paragraphs, and over-specifying makes the result worse.
How do you brief a coding agent to get one working feature?
Three sentences: what the thing is, what it is explicitly not, and which existing example to copy. Everything else should already live in the codebase, and if it does not, the fix is to put it there rather than to write a longer prompt. Long briefs feel thorough and mostly produce features with parts nobody wanted.
The three-sentence brief
Here is a complete, real one:
Add a Bookmarks feature: a url, a title, and an optional note.
No tags, no folders, no search yet.
Follow the shape of the example slice, and put it behind the paywall.
Sentence one is the thing. Sentence two is the boundary. Sentence three points at a template and makes the one product decision the agent cannot infer.
That is enough to get back a model, a migration, permission rules, a controller, screens, routes, and tests, all consistent with everything else in the codebase.
Why sentence two matters most
"No tags, no folders, no search yet" is the highest-value line in that prompt, and it is the one people never write.
Given an under-specified request, an agent does not stop and ask. It fills the gap with reasonable defaults, and reasonable defaults for "bookmarks" include tags, folders, search, import, and export, because that is what bookmarks usually have. Every one of those arrives as code you now own, maintain, test, and eventually remove.
Stating the boundary is cheaper than stating the contents. You can describe what you want in eight words; describing everything you do not want would take a page. So name the two or three obvious extensions and rule them out explicitly.
Why over-specifying makes it worse
The instinct after a bad result is to write a longer prompt. It usually makes things worse, for three reasons.
It competes with the codebase. If your guide file says one thing and your prompt implies another, you have created a conflict, and which one wins is not predictable.
It buries the important part. In a page of instructions, the one line that actually mattered gets the same weight as the rest.
It specifies the wrong layer. People over-specify implementation ("use a join table with a composite index") and under-specify product ("should two people be able to bookmark the same thing"). The implementation is the part the agent is good at. The product decisions are the part only you know, and they are what the brief should spend its words on.
Put the repeated parts in the codebase, not the prompt
If you find yourself typing the same instruction every time, that is a signal.
"Make sure it is scoped to the account, add permission checks, write tests, use the existing design classes" should not be in a prompt. It should be in the guide file, and it should be visible in the worked example the agent copies. Then it happens whether you remember to ask or not, which is the entire point.
A prompt is for what is different about this feature. Everything that is true of every feature belongs somewhere permanent.
Ask for a plan when the request is loose
For anything you cannot state in three sentences, spend one round on a plan:
Before writing code, tell me in five lines how you would add team invitations.
Five lines is enough to reveal a misunderstanding and cheap enough that you will actually read it. Catching a wrong assumption here costs seconds; catching it in a finished diff costs a rebuild.
Skip this for small, well-bounded work. Use it whenever the feature touches something that already exists.
What to review, in order
The reviewing habit matters more than the prompting habit, and there is an order that catches the most for the least reading:
- The migration. Schema is the most expensive thing to change once there is data.
- The permission rules. Deny by default, every query filtered to the current account.
- The lookups. A query through the model rather than through the current account is how one customer reads another's records, and the two lines look nearly identical.
- Everything else, quickly. Screens and copy are cheap to change and rarely dangerous.
The signal that your setup is wrong
If your briefs keep getting longer, the problem is not your prompting.
A prompt that has to explain your conventions means your conventions are not written down. A prompt that has to describe the shape of a feature means there is no example to point at. A prompt that has to say "and make sure it works" means there is no command that verifies.
Fix those three and the briefs get shorter on their own. That is the argument in how to write a guide file your agent will actually follow, and it is why the first run otherwise disappears into plumbing.
The one-line version
Say what it is. Say what it is not. Point at the example. Then read the migration and the permission rules properly, and skim the rest.
