Scrollcraft
Chapter 3 of 15RO

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.

Chapter 3 of 154 min read

What you will learn

By the end of this chapter
  1. 01Write a five-part brief: outcome, facts, limits, format and evidence.
  2. 02Turn a vague request into a specific one.
  3. 03Keep the rules that never change in a project rules file.
  4. 04Steer a session: a plan before code, one change at a time, and a way back.

01 · Anatomy

Five parts
Goal

Say 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.

Context

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.

Constraints

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.

Output

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.

Check

Ask for evidence

End with “list what you tested and what you could not test”. It makes gaps visible instead of hidden.

Template
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 request
Weak

Vague brief

Prompt
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.

Strong

Specific brief

Prompt
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 once

Put 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.

CLAUDE.md
# 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 adapt
Plan

Plan before code

For anything over a few lines, ask for the plan and approve it first.

Prompt
Do not write code yet. List the files you will change, the order, and the risks. Wait for my approval.
Small

One change at a time

Large combined requests hide which change broke the page.

Prompt
Make only this change: [change]. Do not touch anything else. Tell me which lines you edited.
Show

Ask for evidence

Ask what was run, not whether it works.

Prompt
Open the page at 375 px and 1440 px. Report the console errors verbatim, and name every element that overflows.
Critique

Review as a sceptic

A second pass with a different role catches things the first pass missed.

Prompt
Review this page as a hostile reviewer. List the five weakest points: performance, accessibility, motion that could cause discomfort, and anything that looks invented.
Explain

Make it teach you

You will maintain this code, so ask for reasons.

Prompt
Explain how the parallax maths works in plain terms, with one numeric example. Then say what would break if the speed were 0.9.
Undo

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.

bash
git init
git add -A && git commit -m "working hero"

Practice · Work with AI

The same task in your tool

Two 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

Prompt
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

Prompt
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 compare
1

Rewrite 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.

Prompt
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.
2

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.

3

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 course

Before any code, write down what the site is and the rules that never change.

  1. Write brief.md with the five parts for [subject], using the template below.
  2. Create your rules file in the project root (CLAUDE.md, GEMINI.md or AGENTS.md) with the limits from the brief.
  3. Run “Plan before code” and save the plan the AI gives you as plan.md.
  4. Run git init and commit, so every later step has a way back.
brief.md
# 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 result
  • brief.md has 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 log shows a first commit.

Practice · Assessment

Acceptance criteria

0 of 4 criteria met

Next Build

Ten steps with the exact prompt for each, 24 more prompts, and a complete three-file example that was run and checked.

Keyboard shortcuts: [ previous chapter · ] next chapter