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 appears in the folder, and it looks exactly as intended. The second, the same evening: "build a 2048 game". This time the agent either asks five questions in a row or silently builds a 5×5 board with an undo button nobody asked for.

The difference isn't the agent. The difference is what it got as input. In this article we'll look at what a brief for a small task consists of, where to get the substance to put in it, what to do when all you have is a 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". These are all ideas, and they share the same problem: you have a whole picture in your head, but only a couple of words in the text. The agent sees only the text.

When a request has a gap, the agent can go two ways. One is to ask. The other is to fill the gap itself: choose a board size, make up a rule, add a button. The second way is quieter, which makes it more dangerous. you won't notice a decision was made for you until you see the result. Every gap in a request is a decision someone will make, and by default that someone isn't you.

"Everyone knows how to play 2048" - that's in your head. The agent can't read that "everyone knows". What board size? Where do new tiles come from, and when? Which tiles merge, and into what? When do you win, when is the game over? To you it's one word; to 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: Let me check a few things before I start:
       1. What board size, 4×4?
       2. What counts as a win?
       3. Do you need an undo?

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

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

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

That's the path from an idea to a result you can trust. The article follows it from left to right. And the last step leads back to the third one: you check, find a hole, add a line to the brief and give 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's not the hard part. The hard part is knowing what should be on the page and what game we're even playing. That isn't in the code. It's in people's heads, sometimes your own, and the agent knows a thing or two as well. You get it by asking questions, and there are three sources: other people, you, and the agent.

Other people means whoever ordered the thing and whoever is going to use it. It's better to send them your questions in one 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 the questions, and the big temptation is to answer "well, that's obvious". The obvious gets written down just like everything else. "4×4 board" takes two seconds to type, and for the agent those two seconds close off a whole fork in the road.

The third source is the agent, and there's a trap here worth knowing about up front: you can't ask about what you don't know. Does a move that didn't shift anything count as a move? Do you need swipe support on phones? Should the score be shown? These questions don't occur to you until the game is right in front of you. The agent, meanwhile, has seen a thousand games like this and knows where people usually stumble. So instead of "build it", it's sometimes more useful to start with "let's discuss":

I want to build a 2048 game for 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, or it never ends. First: the discussion is over when the four pillars from the next section are filled in, and what it produces is a file, not a chat. Second: the agent's questions are options, not requirements. It will gladly ask "should we add a high score table?", and "no" is a perfectly normal answer. That "no" is a line in the brief too, just under "not doing".

And either way - whether you asked or the agent did - the answer goes into the brief file instead of staying a message in the chat. Otherwise the next request starts with the same hole.

Three sources on the left, one destination on the right. The dashed arrow pointing down is the route answers take most often: they stay in the chat, and ten messages later you can't find them. The arrow is on the diagram, but there's no file at the end of it.

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

3. The 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, and how we'll check it. Here's the whole thing for the game:

# Brief: 2048

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

RULES:     4×4 board
           a new tile appears at the start and after every move: a 2 or a 4
           arrow keys move all tiles in one direction, as far as they go
           two equal tiles that collide merge into one with 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
           merge two 2s, get a 4
           play to the end, see the game over screen

Next, one pillar at a time, each illustrated with two tasks: the game and an invitation page for a board game club meetup.

Goal

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

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

This is also where one line on "what we build it with" goes: HTML, CSS and JavaScript, no build step. Without that line the agent will choose on its own, and it may well choose something you don't know how to run.

And "make it look 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 the result and say "yes" or "no". "4×4 board" - yes or no. "Two equal tiles merge into one with their sum" - yes or no. "More interesting" - neither yes nor no, and a line like that doesn't belong in a brief.

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

The page works the same way, except instead of rules you list what's on it: "a header with the name and the date", "three blocks: what's happening, who it's for, where", "the Sign up button leads to the form URL". You can open each one and see it.

A list like this looks dull next to the idea. Dull is exactly what you want. dull can be checked.

What the first version won't have

