ComputeSphereLearn
Console
Learning paths / Vibe coding to production / Brief before prompt

Brief before prompt

Reading · 6 min · Module 3, lesson 1 of 317 min left in this module

Module 3 · Brief before promptLesson 1 of 3

Goal: Write a short brief with a goal, acceptance criteria, constraints and non-goals before asking an agent to build anything.

3:59 · captions and chapters · narrated with an AI-generated voice
Transcript

Narration uses an AI-generated voice.

[00:00] Where we're going

By the end of this video, you'll be able to write a short brief before you ask an agent to build anything. We'll give an agent the same job twice. Once as a one-line prompt, and once as a brief.

[00:13] A one-line prompt

In the starter app, every task has a done flag, but nothing sets it. So first, the one-liner. Add a done button. The agent does it. A new route, a button on the page, and the tests pass. But the prompt left gaps, and it filled every one with a guess.

The button toggles. Click it again, and it says undo. You never asked for that. It restyled the list while it was there. And who may mark a task done? The route never checks. Anyone can change anyone's task. To be fair, the agent's summary mentions that. But it had to guess whether you cared. Each guess is plausible. But you've got nothing to check them against.

[00:59] The four parts

A brief closes those gaps before the agent starts. It has four parts. First, the goal. What the user can do afterwards. Not how. Second, acceptance criteria. Statements you can check, like a request and its response. Third, constraints. What must stay true, like no new dependencies. And fourth, non-goals. What looks related, but isn't part of this job.

[01:30] The brief

Here's the lesson's brief. The goal. Let a user mark one of their tasks as done, from the page. The criteria spell out what the route returns. Two hundred when it works, four oh four for an unknown task. And four oh three, if it isn't your task. That's the guess from before, now written down. The constraints say no new dependencies, and keep the in-memory store. The non-goals rule out editing titles, and undoing a done task. Last, ask for a plan before any edits.

[02:09] The plan

The agent replies with a plan. Four files, and what changes in each. It leaves undo out, because the brief says it's a non-goal. And it raises one question. The page always acts as the demo user, so Done on someone else's task will be refused. You read it, and say OK.

[02:30] What the brief produced

Here's what it built. The rules sit in one small function. Unknown task, four oh four. Not your task, four oh three. Each rule has a test, like this one for four oh three. Run the tests. Twelve pass, five of them new.

[02:48] Check it against the brief

Now review both changes against the same criteria. Four oh four for an unknown task. Both do that. Four oh three for someone else's task. Only the brief's version. No undo. Again, only the brief's. Tests for the rules. The one-liner's test covers the store, not who may change a task. With a brief, review is a checklist, not a feeling.

[03:16] Recap

To recap. An agent fills every gap in your request with a likely guess. A brief closes the gaps that matter. A goal, criteria you can check, constraints, and non-goals. You don't need one to explain a file, or rename a variable. You need one whenever a change touches behaviour a user, or an attacker, could notice.

Here's a question to check yourself. Which of these belongs under acceptance criteria? It's the four oh three. Anyone, including a test, can check it. Next, check what you've learned. I'll see you there.

Key idea

An agent fills every gap in your request with a likely guess. A brief closes the gaps that matter before it starts: what done looks like, what it must not touch, and what's out of scope. Ten minutes of writing saves an hour of unpicking.

A one-line prompt like "add a done button" works in a demo. In a real app the agent has to guess: which endpoint, who may use it, whether to add a library, whether to restyle the page while it's there. Each guess is plausible. Together they make a diff you can't review.

The four parts

  • Goal. One or two sentences on what the user can do afterwards. Not how.
  • Acceptance criteria. Checkable statements: a request and its response, a thing on the page, a test that passes. If you can't check it, it isn't a criterion.
  • Constraints. What must stay true: no new dependencies, the same data store, who's allowed to do what.
  • Non-goals. What looks related but isn't part of this job. This is what stops a small change growing into a rewrite.

A brief for the starter

The starter stores a done flag on every task, but nothing sets it. Here's a brief for that change:

## Goal
Let a user mark one of their tasks as done from the page.

## Acceptance criteria
- PATCH /api/tasks/:id with {"done": true} sets done and returns the task with 200.
- An unknown id returns 404.
- Only the task's owner (the x-user header) may change it; anyone else gets 403.
- The page shows a Done button on each of the current user's open tasks (with no x-user header the server treats you as demo), and none on anyone else's.
- npm test passes, including new tests for the rules above.

## Constraints
- No new dependencies.
- Keep the in-memory store.
- Don't change existing endpoints.

## Non-goals
- Editing titles or due dates.
- Undoing a done task.

## Before you edit
Reply with a plan: the files you'll change and why. Wait for my OK.

Paste it as your first message, or save it in the repository, for example as docs/briefs/mark-done.md, and point the agent at it. A saved brief doubles as the description when you open the pull request.

What a good brief buys you

  • Review gets easier. You check the diff against the criteria, line by line, instead of against a feeling.
  • Tests write themselves. Every criterion is a test waiting to happen (module 5).
  • Scope stays put. When the agent suggests something outside the brief, you can say no without arguing about it.

You don't need a brief for "explain this file" or "rename this variable". You need one whenever the change touches behaviour a user or an attacker could notice.

Check yourself

Which line belongs under acceptance criteria?
Why list non-goals at all?