The whole course in five examples
Artifact: your gut reaction to which pair feels most and least familiar
1. The summary
The whole course is the move from these prompts to these prompts. Five before/after pairs, drawn from real software engineering tasks. If they all feel obvious and you already write the second column, close the tab. The course is for people who can see the difference but don't yet reach for the second column on instinct.
2. The five pairs
Example 1 — Vagueness
Make this code better.Refactor handleSubmit to extract validation into a separate validate() function.
Keep the existing test suite passing.
Don't change the function's external signature.The difference. The vibe prompt has no target, no constraint, no success criterion. "Better" is in the eye of the model. The spec prompt names the change, the constraint, and what to preserve — three things the model can act on, the same way next time, in the same shape.
Example 2 — Hidden context
Why doesn't this work?
[200 lines of code]This Express handler returns 500 in production but works on my machine.
The production logs show: ECONNREFUSED 127.0.0.1:6379
We use Redis. The handler is below. What am I missing in the production config?
[the handler]The difference. The vibe prompt gives the model code and a vague complaint, then expects it to guess what "doesn't work" means. The spec prompt gives the actual symptom (the error), the environment difference (works locally, fails in prod), and the relevant detail (Redis). Now there's one question, with enough context to answer it.
Example 3 — Telling instead of showing
Write a commit message for this change in our team style.Write a commit message for the diff below. Match the style of these three real ones from our history:
fix(auth): clear stale session cookies on logout
refactor(api): collapse duplicate handler in /users
feat(billing): retry failed Stripe webhooks for 24h
[the diff]The difference. "Our team style" is a fact only your team knows. Three actual examples teach the style without you having to articulate it. Showing beats telling, every time, when style is involved.
Example 4 — Output shape
List any bugs you find in this code.Review the code below. Return JSON only, no prose. Schema:
{ bugs: [{ line: number, severity: "low" | "med" | "high", description: string, suggested_fix: string }] }
If there are no bugs, return { bugs: [] }.
[code]The difference. The vibe prompt gets you prose. Prose is fine to read, useless to a script. The spec prompt gets you JSON you can pipe directly to a tool, and forces the model to commit to specifics (line, severity) instead of waving.
Example 5 — Iterate, don't restart
Nope, that's wrong. Try again.The function signature and the happy-path logic are correct — keep those.
The error handling missed one case: when the input array is empty, the function should return null, not throw "Cannot read property". Fix only that case.The difference. "Try again" throws away the work and the context. The model rolls dice. The spec prompt names what's right (so it stays), what's wrong (so it changes), and constrains the change to just that. The next attempt is closer, not random.
3. The honest test
The gap between I see the difference and I write the spec column by default is what the course closes.
4. What's next
Chapter 1 is the mental model — why these pairs are different in kind, not in length. Chapter 2 breaks down the five parts of a prompt that works. Chapters 3, 4, 5, and 6 apply the model: showing examples, iterating, naming the failure modes, and prompting across different kinds of software work.