The one pillar people usually forget, and that's why it's the most valuable. The agent fills gaps on its own, and its favorite way is to add something. A high score table, tile animations, an undo button, a dark theme. All of it useful, and you asked for none of it.

Write it out by name. 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, payments, a photo gallery". Three names are usually enough; nobody is going to write ten anyway.

Why this matters to you rather than to the agent. The less gets built, the less there is to check. And when something breaks, it's easier to see where it came from: searching six lines is easier than searching six screens. A sign that the boundary is missing: the phrase "while we're at it" keeps showing up in your request or in the agent's reply.

How we'll 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 key - the tiles move, a new one appears, yes. Merge two 2s - you get a 4, yes. You don't write a separate list of checks; 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". You write these lines before the request, not after. Once the result is in, they quietly get adjusted to fit whatever came out - it just happens, and it will happen to you too.

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

Now for 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, so you can 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 included

ON THE PAGE: a header with the club name and the meetup date
             three blocks: what's happening, who it's for, where
             the "Sign up" button leads to the form URL

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

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

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 image in the header", "no more than two colors", "everything fits on a phone screen". Those 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; name them however you like. What matters is that each one has the four pillars:

4. Whose decision is it

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

Both are fine. What's not fine is forgetting that it's an assumption. A week later nobody will remember who decided the button goes 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 there's no answer, come up with something reasonable, and in a
separate list name everything you made up yourself. Save it to BRIEF_INVITE.md.

You read the list of made-up parts first, before the brief itself. These are decisions made for you: each one either goes for approval to someone who knows the subject, or stays in the brief with a flag.

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

The flag works both ways. An agent given a brief with question marks usually asks about them first: to it they're the same signal they are to you.

5. A sandbox instead of questions

Sometimes the four pillars just won't come, however long you sit over them. "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's not a brief, and not even an idea in the usual sense. It's a direction: you know which way to go, but not where you'll end up. Questions don't help here: neither you nor the customer has the answers yet, and you have nothing to compare the agent's suggestions against.

In that case, the cheapest thing is to take a look. Build a sandbox: the simplest version you can look at and poke around in to figure out what you actually want. With an agent that takes ten minutes, and for ten minutes of work, throwing the result away doesn't hurt.

A sandbox gets a four-pillar brief too, just with a different goal:

# 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 move the tiles, equal ones merge
           a new tile appears after each move

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

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

Look at what changed. The goal isn't a game, it's understanding. "Not doing" is the longest line; it holds everything you're unsure about. And the check isn't "does it work" but "what do I know now". Five minutes of playing, and the questions you couldn't ask at the start come up on their own: swipes aren't needed, on a computer people 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 needs to be shown, otherwise it's unclear the game is over.

That's what a sandbox gives you. Not code, answers. You write the real brief from them, and the real version 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.

It's the same chain as in the first section, except the "Questions" step has been replaced by a loop: when there's nothing to ask, you look first and write it down after. Only one thing goes down into the brief - answers. The sandbox has no arrow to the agent, and that's not an oversight: the agent builds the real version in a clean folder, from scratch. from there it's the same chain.

6. The brief lives in a file

Why a file and not the chat. Chat history gets lost: ten messages later you can't find the rule about merging tiles anymore. A file sits in the project folder next to the code, the agent reads it on its own when you point to it, and you can fix it and hand it over again with the same phrase. Any name works: BRIEF_2048.md, BRIEF_LANDING.md, or even task.txt. It's a plain text file, with no special format.

You hand it over with one phrase. Compare:

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

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

The second request is shorter than the first, yet 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 just say. A rule of thumb: if a rule or a boundary changed, edit the file and hand it over again ("win at 2048, not at 1024" goes in the file). If some small visual detail changed that doesn't affect the rules, just say it ("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 grown to two pages, it most likely picked up things that belonged under "not doing".

One last thing before you hand the file to the agent: read it once as if someone else wrote it. There's almost always a line that can't be checked. I find one every time.

7. What the agent does with the brief, and what's left to you

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

The point of a brief isn't to make the agent 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.