The brief

What you tell an agent before it starts: what to build, why, what counts as finished, and whatever it couldn't work out by itself. It can be one sentence or a page. Anything it leaves out, the agent decides for you.

A colleague asks when a request is unclear. A model usually picks an answer, writes working code for it and reports success, so you learn what it chose only by reading the result. The brief is the cheapest moment to make those choices yourself.

A written description of what something must do, exact enough that two people, or two agents, would build the same behaviour from it. It says what and why, and usually leaves how to the builder.

A session forgets. A spec in the repo lets the next session, a reviewer and a second agent all hold the work to the same thing, and you can read it before any code exists. The price is that it is one more thing that can be wrong, and nothing tells you when it is.

One thing the result must do, stated so that someone could check it. "apply ignores an event older than the newest one for that order" is a requirement. "Handle events properly" is a wish.

An agent reads a wish as permission to decide. But plenty of real requirements change nothing either: on payment-events, every vague attempt dropped repeated events without being told. Spend your words on what the model wouldn't have done by itself.

The specific checks that decide whether this piece of work is finished, agreed before it starts. Each one passes or fails. The best are written so that a program can run them.

An agent's own tests check what it built, not what you needed. Of the 11 broken vague attempts in our runs, 9 passed every test they wrote for themselves. Criteria written before the code, by someone who knows the job, can't be shaped by the code.

The list that must be true before anything counts as finished, on every task: say the code type-checks, the tests pass and the docs are updated. You write it once, and it applies to all the work.

An agent stops when the work looks done to it. A written definition gives it something to run in place of that feeling. It only rejects what it names, though. The bench below shows how far a general list gets you when nobody asked for the behaviour that was missing.

The edges of the job: which files, features and behaviours this task may change, and which it may not. One line of scope can save a long review.

Agents overshoot and undershoot, and you pay either way: too much is a diff you must read, too little is a follow-up. They can't tell how much you were hoping for. So say it, with something you can check, such as a folder and a rough size.

Something that could reasonably be a goal and that you have chosen not to pursue this time. "No offline mode in this version" is a non-goal. "It shouldn't crash" isn't, because nobody was ever going to want crashes.

An agent reads a gap as room to build. Naming the reasonable thing you are leaving out stops it being built, spares you reviewing it, and tells the next person it was a decision and not something you forgot.

An input at the limit of what a program expects: nothing at all, exactly one, zero, the largest allowed, the same thing twice, things in the wrong order. Bugs gather here because the usual case is what everybody pictures.

Models handle the edges everyone has heard of and miss the ones particular to your domain. In our runs all 15 vague attempts handled a repeated webhook, and 11 of 15 got an old event arriving after a newer one wrong. Listing the edges costs one sentence.

A limit on how the job may be done, rather than on what it must do: no new libraries, under 200 milliseconds, use the database we already have.

An agent takes whichever route looks most natural, and it has no idea what your project ruled out last year. Constraints are cheap to state and expensive to discover during review. Once one matters twice, turn it into a check.

Showing what you want with concrete inputs and the results they must give, in place of or beside a description. A good one settles what a paragraph leaves open, and it is hard to read two ways.

Examples are direct, but most of them rule out very little. "Jan 15 gives Feb 15" leaves wrong programs standing that "Jan 31 gives Feb 28" removes at once. The useful ones sit at the edges, so you have to know where the edges are.

A sentence that can honestly be read more than one way. A model rarely stops to ask which you meant. It picks a reading and writes working code for it, so nothing looks wrong.

Between people, ambiguity comes back as a question. From an agent it comes back as behaviour. "Updates an order's status" gave us three kinds of program. All of them type-check, and they agree on the obvious cases, so nothing tells you a choice was made.

Instead of writing the brief yourself, you ask the agent to question you until it could write it. It finds the decisions you hadn't noticed you were making.

You can't list what you haven't thought of. A model has read a great many specs for this kind of feature, so it is good at what must be decided and knows nothing about your answers. That split is the useful part: it brings the list, you bring the choices.

The steps an agent intends to take, written before it takes them: which files, in what order, what it will check, and what it isn't sure about.

It is the cheapest place to find out the agent misunderstood you. It is also a guess that nothing has tested yet, and polishing one can feel like progress while no knowledge is being added. Skip it when the change is small and the approach is obvious.

