How to Write a Good Brief for an AI Agent

A good brief for an AI agent says who the application is for, which problem it solves and which concrete cases will show you that it works. If your first attempts with Claude Code or Codex were disappointing, the cause is often less the tool than a brief that leaves these three things open.

The agent fills gaps with assumptions. The more gaps, the more assumptions, and the further the result drifts from what you had in mind. This post shows how to build a brief, how to break it into smaller steps and what that looks like for a contact list.

Why a short brief rarely gets you what you want

A typical first attempt reads something like: "Build me an app for my contacts." The agent delivers something. Perhaps a list of names and phone numbers, perhaps a form with twenty fields, perhaps a login page you never asked for. Technically, none of that is wrong. It just doesn't fit your work.

The problem: you know who will use the app, how many contacts there are and what should happen after a conversation. The agent doesn't. It guesses. And because you didn't decide beforehand how you'll measure success, all you're left with is a gut feeling that something isn't right. Then comes the next attempt, vague again, guessed again.

A brief with a clear target user, a clear problem and testable cases breaks this loop. You can hold every result up against your cases and say exactly what's missing.

The three parts of a good brief

Target user: who is the app for?

Describe the person who works with the app and their situation. "For a small company" is a start. Better: "For a salesperson at a small company who manages leads from trade fairs and enquiries and wants to know on Monday whom to call back." From this sentence the agent can work out that the interface should be simple, that dates matter and that nobody needs an admin panel for a hundred users.

Problem: what should get better?

Name the problem, not the solution. "I want a table with filters" describes a solution. "Follow-ups get forgotten because they're scattered across notes and emails" describes the problem. When the agent knows the problem, it can make sensible decisions you didn't spell out. And later you can check whether the solution actually addresses the problem.

Acceptance cases: how do you know it works?

Acceptance cases are short, concrete situations with an expected result. A proven format is: starting point, action, expected result. For example: "There is a contact with a follow-up date of yesterday. When I open the list, this contact is marked as overdue."

Cases like these have two advantages. The agent understands more precisely what you mean. And you have a checklist you can run through after every change instead of relying on an impression. Acceptance cases can later be turned into automated tests. Then a single command checks whether everything still holds.

Think about failure cases too: what happens when a required field is left empty, when an email address has no @, when the list is empty? These are exactly the cases people forget on the first go, and exactly where the bugs appear that cost you time later.

How to break the brief into smaller steps

Even a good brief is too big if it describes the whole app at once. The agent then produces a lot of code in one go, and if something is wrong, you don't know where to look. It's better to split the work into small steps that can each be checked on their own.

Here's how:

1. Write down the goal of the whole app in two or three sentences: target user and problem.
2. Collect everything the app should do as a loose list.
3. Order the items so that each builds on the one before. First display, then save, then change, then connect.
4. Write two to four acceptance cases for each step, including at least one failure case.
5. Give the agent only one step at a time and check the cases before moving on.
6. Note what the agent contributed and what you changed yourself.

The last point seems minor. But it helps you explain later how your app came about, and it lets you trace bugs faster.

A good step is small enough that you can check the result in a few minutes. If checking a step takes you half an hour, it was too big.

Example: a brief for a contact list

This is what a brief for the first stage of a contact and follow-up app could look like:

Target user: A salesperson at a small company. They manage leads
and want to see whom to contact next.

Problem: Follow-ups get forgotten because contacts and next steps
are noted in different places.

This step: A contact list and a detail view with sample data.
No saving yet, no editing, no login.

Acceptance cases:
1. Given five sample contacts. When I open the app,
   I see all five with name, company and status.
2. When I click a contact, the detail view opens
   with all details and the next follow-up date.
3. When I click 'Back' in the detail view, I see
   the list again.
4. Given no contacts. When I open the app, I see
   the message 'No contacts yet' instead of an empty screen.

Note what the brief explicitly rules out. "No saving yet, no login" stops the agent from building features you can't test in this step anyway.

The next steps

Only when all four cases pass does the next brief follow. The order could look like this:

• Save contacts and validate input: a new contact without a name is rejected, with a clear message.
• Status change: a contact moves from 'new' to 'contacted', and the list shows the new status immediately.
• Filter: when I filter by 'overdue', I only see contacts whose follow-up date is in the past.
• Interface: when the service doesn't respond or returns an error, the app shows a message instead of crashing.

Each of these steps gets its own acceptance cases again. That way the app grows in small, controlled pieces.

How to tell your brief isn't good enough yet

Go through these questions before you send it:

• Does it say who uses the app and in what situation?
• Does it describe the problem, not just a feature you want?
• Are there at least two concrete acceptance cases with an expected result?
• Is there at least one failure case, such as empty input or an empty list?
• Does it say what should explicitly not be built in this step?
• Can you check the result in a few minutes?

If any answer is no, add to the brief before you send it. That takes a few minutes and saves you several rounds of fixes.

And if the result still doesn't fit: hold it up against your acceptance cases. Tell the agent exactly which case fails and what happens instead. "Case 3 fails: after clicking Back, the detail view stays open" is feedback the agent can work with. "Doesn't work" is not.

How the Vibe Coding Foundation course practises this approach

In the Vibe Coding Foundation course you build exactly this contact and follow-up app, step by step, with Claude Code or Codex. Writing the brief is a mission of its own: in Mission 1 you describe who the app is for and what it should do. The planned time for it is two hours. Breaking a work task into testable steps and describing them as acceptance cases is one of the four skills the programme certifies.

The following missions build on this: the contact list with a detail view, input validation with status changes and filters, and a simulated interface with empty responses, errors and delays. Each mission has a goal, criteria in the form of tests and hints at three levels in case you get stuck. On your computer, a command checks the criteria, so you quickly see whether your brief led to the result you wanted. Alongside, you keep an AI log recording what the AI contributed and what you changed yourself.

You'll find all missions and their goals in the course overview (in German). If you want to see how it starts, Mission 0 on setting up the tools is free to read (also in German). How the course works overall is explained in the course structure section on the home page. At the end there is a written project exam. The exam rubric shows how it is assessed.