Lesson 1.1 · 45 minWriting a good brief

What you will have

The student has a four-part brief template saved in the project as docs/brief-template.md, and has seen with their own eyes how the same request produces a different result when it is written as a brief.

Video

The video for this lesson is not recorded yet.

Prompts used in this lesson

Part 3 — Demonstration: weak request versus brief

Make a nice form. Save it as practice/briefs/form-weak.html.

Purpose: I need a quote-request form for Brightside Cleaning, a home-cleaning service. Visitors use it to ask for a price. It must feel quick and trustworthy, because every extra field makes people give up, and we only need enough to call them back.

Context: This is a practice exercise. Create one standalone file, practice/briefs/form-brief.html, with its styles inside the same file. There is nothing to reuse yet.

Done looks like: The form has exactly four fields: name, email, phone, and a message box. There is one button labelled "Request a quote". Name and email are required. In a narrow, phone-width window nothing is cut off and the button is easy to find.

Constraints: Plain HTML and CSS only. No JavaScript and no libraries. The form does not need to send anything yet. Do not change any other file. Do not invent text such as testimonials or prices.

If anything is unclear, ask me before you start.

Part 5 — When you don't know what to ask for

I want to add a "services" section to a page for Brightside Cleaning, a home-cleaning service, but I have not decided what goes in it. Before you write anything, ask me the questions you need answered to do this well. Ask them one at a time. When you have enough, write the brief back to me using four headings: Purpose, Context, Done looks like, Constraints. Do not create or change any files yet.

Do along

You rewrite three weak requests as briefs, compare the results and save your template. Use the sample business, Brightside Cleaning. All files go in practice/briefs/. Pause the video where the steps say.

1. Pause after Part 3. Open a terminal in your project folder and start Claude Code with claude.
2. Request A, the form. Send the weak version exactly as in the video: Make a nice form. Save it as practice/briefs/form-weak.html. Then type /clear, and send your own four-part brief for a quote-request form, saving to practice/briefs/form-brief.html. Write it yourself; do not copy mine word for word.
3. Pause after Part 5. Request B, a services section. Weak version: Add a services section. Save it as practice/briefs/services-weak.html. Then /clear, and your brief, saving to practice/briefs/services-brief.html. Decide for yourself: which three services, how each is described, what the visitor should do after reading.
4. Request C, improving a page. Weak version: Make my about page look better. Work on a copy saved as practice/briefs/about-weak.html. Then /clear, and your brief, working on a copy saved as practice/briefs/about-brief.html. In "done", name two or three things you can see: for example, text width, spacing between sections, one accent colour.
5. For each pair, open both files side by side in the browser. Write down one sentence per pair: what did Claude have to guess in the weak version?
6. Now save your template. Type /clear, then:

Purpose: I want a reusable template for the requests I write to you, so I stop leaving things out.

Context: I use four parts: Purpose (what and why, and who it is for), Context (what exists, files and examples to look at), Done looks like (what I will check), Constraints (what must not change, what to avoid). I end with "If anything is unclear, ask me before you start."

Done looks like: A file docs/brief-template.md that contains those four headings, a one-line reminder under each of what to write there, and the closing line. It fits on one screen.

Constraints: Create only that file. No extra sections, no examples longer than one line.

1. Open docs/brief-template.md and edit it by hand until the reminders are in your own words.
2. Commit your work. Ask Claude: Commit everything with the message "Lesson 1.1: brief template and practice briefs". Read what it is about to commit before you approve.

If you already know your own business well, you may use it for requests B and C instead of Brightside. Keep the file names the same.

Check your work

1. Run ls docs (macOS) or dir docs (Windows). Expected: brief-template.md is listed.
2. Open docs/brief-template.md. Expected: four headings (Purpose, Context, Done looks like, Constraints) and the "ask me before you start" line.
3. Open practice/briefs/. Expected: six files, a -weak and a -brief version for form, services and about.
4. Open form-brief.html and compare it with the "done" paragraph of your brief. Expected: every sentence of "done" is true of the page.
5. Run git status. Expected: nothing left to commit.

Common problems

• The weak and brief versions look almost the same. → You probably did not type /clear between them, so Claude still remembered the first attempt; or your brief's "done" was vague. → Type /clear, add two checkable details to "done", and run the brief again.
• Claude changed a file you did not mention. → No constraint told it not to. → Say: "Undo your changes to every file except the one I named," and add "Do not change any other file" to your template's constraints reminder.
• Claude asks many questions instead of starting. → Your brief ended with "ask me if anything is unclear" and something was unclear. That is the brief working. → Answer, or say "Use your best judgement for the rest and list the assumptions you made."
• Pasting a screenshot does nothing. → The image is not on the clipboard, or your terminal uses a different shortcut. → Copy the image again and try Control+V; on Windows try Alt+V. Otherwise save the image into the project folder and refer to it with @.
• The brief version ignored one of your "done" points. → Say exactly which: "The brief says the button label is 'Request a quote'. It currently says 'Submit'. Fix that and nothing else."
• Your brief is half a page long. → Fine for a big task. For a one-line change, one sentence with the purpose is enough.

Homework

About 25 minutes, after the lesson. Nothing later depends on it. Use your own business idea from lesson 0.1. Save the files in practice/homework/1.1/; this is practice, not your real site text, which comes in section 2. At the end, ask Claude to commit with the message "Homework 1.1" (no tag).

1. One brief for your own business. Pick one small piece your site will need, such as an opening-hours block or a "where we work" section. Write a four-part brief from docs/brief-template.md, save its text as own-brief.md, then send it, with the result saved as own-piece.html. Done when: every sentence of "Done looks like" in own-brief.md is true of the page in your browser.
2. Three rules with a reason. In because.md, write three constraints your business needs, each followed by "because" and the reason. Done when: for each one you can name a decision you never mentioned that the reason would settle.
3. Let Claude interview you. Send the Part 5 prompt with your own business and one section you have not decided, for example an FAQ. Correct the brief Claude writes back, then ask Claude to save it as interview-brief.md and build nothing. Done when: the file has the four headings and contains at least one correction of yours.