Chapter 46: Your First TDG Cycle
Emma sets her laptop on the table and turns the screen toward James. On it: five lines of Python. A function name, a type annotation, an ellipsis, and two assertions. "That," she says, "is the whole specification."
James looks at the screen, then back at Emma. "Where is the rest of it?"
"There is no rest of it. You write these five lines. AI writes the twenty lines that make them pass. You verify." She taps the terminal. A green bar. All tests passing. "That is the loop."
In Chapter 45, you learned to read Python -- to predict output, build trace tables, and catch bugs before running code. You can look at a function and know what it does. Now you use that skill for something new: you write a tiny specification -- a function stub with type annotations and a pair of tests -- and let AI generate the implementation. Then you read what AI wrote, predict whether it is correct, and run the tests to verify.
This workflow is called Test-Driven Generation (TDG). It is Spec-Driven Development applied to code: you write the specification in Python (types and tests) instead of English, AI generates the implementation, and your tools (pytest and pyright) verify the result automatically. The method stays the same as Chapter 16. The language changes from English to Python.
What You Will Learn
By the end of this chapter, you will be able to:
- Explain what TDG is and how it connects to SDD from Chapter 16
- Write a function stub with a return type annotation and an ellipsis body
- Write two test assertions that define what the function must do
- Prompt AI to implement the function and verify the result with pytest and pyright
- Read AI-generated code using the PRIMM skills from Chapter 45
- Re-prompt AI when the first attempt does not pass your tests
The TDG Loop
Every lesson in this chapter follows the same loop:
| Step | What You Do | Tool |
|---|---|---|
| Specify | Write a stub (... body) with type annotations and test assertions | Your editor |
| Check types | Run uv run pyright -- types must pass before AI generates anything | pyright |
| Generate | Prompt AI: "Implement the function that passes these tests" | Claude Code |
| Verify | Run uv run pytest -v -- tests must pass | pytest |
| Read | Apply PRIMM from Chapter 45: predict what the generated code does, then verify | Your brain |
This is the same Red-Green cycle from test-driven development (TDD), invented by Kent Beck in 1999. The difference: in TDD, the human writes the implementation. In TDG, AI generates it. Your job shifts from writing code to specifying intent and verifying results.
Chapter Lessons
| Lesson | Title | What You Do |
|---|---|---|
| 1 | From Reading to Specifying -- What Is TDG? | Understand the TDG loop by reading a complete worked example |
| 2 | Your First Failing Test | Learn return, -> float, and ... -- write your first stub and tests |
| 3 | AI Generates, You Verify | Prompt AI to implement your stub, verify with pytest and PRIMM |
| 4 | When AI Gets It Wrong | Handle a failed generation -- read the failure, re-prompt, verify again |
PRIMM-AI+ in This Chapter
Every lesson includes a PRIMM-AI+ Practice section where you apply the enhanced framework from Chapter 42. In this chapter, PRIMM-AI+ shifts from reading existing code to evaluating AI-generated code -- the verification loop that makes TDG work.
| Stage | What You Do | What It Builds |
|---|---|---|
| Predict [AI-FREE] | Read AI-generated code and predict whether tests pass, with a confidence score (1-5) | Calibrates your judgment on AI output |
| Run | Execute pytest and compare to your prediction | Creates the feedback loop |
| Investigate | Write a trace artifact before asking the AI for help | Makes your understanding visible |
| Modify | Change the test specification and predict the new outcome | Tests whether your understanding transfers |
| Make [Mastery Gate] | Complete a full TDG cycle independently -- stub, tests, prompt, verify | Each lesson has a specific mastery gate |
New Vocabulary
This chapter adds three Python words to the two you learned in Chapter 45 (def and assert):
| Word | Meaning | Example |
|---|---|---|
return | Hands a value back from a function | return celsius * 9 / 5 + 32 |
-> float | Promises what type the function returns | def convert(c: float) -> float: |
... | Intentionally empty body (a stub) | def convert(c: float) -> float: ... |
Five words total across two chapters. That is enough to specify, generate, and verify real Python functions.
Prerequisites
- Chapter 45: Reading Python -- You must be able to read type-annotated Python, predict output, and build trace tables. Every lesson in this chapter requires those skills.
- Chapter 44: The Development Environment -- You must have uv, pyright, ruff, pytest, and Git installed in your SmartNotes project.
- Chapter 16: Spec-Driven Development with Claude Code -- You must understand the SDD workflow: specification before implementation, verification after generation. TDG is SDD expressed in Python instead of English.
Examples in this chapter use Claude Code, but the TDG loop works with any AI coding assistant that can read your files and generate code -- GitHub Copilot, Cursor, Windsurf, or others. The loop is tool-agnostic: you write the specification, any AI generates, your tests verify.