Phase 1: Mindset Shift (Days 1–3) — Understand why traditional prompting is insufficient and what replaces it.
Understanding Core Concepts
1. Prompt vs Spec
A prompt is a request:
- "Make the authentication logic better."
A spec is a contract:
- Exact inputs and outputs
- What must pass and what must fail
- Constraints (don't change the database schema, keep the existing API contract, etc.)
- Clear success criteria
Agents perform dramatically better when they receive a contract instead of a wish.
2. Spec-Driven Development for Agents
Instead of hoping the agent "understands" what you want, you write the requirements so clearly that both you and the agent can check whether the result is correct.
This is the same discipline senior engineers use when writing tickets or RFCs — just applied to AI. The rigor is identical: no ambiguity, testable acceptance criteria, clear boundaries.
3. Why Vague Prompts Fail
When instructions are fuzzy, the agent fills in the gaps with assumptions. Those assumptions are often wrong, especially on edge cases:
- Boundary values (zero, negative, very large numbers)
- Malformed or unexpected input
- Concurrent requests
- State changes between calls
A good spec removes most of those guessing opportunities by making the edge cases explicit.
4. The Feedback Advantage
Recall from Day 1: evaluation is how you improve agents.
A clear spec makes evaluation easy. You can immediately score the agent's output against the written requirements instead of arguing with yourself about whether the result "feels" good enough.
Spec + Evaluation = The closed loop that compounds improvement.
Tiny Action for Today (20–30 minutes)
Take one feature the agent has been working on and turn your current instructions into a short spec using this template:
## Goal
[One clear sentence: what does this feature do?]
## Inputs
- What data or parameters does it receive?
## Expected Outputs
- What should it produce?
- In what format?
## Constraints
- What must NOT change?
- What dependencies must be respected?
## Success Criteria
- How do you know it worked?
- List 3–5 concrete, testable criteria
Save it somewhere you'll reference. Next time you ask the agent to work on that feature, give it the spec instead of a casual prompt and compare the difference in quality.