the anatomy of a good request

the request is a spec in miniature

The PRD (lesson 1) defines the project; the request defines the next 20 minutes. The same three layers apply, shrunk to a paragraph (Addy Osmani's spec guide breaks it down the same way: goal, boundaries, verifiable criteria):

1. the goal – what should be true when the work is done
2. the constraints – what must not change, what's out of scope
3. the verification – how you'll both know it worked

If any of the three is missing, the agent fills it in from its own defaults – exactly like a PRD with no EXCLUDED list.

bad request, good request

The difference is not politeness, it's testability:

• ❌ "make the header nicer" — nicer by whose measure? The agent will pick one.

• ✅ "the nav links get a sliding hover highlight like Vercel's; the active page keeps the underline; run lint and show me a screenshot" — a goal, a constraint, a verification.

• ❌ "fix the bug" — which bug, seen where, expected what?

• ✅ "on mobile at 375px the CTA overflows the card – it should wrap under the title; verify with a 375px screenshot"

• ❌ "look at the code and improve what you can" — an invitation to a random walk.

• ✅ "report first, don't fix: list what you'd change in checkout.ts and why – I'll pick" — investigation and intervention are two different requests.

say what done looks like

The strongest habit from this whole module (the official guide's central recommendation: give the agent a check it can run): end the request with the evidence you expect. "tests green", "tsc with zero errors", "screenshot at 1440 and 375". The agent that knows how it will be judged organizes its whole session around producing that evidence – you're not just requesting work, you're installing a verification loop (the loop where the agent checks its own output against a stated standard before declaring it done).

what it looks like in production

A real request from building this site – note that the prompt itself names the standard ("best in class") and the agent's last step is producing the evidence, unprompted:

exercise

❯ exercise — rewrite three of your own requests

Dig out three requests you actually sent to an agent (or would send), and rewrite each with the three layers.

• ○each request names a goal that can be true or false – not a mood
• ○each request has at least one explicit constraint or exclusion
• ○each request ends with the evidence you expect (test, type check, screenshot)
• ○investigation requests are marked 'report, don't fix'

0/4 · log in so we can save your progress