Chapter 46: Your First TDG Cycle
James has been reading code for two chapters. Predicting output, building trace tables, catching bugs. He knows what Python does when he sees it. But he has not written a single line that tells Python what to do.
Emma closes her laptop. "You have spent two chapters learning to read. Now you learn to specify." She says it like the distinction matters. It does. Reading is verification. Specifying is intent. This chapter is where the two meet.
In Chapter 45, you learned to read Python: predicting output, building trace tables, and catching 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), described 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 ... then 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 | Claude Code Tool |
|---|---|---|
| Predict [AI-FREE] | Read AI-generated code and predict whether tests pass, with a confidence score (1-5). Press Shift+Tab for Plan Mode. | Plan Mode protects prediction |
| Run | Press Shift+Tab to exit Plan Mode. Run uv run pytest -v yourself and compare to your prediction. | You run it, not Claude Code |
| Investigate | Write a trace artifact before asking. Then use /investigate @file for Socratic questions. | /investigate probes mechanics |
| Modify | Change the test specification and predict the new outcome before running. | You edit, Claude Code reviews |
| Make [Mastery Gate] | Complete a full TDG cycle independently: stub, tests, prompt, verify. | Your work, Claude Code generates |
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.
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.