Prompting: how to brief an AI so the first draft is usable.
Most weak results come from a weak brief. This chapter gives you a template, a worked before and after, a project rules file and six patterns for steering the work.
What you will learn
By the end of this chapter- 01Write a five-part brief: outcome, facts, limits, format and evidence.
- 02Turn a vague request into a specific one.
- 03Keep the rules that never change in a project rules file.
- 04Steer a session: a plan before code, one change at a time, and a way back.
01 · Anatomy
Five partsSay what exists at the end
One sentence that names the thing and who it is for. “A one-page site for a fictional studio” is a goal. “Something cool” is not.
Give it the facts it cannot guess
File names, the theme, the libraries you already chose, and what is out of scope. The assistant will otherwise pick for you.
Set the limits
Exact library versions, which properties may be animated, the reduced motion rule, the browsers that matter. Constraints are the cheapest way to avoid rework.
Name the format
“The three files, nothing else” stops a long explanation you do not need. Ask for a short plan first when the task is large.
Ask for evidence
End with “list what you tested and what you could not test”. It makes gaps visible instead of hidden.
Goal: [what exists at the end, for whom]
Context: [files, theme, libraries, scope]
Build, in order: [numbered list]
Constraints: [versions, allowed properties, reduced motion, browsers]
Output: [format]. Then list what you tested and what you could not test.02 · Before and after
Same requestVague brief
Make me a cool scroll website with animations.You will get a generic page, probably with a heavy library, a gradient and effects nobody asked for. You then spend several rounds undoing choices.
Specific brief
Goal: a one-page site for a fictional studio called Northlight, built in plain HTML, CSS and JavaScript.
Context: it is a teaching example. The three files are index.html, style.css and app.js. Dark theme, one accent colour.
Build, in this order:
1. A hero with two parallax layers (speeds 0.2 and 0.4).
2. A sentence that lights up word by word as I scroll through a sticky section.
3. Three cards that fade up when they enter the viewport, once.
4. A pinned horizontal gallery with five panels.
Constraints: Lenis 1.1.18 from jsDelivr for smooth scroll. Transform and opacity only. Reduced motion switches everything off.
Output: the three files, nothing else. Then list what you tested and what you could not test.Every ambiguous decision is settled. The result can be checked against the list, item by item.
03 · Rules file
Write it oncePut the rules that never change into a file the tool reads at the start of each session, so you stop repeating them. Claude Code reads CLAUDE.md, Gemini CLI reads GEMINI.md, and Codex reads AGENTS.md. File names and loading rules can change, so check the current page for your tool before relying on it.
# Northlight
Static site: index.html, style.css, app.js. No build step.
## Rules
- Vanilla JavaScript. Libraries come from jsDelivr, pinned to an exact version.
- Animate transform and opacity only.
- Every motion has a prefers-reduced-motion fallback.
- Test with `python3 -m http.server 8000`. Never open the file directly.
- Do not invent copy, statistics, quotes or client logos.
## Done means
- No console errors at 375, 768 and 1440 px wide.
- You list the checks you ran and the checks you could not run.Keep it short. Rules that are long or contradictory get ignored more often than short, concrete ones.
04 · Six patterns
Copy and adaptPlan before code
For anything over a few lines, ask for the plan and approve it first.
Do not write code yet. List the files you will change, the order, and the risks. Wait for my approval.One change at a time
Large combined requests hide which change broke the page.
Make only this change: [change]. Do not touch anything else. Tell me which lines you edited.Ask for evidence
Ask what was run, not whether it works.
Open the page at 375 px and 1440 px. Report the console errors verbatim, and name every element that overflows.Review as a sceptic
A second pass with a different role catches things the first pass missed.
Review this page as a hostile reviewer. List the five weakest points: performance, accessibility, motion that could cause discomfort, and anything that looks invented.Make it teach you
You will maintain this code, so ask for reasons.
Explain how the parallax maths works in plain terms, with one numeric example. Then say what would break if the speed were 0.9.Keep a way back
Commit or copy the folder before each large step. If a change goes wrong, revert and rewrite the prompt rather than patching on top.
git init
git add -A && git commit -m "working hero"Practice · Work with AI
The same task in your toolTwo prompts you will use for the rest of the course: one that makes the AI plan before it codes, one that makes it look for its own mistakes.
Open a terminal in the project folder and run claude. Press Shift+Tab until plan mode is on, paste the prompt, read the plan, then approve it. Project rules go in CLAUDE.md.
Plan before code
Read CLAUDE.md and brief.md. Do not write code yet. Give me a numbered plan for the hero section of the site for [subject]: the files you will change, what each change does, and how I can check it in the browser. Wait for my approval.Review as a sceptic
Review your last change as a sceptical senior front-end developer. List what could break on a phone, with reduced motion and with the keyboard only. Do not fix anything yet.Open a terminal in the project folder and run gemini; the first time, it asks whether you trust the folder, so say yes for your project. Paste the prompt. Gemini CLI asks before it edits a file or runs a command: read each request before you accept it. Project rules go in GEMINI.md.
Plan before code
Read GEMINI.md and brief.md. Do not write code yet. Give me a numbered plan for the hero section of the site for [subject]: the files you will change, what each change does, and how I can check it in the browser. Wait for my approval.Review as a sceptic
Review your last change as a sceptical senior front-end developer. List what could break on a phone, with reduced motion and with the keyboard only. Do not fix anything yet.Open a terminal in the project folder and run codex, then paste the prompt and approve each change. In the ChatGPT app without Codex, attach the files, paste the prompt and copy the changes back yourself. Project rules go in AGENTS.md.
Plan before code
Read AGENTS.md and brief.md. Do not write code yet. Give me a numbered plan for the hero section of the site for [subject]: the files you will change, what each change does, and how I can check it in the browser. Wait for my approval.Review as a sceptic
Review your last change as a sceptical senior front-end developer. List what could break on a phone, with reduced motion and with the keyboard only. Do not fix anything yet.Practice · Exercises
Try first, then compareRewrite a vague brief
Rewrite “Make me a cool website with animations.” as a five-part brief for [subject].
Hint: go through outcome, facts, limits, format and evidence in that order.
Show the solution
Compare yours with this one. Every part answers a question the AI would otherwise guess.
Outcome: a one-page cinematic site for [subject], for [audience], ending with one action: [one action].
Facts: five sections in this order: hero, story, three features, pinned product moment, call to action. Use only the text I give you.
Limits: plain HTML, CSS and JavaScript in three files. Animate only transform and opacity. Every effect has a still version under prefers-reduced-motion. No invented numbers, quotes or logos.
Format: the three files in full, then a list of what changed.
Evidence: list every check you ran, with the width or tool, and every check you could not run.Find the missing part
This brief has no limits: “Build a one-page site for [subject] with a pinned product section and a contact link. Reply with the three files.” Add them.
Hint: limits are what the AI must not do or use.
Show the solution
For example: plain HTML, CSS and JavaScript; no library except Lenis; animate only transform and opacity; respect reduced motion; nothing hidden without a .js class; no invented numbers, quotes or logos.
Ask for evidence
Write the one sentence that makes the AI prove its work instead of saying “tested”.
Hint: ask for what was run and for what was not.
Show the solution
“List every check you actually ran, with the width or tool you used, and every check you could not run and why.” Then open the page and look at the checks it could not run.
Practice · Course project
One site, built across the courseBefore any code, write down what the site is and the rules that never change.
- Write
brief.mdwith the five parts for [subject], using the template below. - Create your rules file in the project root (CLAUDE.md, GEMINI.md or AGENTS.md) with the limits from the brief.
- Run “Plan before code” and save the plan the AI gives you as
plan.md. - Run
git initand commit, so every later step has a way back.
# Brief: [subject]
Outcome: a one-page cinematic site for [subject], aimed at [audience].
The page ends with one action: [one action].
Facts: names, real numbers, real quotes, and the sections in order.
Limits: plain HTML, CSS and JavaScript in three files. Animate only
transform and opacity. Every effect has a still version under
prefers-reduced-motion. No invented numbers, quotes or logos.
Format: the three files in full, then a list of what changed.
Evidence: every check you ran, with the width or tool, and every
check you could not run.Practice · Test it
Check the resultbrief.mdhas all five parts, and none of them says “TBD”.- Asked “Which rules apply in this project?”, your AI quotes your rules file.
- The plan names files and a check for each step, and no file changed before you approved it.
git logshows a first commit.
Practice · Assessment
Acceptance criteria0 of 4 criteria met