Interview yourself into an agent spec

Build-along · ~12 min at your own keyboard

Most agents fail because they were never specified, just vibed. 'I want an agent that finds deals' is a wish, not a build. The move that fixes it costs ten minutes: have Claude Code interview YOU, one question at a time, and turn the wish into a spec. Six things every agent needs pinned down before a line of code: the INPUT (what it reads), the TRIGGER (what makes it run, a schedule, a new row, a manual kick), the OUTPUT (what it produces and where it lands), the GUARDRAILS (what it must never do), the COST CAP (a hard ceiling on runs, tokens, or spend, so a loop can't drain your account), and the DEFINITION OF DONE (how you'll know a run was good). Make Claude ask, don't let it assume, and you'll catch the ambiguity now instead of at 2am when the agent has emailed the wrong list. The spec is the artifact; the code is downstream. Last, have it split the build into phases small enough that each one fits a single fresh session, with what each phase hands to the next. A phase that needs a long, crowded session is two phases.

Where these ideas come from: Grilling, Spec, The grill-me skill (AI Hero dictionary and open-source skills library (MIT)). Paraphrased here.

Your starter: Agent spec: one deal task

Template

Make it yours: Pick one task you do every week, name the exact inputs it reads and the one file it writes, and strike any line that gives it a decision you would not give an analyst on day one.

AGENT SPEC: [name, e.g. OM first read]

DOES ONE THING: [reads an offering memo and returns the facts table]
READS: [the OM PDF in /deals/inbox]
WRITES: [/deals/inbox/[deal]-facts.md], nothing else

OUTPUT SHAPE
- Address, units or SF, year built, occupancy, asking: each with the OM page number.
- Any figure the OM states without a basis is written [SOURCE NEEDED: figure, OM p. n]. No number without a source and a date.
- Three questions the broker must answer before a call.

DOES NOT: value the deal, email anyone, change any file but its own.
STOPS WHEN: the OM is over [n] pages, or it cannot find the rent roll.

The coach checks that what you paste back is your own work. The starter pasted back unchanged won't pass.

Do this

0/5

Share what happened

Paste the written spec Claude produced (input, trigger, output, guardrails, cost cap, definition of done) and the one gap the interview surfaced that you hadn't thought about.