Your builder path
3 / 6 chaptersThis chapter
Slide 1 of 5This slide
Why a spec first
Why the coach asks before it builds
You are about to answer a lot of questions before you see anything on screen. That is the method working, not the tool stalling.
Need a hand?
If a question feels slow, remember that the alternative is finding out at the end that it built the wrong thing.
For this step
Your controls
What the architect decides
Four decisions stay yours no matter how fast the AI moves: who it is for, how big, what proves it works, and what comes next.
Who it is for
Name one real user.
How big
One main action today.
What proves it
The check you will run.
Next move
The smallest useful step.
Spec-driven means the decisions get written down before the code exists. It is the difference between directing a build and hoping for one.
| Vibe coding | Spec-driven |
|---|---|
| "Build me an app" | "Build a list for my club's events" |
| The AI decides the scope | You decide the scope |
| You find problems at the end | You find them one card at a time |
| The chat holds everything | Files hold everything |
The coach will ask you questions one at a time. Answer them properly. Every minute here removes ten minutes of rebuilding later.
Core rule
The chat is not the source of truth. The files are.
For this step
project-brief.md is the shortest and most important file in your project. It
locks four things:
| It records | Why it matters |
|---|---|
| Who this is for | One person or one group, never "everyone" |
| What they need | The single result they came for |
| The one main action | The thing you will test at the end |
| What is out of scope today | The list that protects your session |
If the coach guesses your user, correct it. A build aimed at nobody in particular is the most common way a session ends with something impressive that nobody would use.
For this step
The coach infers a build shape from your idea, tells you which one it chose and why, and asks you to confirm once.
| Build shape | You get | Tested by |
|---|---|---|
| Content-led site | Pages, sections, one primary action | Reading it, clicking the action |
| Browser-local tool | Add, edit, delete, save in the browser | Refreshing and checking data survives |
If your idea needs login, payments, a database or a live API, the coach proposes a browser-only version instead. Accept that today. It is a later build, not a smaller ambition.
For this step
"Make it modern" is not direction. design.md exists to turn taste into
instructions the AI can actually follow.
| Vague | Specific |
|---|---|
| Clean and modern | White ground, one accent colour, 1px lines |
| Like a big travel site | Borrow the card grid; do not copy the logo or photos |
| Nice fonts | One sans for body, heavier weight for headings |
| Works on mobile | Single column under 600px, buttons full width |
Borrowing a layout pattern is normal practice. Copying a logo, a brand name, someone's photos or their testimonials is not. The coach will hold that line if you ask it to.
For this step
By the end of planning your folder holds the whole plan, in files that survive a closed laptop and a new chat session:
project-brief.md who, what, scope, success target
architecture.md stack, structure, storage
design.md borrow, avoid, layout, type, mobile
build-blueprint.md the full builder-ready spec
build-status.md phase, done, blockers, next instruction
work-cards/01-*.md the first small implementation stepRead the first Work Card before you approve it. Check two things: you understand what it builds, and it says how you will know it worked.
Before you move on
Common mistakes
- Rushing the questions, then getting a build aimed at nobody.
- Accepting "make it modern" as a design decision.
- Approving the whole plan instead of the first card.
- Choosing an idea that needs login or payments on day one.
- Arguing with the coach in chat instead of asking it to update the file.
Work through one step at a time. Ticking a step marks it for this page view only, so nothing is saved when you leave.