A brief for the agent: how to turn an idea into a task

Two requests to the agent, one after the other. The first: "build the page from the brief in BRIEF_LANDING.md". A few minutes later index.html shows up in the folder, and it looks the way it was meant to. The second, the same evening: "build a 2048 game". And here the agent either asks five questions in a row or quietly builds a 5×5 board with an undo button nobody asked for.

The difference isn't in the agent. The difference is in what it was given. In this article we go through what a brief for a small task is made of, where to get the substance that goes into it, what to do when all you know is the direction, and why after "done" you check the result against the same lines you wrote before you started.

1. An idea is not a task yet

"I want 2048". "Make a nice page". "Make a new game, something more interesting". All of these are ideas, and they share one problem: you have a whole picture in your head, but only two words in the text. The agent sees only the text.

When there's a gap in the request, the agent has two paths. The first is to ask. The second is to fill it in itself: pick a board size, invent a rule, add a button. The second path is quieter, and that makes it more dangerous. you won't notice that a decision was made for you until you see the result. Every gap in the request is a decision somebody will make, and by default that somebody isn't you.

"Everyone knows how to play 2048" - that lives in your head. The agent doesn't read "everyone knows". What board? Where do new tiles come from, and when? Which ones merge, and into what? When is it a win, when is it over? For you it's one word; for the agent it's a blank until it's broken down into rules. In the chat it looks like this:

You:   build a 2048 game
Agent: A few things to clarify before I start:
       1. What board size, 4×4?
       2. What counts as a win?
       3. Do you need undo?

That's the good outcome. There's another one, for the same request:

You:   build a 2048 game
Agent: Done. The game is in index.html:
       - 5×5 board
       - undo button for the last move
       - high score table in localStorage

That isn't the agent's mistake. That's three of your gaps, filled without you.

This is the path from an idea to a result you can trust. The article follows it left to right. And the last step loops back to the third: you check, find a hole, add a line to the brief and hand it to the agent again.

2. Where the substance comes from

The agent builds the skeleton of a page or a game in minutes, and honestly that isn't the hard part. The hard part is knowing what should be on the page and what game we're even playing. None of that is in the code. It's in people's heads, sometimes in your own, and the agent knows a thing or two as well. You get it out by asking, and there are three sources: people, yourself, and the agent.

People means whoever ordered the thing and whoever will use it. Questions to them are best sent in a batch. A list of five or six items at once, not one question a day. A batch looks pushy, I know. In practice it saves everyone a week of back-and-forth.

When the customer is you (your own game, your own page), you ask yourself, and the big temptation here is to answer "well, that's obvious". The obvious gets written down the same way as the non-obvious. "4×4 board" takes two seconds to write, and for the agent those two seconds settle a whole fork in the road.

The third source is the agent, and there's a trap here worth knowing about in advance: you can't ask about what you don't know. Does a move that shifted nothing count as a move? Do you need swipes on a phone? Should the score be shown? These questions don't come to mind until the game is in front of you. The agent, though, has seen a thousand games like this and knows where people usually trip up. So instead of "build" it's sometimes more useful to start with "let's talk it through":

I want to build a 2048 game in the browser. Don't write anything yet.
Ask me the questions you can't start without. All at once, as a list.
I'll answer, and then we'll put the brief together in BRIEF_2048.md.

Two rules for a conversation like this, otherwise it never ends. First: the discussion is over when the four pillars from the next section are filled in, and its outcome is a file, not a chat. Second: the agent's questions are options, not requirements. It will happily ask "and are we doing a high score table?", and "no" is a perfectly good answer. That "no" is also a line in the brief, just under "not doing".

And either way - whether you asked or the agent did - the answer gets written into the brief file rather than left as a line in the chat. Otherwise the next request starts from the same hole.

Three sources on the left, one destination on the right. The dashed arrow going down is the path answers take most often: they stay in the chat, and ten messages later they're nowhere to be found. The arrow is on the diagram; a file at the end of it isn't.

You can ask the agent for more: not just to ask questions, but to draft the brief itself from your answers, filling in what you didn't say. What to do with the parts it made up is in section 4. First, what a brief is made of.

3. Four pillars of a brief

For a small task, a brief is six to eight lines. They rest on four pillars: the goal, what should happen, what the first version won't have, how we'll check it. Here it is in full, for the game:

# Brief: 2048

