Understanding Spec Driven Development

Welcome to the first lesson of this course, "Foundations of Spec-Driven Development."

In the current landscape of "vibe coding"—where we can describe a rough idea and let AI agents iterate until the result looks right—it's tempting to think that formal specifications are a relic of the past. You might be wondering: if an AI agent can see what it's implemented and adjust based on your feedback, why bother with a formal spec?

As an experienced engineer working with AI tools, you've probably experienced this workflow:

1. Prompt AI: "Create a login endpoint"
2. Review generated code, give feedback: "Add rate limiting"
3. Review again, give feedback: "Use JWT instead of sessions"
4. Review again, give feedback: "Add account lockout"
5. Review again, notice it broke something from step 2
6. Repeat...

Yes, AI maintains context. But this approach has real costs for you, right now. Let's examine why specifications still matter.

• Problem 1: You Don't Know When You're Done

  Without a specification, how do you validate the implementation is complete? You discover missing requirements by reviewing code, then add them iteratively. A spec defines "done" upfront.

• Problem 2: Iteration Is Expensive

  Vibe coding feels fast, but each iteration costs time and tokens. A 10-minute conversation to refine code could have been a 2-minute spec review + one generation.

• Problem 3: No Reference for Validation

  Six months later, a bug appears. Without a spec, how do you know if it's a bug or intentional behavior? You have to reverse-engineer the code (or dig through AI conversation history).

• Problem 4: Cross-Session Inconsistency

  You need to continue yesterday's work. Do you:

  • Re-read all the code to remember the details? (Time-consuming)
  • Continue yesterday's AI conversation? (Lost context, different session)
  • Start fresh and hope AI remembers the patterns? (Inconsistent implementation)
  • Reference a specification? (Instant context recovery)

• Problem 5: Unclear Edge Cases

  Without thinking through a spec first, you discover edge cases while reviewing generated code. Each discovery means another iteration cycle. A spec forces you to think through edge cases upfront, when it's cheapest to address them.

• Problem 6: Muddled Requirements

  You start with a vague idea, AI implements something, you realize that's not quite what you wanted, iterate, realize there's another aspect, iterate again. A spec forces you to clarify your own thinking before generating code.