Module 1: Spec-First Methodology and TDD with AI

Capsule overview

So far you've used Claude Code to generate code — endpoints, functions, whole modules. And it works. But there's a problem you've probably already felt: how do you know the generated code is correct? That it handles the edge cases? That it doesn't break something that already worked?

The answer isn't "review the code manually" (that doesn't scale) or "trust that the AI got it right" (that isn't reliable). The answer is tests as specification: you define exactly what should happen BEFORE asking Claude Code to implement. The tests are your contract with the AI — if they pass, the code is correct. If they fail, Claude Code iterates until it is.

This module introduces the philosophy that transforms your relationship with Claude Code: you stop being "the one who asks for code" and become "the one who defines the expected behavior." It's a paradigm shift — and it's the foundation of everything that comes in this guide.

Module Context

Where are we?

This is Module 1 of the "Testing with Claude Code" guide — guide #7 of the Claude Code Agentic Development Path.

What you already know (guides #1-6 of the path):

✅ Using Claude Code to generate code
✅ Prompt engineering to get quality outputs
✅ Managing context and files with Claude Code
✅ Orchestrating complex tasks with the agent
✅ Working with PRDs, plans, and TODOs
✅ Debug and code review with Claude Code

What's missing: A method to verify that what Claude Code generates is correct. That's exactly what this guide gives you.

Where are we headed?

This guide has 3 phases:

Phase 1: TDD Fundamentals with AI (Modules 1-3)
→ Spec-first, unit tests, integration/E2E

Phase 2: Testing Workflows (Modules 4-6)
→ Complete TDD, coverage, mocking, validation loops

Phase 3: CI and Project (Modules 7-8)
→ GitHub Actions, TDD-complete capstone project

This first module establishes the philosophy that holds everything else up. Without understanding why TDD changes radically with AI, the technical modules would just be "how to write tests" — something that already exists in a thousand tutorials. What makes this guide different is the context: tests as specification for an AI agent.

Professional Objective

Understand that in agentic development, tests aren't "after-the-fact verification" — they're up-front specification. They're the most precise language for telling Claude Code what to build.

By the end of this module you'll be able to:

✅ Explain why TDD matters more with AI than without it — and convince your team to adopt it
✅ Apply spec-first methodology: define behavior as tests BEFORE implementing
✅ Run your first spec→implement→validate cycle with Claude Code
✅ Distinguish test-first from test-after and explain why test-first produces more reliable results with AI
✅ Identify the traits of a good test-spec: deterministic, independent, clear, with a single reason to fail

Module Progression

Module Map

Capsule	Topic	What you'll learn
02	Why TDD matters more with AI	The problem of speed without validation — how AI amplifies both good code and bugs
03	Spec-First Methodology (Tweag)	The inversion of control: you define "what should happen" (tests), Claude Code implements "how"
04	Anatomy of a good test-spec	What makes a test a good specification: deterministic, independent, clear
05	First spec→implement cycle with Claude Code	Hands-on: you write tests, Claude Code implements, you validate — your first complete cycle
06	Project: Spec-first mini-app	Apply it all: you define a calculator with tests as the spec, Claude Code implements it

Learning flow

The module follows a deliberate progression: problem → philosophy → technique → practice → project.

First you'll understand the problem (capsule 02): why generating code without tests is accelerated technical debt when the AI produces code at unprecedented speed. Without this context, TDD feels like unnecessary bureaucracy.

Then you'll get to know the philosophy (capsule 03): spec-first methodology, based on Tweag's work with LLMs. The core idea is an inversion of control — you stop telling Claude Code "implement this" and start telling it "here are the tests that define what should happen — implement so they pass."

Next you'll master the technique (capsule 04): what makes a test a good specification. Not just any test works as a spec — you need tests that are deterministic, independent, with a single reason to fail, and that document behavior, not implementation.

In capsule 05 you'll put it all into practice: your first spec→implement→validate cycle with Claude Code. You'll write simple tests, give them to Claude Code as context, and watch it implement exactly what you defined. This is the module's "aha" moment.

Finally, in the project (capsule 06) you'll build a complete mini-app using spec-first: you define tests for a calculator (addition, subtraction, multiplication, division, edge cases) and Claude Code implements. The focus isn't the calculator — it's experiencing the complete workflow.

Project Connection

This module's project: Spec-first mini-app

You'll build a calculator app where everything starts with tests:

You define tests for add(a, b), subtract(a, b), multiply(a, b), divide(a, b)
You add tests for edge cases: division by zero, negative inputs, floats
You give the tests to Claude Code as context
Claude Code implements the logic
You run the tests and validate

It's deliberately simple in implementation but rich in workflow. The goal is for you to experience the spec→implement→validate cycle, not to build something complex.

Connection with the final project (Module 8)

The guide's final project is a complete application built 100% with TDD + Claude Code — a REST API with authentication, CRUD, and business logic. Every feature of that application is built exactly like the calculator in this module: tests first, Claude Code implements, you validate. The difference is scale, not process.

What you learn here is the fundamental pattern that repeats throughout the guide:

Define test → Give context to Claude Code → Claude implements → Tests validate → Next test

Key Module Concepts

Test-Driven Development (TDD)

A methodology where you write tests before writing the implementation. The classic cycle is:

Red: You write a test that fails (because the implementation doesn't exist)
Green: You write the minimal implementation to make the test pass
Refactor: You improve the code without breaking tests

In classic TDD, you do all three steps. In agentic TDD, you do step 1 (write the test) and Claude Code does steps 2-3 (implement and refactor).

Spec-First

A philosophy where tests are the system's specification. Instead of documenting requirements in natural language (ambiguous), you document them as tests (precise, executable, verifiable). Based on Tweag's work with LLM-assisted development.

Validation Loop

An automatic cycle where Claude Code runs tests → identifies failures → fixes → re-runs. This loop is what makes agentic TDD fundamentally different from manual TDD: the AI self-corrects using test output as feedback.

Boundaries: What This Module Will NOT Do

❌ Advanced pytest — Covered in Module 2 (unit tests with Claude Code). Here you'll only use the bare minimum needed to write a test
❌ Integration and E2E tests — Covered in Module 3. This module focuses exclusively on the philosophy and the first cycle
❌ Coverage and metrics — Covered in Module 5. Here you won't measure coverage, you'll only experience the workflow
❌ The history of TDD — You don't need to know Kent Beck or the evolution of TDD. What you need is to understand the inversion of control with AI
❌ Comparing testing frameworks — We only use pytest. There's no unittest vs nose vs robot framework debate
❌ CI/CD — Covered in Module 7. Here the tests run locally

Why these boundaries? This module is philosophical and practical at the same time. You need to understand the "why" before diving into the "how." The following modules give you all the technique — but without this conceptual foundation, the technique gets applied mechanically without understanding its value.

Evidence of Success

By the end of this module, you'll know you succeeded if:

✅ You can explain in one sentence why TDD matters more with AI: "The speed of generation amplifies both good code and bugs — tests are the filter"
✅ You can describe the inversion of control: you define "what should happen" (tests), Claude Code implements "how"
✅ You ran at least one complete spec→implement→validate cycle with Claude Code — you wrote a test, Claude Code generated the implementation, and the test passed
✅ You can evaluate a test as a spec: is it deterministic? independent? does it have a single reason to fail?
✅ You completed the mini-project: a calculator with tests as the spec and Claude Code as the implementer

What You'll Change After This Module

Before this module, your workflow with Claude Code was probably:

You: "Implement a function that calculates discounts"
Claude Code: [generates code]
You: [reviews visually] "Looks good" → push

After this module, your workflow will be:

You: [writes test] test_discount_10_percent → expects 90
You: [writes test] test_discount_zero → expects original price
You: [writes test] test_discount_negative → expects ValueError
You: "Implement so these tests pass"
Claude Code: [generates code]
You: pytest → ✅ All tests pass → push

The difference: In the second workflow, you don't need to trust your visual review. The tests are your safety net — automatic, precise, and reproducible.

Summary

✅ This module establishes the spec-first philosophy: tests as specification for an AI agent
✅ TDD changes radically when the implementer is Claude Code — you define "what", the AI implements "how"
✅ The module progresses from problem → philosophy → technique → practice → project
✅ The project is a calculator app built with spec-first: tests first, Claude Code implements
✅ Only basic pytest is used — the advanced technique comes in later modules
✅ Everything you learn here is the fundamental pattern that repeats throughout the guide

Next capsule: Why TDD matters more with AI — the problem of speed without validation.

Additional Resources

Tweag: Test-Driven Development with LLMs - The spec-first methodology this module is based on
pytest Documentation - Official pytest documentation (reference, you don't need to read it all now)
Martin Fowler: Test-Driven Development - An introduction to classic TDD by Martin Fowler
Anthropic: Claude Code Documentation - Official Claude Code documentation
Kent Beck: TDD by Example - The book that originated TDD (historical reference, not a prerequisite)
The Pragmatic Programmer: Test-First - A pragmatic perspective on testing

Module 1 — Testing with Claude Code Guide Spec-first: tests as specification, not as verification

Next →Why TDD Matters More with AI Than Without It