GOAL:      a 2048 game in the browser, opens from a file, nothing to install.
           HTML, CSS and JavaScript, no build step

RULES:     4×4 board
           at start and after every move a new tile appears: a 2 or a 4
           arrow keys slide all tiles in one direction, as far as they go
           two identical tiles that collide merge into one tile worth their sum
           win: a 2048 tile appears on the board
           loss: no moves left, the board is full, nothing to merge

NOT DOING: high score table, animations, undo

CHECK:     open index.html in the browser, see the board and the starting tiles
           make three moves with the arrow keys, a new tile appears after each
           bring two 2s together, get a 4
           play to the end, see the loss screen

Now one pillar at a time, each shown on two examples: the game and an invitation page for a board game club meetup.

Goal

The first line. Reading it, a person should picture the result, not the code. "A 2048 game in the browser, opens from a file, nothing to install". "An invitation page for a club meetup: a person understands what the meetup is and signs up with a button".

A check for the goal: if, reading it, you see code rather than what a person will see, it isn't a goal. "Write a tile merge function" isn't a goal; it's a piece of the work.

This is also where one line says "what we build with": HTML, CSS and JavaScript, no build step. Without that line the agent picks for itself, and there's no guarantee it picks something you know how to run.

And "make it nice" can't be a goal. Nice for whom, and where would you see it.

What should happen

The longest pillar, and for the game it's already written above. There's one rule: a line is good if, after launch, you can look at it and say "yes" or "no". "4×4 board" - yes or no. "Two identical tiles merge into one tile worth their sum" - yes or no. "More interesting" - neither yes nor no, and a line like that has no place in a brief.

One thought per line. "Tiles appear and merge" is two checks, so it's two lines.

For the page it's the same, only instead of rules it's what's on it: "a header with the name and the date", "three blocks: what happens, who it's for, where", "the Sign up button links to the form". Each one you can open and see.

A list like that looks dull next to the idea. Dull is exactly the point. dull can be checked.

What the first version will not have

The one pillar people usually forget, which makes it the most valuable. The agent fills a gap on its own, and most readily by adding something. A high score table, tile animation, an undo button, a dark theme. All of it useful, and none of it something you asked for.

Spell it out item by item. Not "nothing extra" - that's a wish, not a boundary - but "not doing: high score table, animations, undo". For the page: "not doing: the sign-up form itself, payment, a photo gallery". Three items are usually enough; nobody's going to write ten anyway.

Why this is for you, not for the agent. The less gets built, the less there is to check. And the clearer it is where the thing that broke came from: six lines are easier to search than six screens. A sign that there's no boundary: the phrase "while we're at it" starts showing up in your request or in the agent's reply.

How we will check it

Every line under "what should happen" is one check after the agent says "done". Open the game - 4×4 board, yes. Press an arrow - the tiles slide, a new one appears, yes. Bring two 2s together - a 4, yes. You don't write the list of checks separately; it's already written.

Plus two or three "check" lines in the brief itself: what exactly to do by hand. "Open the file in the browser, make three moves, play until you lose". These lines are written before the request, not after. After the result they quietly get bent to fit whatever came out - it happens by itself, and it'll happen to you too.

"Done" from the agent is a line in the chat, not a check. The check is yours, against your lines.

Now some practice. Take the request "make a nice page for the board game club meetup" and break it down into the four pillars, a line or two for each. The answer is right below; compare:

# Brief: invitation page

GOAL:        an invitation page for a board game club meetup:
             a person understands what the meetup is, when and where, and signs up with a button.
             one HTML file, styles inside

ON THE PAGE: a header with the club name and the meetup date
             three blocks: what happens, who it is for, where
             the "Sign up" button links to the form

NOT DOING:   the sign-up form itself, payment, a photo gallery

CHECK:       open in the browser, see the header and the three blocks
             press the button, land on the form

Notice that the word "nice" didn't make it into the brief at all. It can't be checked. If looks really matter, they get broken down into lines like everything else: "one picture in the header", "no more than two colors", "everything fits on a phone screen". That you can open and look at.

The block names differ between the two examples: "rules" for the game, "on the page" for the page. That doesn't matter; call them whatever suits you. What matters is that each has the four pillars:

4. Whose decision is this

Decisions nobody signed off on end up in the brief, and it happens in two ways. First: you let the agent fill the holes with "something reasonable" so you get a draft now instead of waiting for answers until Tuesday. Second: you decided for the customer yourself, because there was nobody to ask, or no time to.