A plan saved as a file in the repo, with steps that get ticked off, so that it survives the session. A later agent can pick it up, and a reviewer can see what was meant.

A plan in a chat disappears with the chat. In a file, it carries work across sessions and makes drift visible. The hazard is the same as any document: a stale plan gets read as truth, so it has to change when reality does.

Working so that the spec comes first and stays the main thing: you write and review the spec, and agents produce the code from it. How far this goes varies, from a spec for one task to a spec that replaces code as what you edit.

It answers a real problem. Code is cheap, intent gets lost, and agents write more than anyone can read, so a spec gives you something smaller to check. The bill is long documents to review, and an agent that may still ignore them.

The opposite position: write code early, because code that runs answers questions a document can only guess at. A working version or a prototype becomes the description of what you want, and anything written comes after.

Our reading, and only ours: code wins when running it shows you the answer, one person is deciding, and throwing it away is cheap. A written spec wins when being wrong won't show up on a run, as with money, when several agents must build to one thing, or when nobody will read the code.

A small piece of a feature that goes through every layer, from what the user sees down to where the data is kept, so it works end to end even though it does very little.

An agent can write a whole layer confidently, and the mismatches only appear where layers meet, by which time a lot is resting on a guess. A slice gives it something real to run and check within the first hour.

Splitting a big job into pieces small enough to be done and checked alone, in an order where each piece builds on something already known to work.

Given everything at once, an agent can run out of room halfway and leave the next session a half-built feature. With small pieces, a break shows up at the piece that caused it. Too small has a cost as well, because every piece has its own overhead.

Start a new session for each separate job, so one job's leftovers don't end up steering, or being paid for by, the next.

The whole conversation goes back on every request, wrong turns included. Three old jobs are three jobs you are still paying to re-read, and three sets of assumptions still in the room. Anything worth keeping goes in a file first.

A small throwaway program written to answer one question, such as whether a library can do something or how a function really behaves. You keep the answer and delete the code.

Agents make these nearly free, so there is little reason to argue about something you could run in a minute. The usual failure is the spike's rough code quietly becoming the real code, so say at the start that it will be deleted.

Get one agent doing one hard thing well, with real understanding and real checks, before you run several at once. A setup you can't trust with one agent gives you ten times the mess with ten.

Parallel agents multiply whatever you already have, and your ability to review doesn't multiply with them. The first deep run also teaches you what the checks and the brief need to say, which is what makes the later ones safe to leave alone.

A quick version built to help you decide something, such as which layout or how an interaction should feel. It is meant to be thrown away, and the real one gets built properly afterwards.

Agents make these so cheap that you can see three before choosing. That speed sharpens the old danger, because a prototype looks finished. Vibe coding one is fine. Keeping it, and adding real users, is the mistake.

One short sentence about who wants something and why, usually written "As a [someone], I want [something], so that [reason]." It starts a conversation and isn't meant to be the whole spec.

For an agent, the useful part is "so that". The reason lets it make sensible choices where your brief runs out. Generated in bulk they are padding: a story that says what the code does, with no real person in it, tells nobody anything.

A rule the agent can check that says when to stop: these commands exit 0, or this many tries have been used. It stands in for the agent's own feeling that it has finished.

With no one watching, it needs two things: a way to succeed, and a limit for when it can't. Without the first it stops when things look done. Without the second it can spend all night on one failure. In our recordings, 1 of 40 loops never passed.

A rule for the agent: when the answer changes what gets built and it can't find out for itself, stop and ask instead of quietly picking. People disagree about how often that should be.

Each silent guess is a decision you never saw. Each question stops you, and stops a long run dead. Both are real costs, and what settles it is mostly how hard the guess is to undo. If it's reversible, proceed and report. If it isn't, ask.

Using the exact term of the trade instead of a description: "idempotent" for "handles repeats okay", "debounce" for "waits until I stop typing". One word can carry a set of requirements you would otherwise have to spell out, if you know it.

A term points at everything a model has read about it, and you need the name more than the fix. But our worded briefs used the term and stated the rules, so we can't say how much the word alone did. And it is only useful if you can check the result, which means knowing what the word means.