Module 03 · 25 min

Prompting Claude Code Well

The single biggest skill. Most "the AI didn't get it" moments are really "the instruction wasn't clear." Let's fix that.

Module 3 of 5

What you'll learn

The four ingredients of a strong instruction
How to give Claude Code the right context (and point at specific files)
When and how to use Plan mode for bigger tasks
How to iterate instead of starting over

The mindset: brief a smart new teammate

Imagine a sharp new colleague on their first day. They're capable but they don't know your project, your preferences, or what "done" looks like to you. You wouldn't say "fix the thing." You'd say what, where, and why. Prompting Claude Code is the same — and the clearer your brief, the better the result.

The four ingredients of a strong instruction

1. Goal — what outcome you want

"Add a contact form" → better: "Add a contact form that emails submissions to info@example.com."

2. Context — where & what it's working with

Point at the file or area: "in contact.html", "match the style of the existing forms."

3. Constraints — the guardrails

"Don't add any new libraries", "keep it under 50 lines", "don't touch the header."

4. Done — how you'll both know it worked

"It's done when the form validates the email and shows a thank-you message."

Weak vs. strong — see the difference

✕ Weak

make the website better

No goal, no context, no definition of done. Claude Code has to guess what "better" means and may change things you didn't want touched.

✓ Strong

On the home page (index.html), make the main heading larger and add a short subheading under it that explains what we do. Match the existing fonts and colors. Don't change anything else.

Clear goal, specific file, a style constraint, and a boundary. Easy to approve or correct.

✕ Weak

fix the bug

Which bug? Where? What's the symptom? Claude Code will go hunting and may "fix" the wrong thing.

✓ Strong

When I submit the signup form with an empty email, the page crashes instead of showing an error. Find why and fix it so it shows a friendly "please enter your email" message instead.

Describes the symptom, the trigger, and the desired behavior. Claude Code can reproduce and verify.

Point at things with @

Type @ in your prompt to reference a specific file by name — for example, "refactor @utils.js to be easier to read." This focuses Claude Code exactly where you want it instead of making it search.

Plan mode — look before it leaps

For anything bigger than a one-line change, ask Claude Code to plan first. In Plan mode it investigates and writes out the steps it intends to take without changing any files, and waits for your approval. You read the plan, correct it if needed, then let it proceed.

claude — plan mode

> Plan how you'd add a dark-mode toggle to the site before doing anything.

Claude Code (plan):
  1. Add a toggle button to the header in header.html
  2. Store the theme choice in the browser so it persists
  3. Add dark-mode color variables in variables.css
  4. Wire the toggle to switch a class on the page
  Approve this plan? (or tell me what to change)
> Good, but skip step 1 — put the toggle in the footer instead.

You can switch modes during a session (Claude Code shows the current mode and how to cycle it). Plan mode is the safest way to take on something unfamiliar: you approve the approach before any code is written.

Big task? Break it down

Don't ask for ten things in one breath. Give one clear task, let it finish, review, then give the next. Small steps are easier to check and easier to undo. You can also ask Claude Code itself: "break this into smaller steps and do them one at a time, pausing after each."

Iterate — don't restart

The result is rarely perfect on the first try, and that's normal. The skill is steering, not re-rolling. Reply with a correction and Claude Code adjusts in place:

claude — iterating

> Close — but the button is too big and the wrong color.
  Make it the same size as the Donate button and use our teal.

> Better. Now add a little space above it.

Specific feedback ("too big → match the Donate button") beats vague feedback ("I don't like it"). If a path goes really wrong, remember Esc Esc rewinds, and /clear starts a clean slate.

Try it yourself

In your practice folder, ask Claude Code to "create a simple personal webpage about a hobby." Then iterate three times with specific feedback: change a color, add a section, adjust the wording. Notice how each precise instruction gets you closer than starting over would.

Knowledge check

Which instruction will Claude Code most likely handle well on the first try?

Correct: It names the file (@about.html), states a specific goal (shorten to two sentences, fix typos), and sets a boundary (don't change anything else). Goal + context + constraint = a clean result you can approve with confidence.

Key takeaways

A strong instruction has four parts: goal, context, constraints, and a definition of done.
Use @filename to point at exactly what you mean.
For anything non-trivial, ask it to plan first and approve the approach before it writes code.
Iterate with specific feedback instead of starting over; Esc Esc and /clear are your reset buttons.

Finished this module?