Both cases are fine. What isn't fine is forgetting that it was an assumption. A week later nobody will remember who came up with the button going to an email address instead of the form, and that's exactly what the argument will be about.

For the first case, the request to the agent looks like this:

Put together a draft brief for the invitation page from these answers.
Where an answer is missing, pick something reasonable and list
separately what you made up yourself. Save it to BRIEF_INVITE.md.

Read the list of made-up parts first, before the brief itself. These are decisions made for you: each one either goes to whoever knows the subject for approval, or stays in the brief, flagged.

For the second case, a flag in the file itself. The word "assumption:" before the decision, or just a question mark at the end of the line: "the button goes to the club's email (?)". When the answer arrives, you can see right away what to change. and there's no need to remember where it came from.

The flag works both ways. An agent handed a brief with question marks in it usually asks about them first thing: they mean the same thing to it as they do to you.

5. A sandbox instead of questions

Sometimes the four pillars just won't get written, however long you sit there. "I want something like 2048, but I don't know if it needs a score, if it needs swipes, or if it's even 4×4". That isn't a brief, and not even an idea in the usual sense. It's a direction: which way is clear, what comes out isn't. Questions don't help here: neither you nor the customer has the answers yet, and you have nothing to compare the agent's options against.

In that case the cheapest thing is to look. Build a sandbox: the simplest version you can look at and poke at, to figure out what you actually want. With an agent that costs ten minutes, and at that price it's no loss to throw the result away.

A sandbox is also a brief on four pillars, only its goal is different:

# Brief: 2048 sandbox

GOAL:      see how 2048 plays in the browser and figure out what I want.
           HTML, CSS and JavaScript, no build step

RULES:     4×4 board
           arrow keys slide the tiles, identical ones merge
           a new tile appears after a move

NOT DOING: everything else: win, loss, score, swipes, styling

CHECK:     play for five minutes and write down what is missing and what is extra

Look at what changed. The goal isn't a game but understanding. "Not doing" is the longest line; it holds everything you're not sure about. And the check isn't "does it work" but "what do I know now". Play for five minutes - and the questions you couldn't ask at the start show up on their own: swipes aren't needed, on a computer you play with the arrow keys; a score is needed, it's boring without one; 4×4 is too small, you want to try 5×5; the loss has to be shown, otherwise it isn't clear the game is over.

That's the result of the sandbox. Not code, answers. You write the real brief from them, and the game gets built from scratch, in a clean folder, with one phrase: "build the game from the brief in the file". The sandbox has done its job.

This is the same chain as in the first section, only the "Questions" step has been replaced by a loop: when there's nothing to ask about, first we look, then we write it down. Only one thing goes down into the brief - answers. The sandbox has no arrow to the agent, and that isn't an oversight: the agent builds the real version in a clean folder, from scratch. from there it's the chain as before.

6. The brief lives in a file

Why a file and not the chat. The chat gets lost: ten messages later the rule about merging tiles is nowhere to be found. A file sits in the project folder next to the code, the agent reads it itself when you point at it, and you can fix it and hand it over again with the same phrase. Any name will do: BRIEF_2048.md, BRIEF_LANDING.md, even task.txt. It's a plain text file; there's no particular format to it.

You hand it over with one phrase. Compare:

Before: "build a 2048 game, you know the one, something more interesting".

After: "build the game from the brief in BRIEF_2048.md".

The second request is shorter than the first, and it carries ten times more information - it's in the file. No need to paste the brief into the chat; the agent will open the file itself.

What to change in the file and what to say in words. The rule of thumb: a rule or a boundary changed - edit the file and hand it over again ("win at 2048, not at 1024" goes in the file). A small visual detail changed that doesn't affect the rules - words are fine ("make the button blue"). Not sure - put it in the file: an extra line is cheaper than a forgotten rule.

About size. For a small task it's six to eight lines, like the 2048 block above. If a brief for a one-evening game has stretched to two pages, most likely it picked up things that should have gone under "not doing".

One last thing before you hand the file to the agent: read it once as if someone else wrote it. A line that can't be checked turns up almost every time. it does for me.

7. What the agent does with the brief and what stays with you

Let's put it all in one picture: what Claude Code does in this setup and what stays on your side. In pairs.

The point of a brief isn't for the agent to understand. It will build something from two words anyway. The point is for you to know what you ordered, and to be able to check it.