adamayoung/TMDb / .claude/skills/canon-tdd
canon-tdd
VerifiedImplement features and fix bugs test-first, the Canon TDD way (test list → one test → make it pass → refactor → repeat). Use when implementing any new feature, endpoint, model, or method, fixing a bug, or executing a plan — write the test list and a failing test BEFORE production code.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.2 KB |
SKILL.md
View on GitHub---
name: canon-tdd
description: Implement features and fix bugs test-first, the Canon TDD way (test list → one test → make it pass → refactor → repeat). Use when implementing any new feature, endpoint, model, or method, fixing a bug, or executing a plan — write the test list and a failing test BEFORE production code.
---
# Canon TDD
Test-driven development the way Kent Beck describes as "Canon TDD", per
<https://adam-young.co.uk/blog/canon-tdd/>. CLAUDE.md mandates a TDD approach for
this package; this skill is the detailed how.
> **Red-Green-Refactor is the engine. The Test List is the steering wheel.**
## Agent behaviour contract
The point of this skill: do these by default, without being reminded.
1. **Start with a test list, and show it.** Before touching production code,
enumerate the behaviours and edge cases as a checklist and confirm it with the
user (or state it explicitly). This is the steering wheel — it defines "done".
2. **No production code before a failing test.** Write exactly **one** test,
run it, and watch it fail for the right reason. Never write the implementation
first and back-fill tests.
3. **One test at a time.** Do not convert the whole test list into code up front
— the first passing test often forces a design change that affects the rest.
4. **Refactor only on green**, and keep refactoring out of the make-it-pass step.
5. **Repeat until the test list is empty**, adding newly-discovered cases to the
list as you go.
## The five steps
1. **Write a test list** — every behavioural variant and edge case you can think
of, as a plain checklist. Not code yet. It's a living list: add to it whenever
implementation reveals a new case.
2. **Write a test** — pick the next item and write one real, automated test:
setup, invocation, and **assertions**. Define *what* the system does and *how
it's invoked* — not how it works inside. Run it; confirm it fails — and
**state the failure**: quote the failing assertion/message and check it is
the *expected* reason. (For brand-new API the first red is normally a
compile error — the symbol doesn't exist yet; that is expected. Stub the
minimal declaration and re-run so the red becomes the failing assertion.)
A compile error in *existing* code, a missing import, or an unrelated
crash is a red for the wrong reason — it proves nothing about the
behaviour, so fix the test and re-run until it is red for the right reason.
3. **Make it pass** — change the system to satisfy that test with the simplest
thing that works. Nothing more; resist solving items still on the list.
4. **Optionally refactor** — improve names, structure, and duplication while every
test stays green. Skip if there's nothing to improve.
5. **Repeat** — next item, until the list is empty.
## Separate interface from implementation
A test fixes a *decision* about the interface (the call shape, inputs, outputs)
and should be silent about the internals. Tests that assert on private mechanics
break under refactoring and defeat step 4.
## Anti-patterns (don't)
- **Tests without assertions** — a test that invokes but asserts nothing proves
nothing.
- **Pre-converting the whole list to code** — write one test, learn, then the
next. Batching tests locks in design decisions before you've learned anything.
- **Mixing refactor into make-it-pass** — keep "make it work" and "make it clean"
as separate steps on either side of green.
- **Premature abstraction from duplication** — a little duplication across two
green tests is fine; abstract when the shape is clear, not at the first repeat.
## In this codebase (TMDb)
Apply the loop with the project's tooling and conventions:
- **Framework:** Swift Testing — `@Suite`, `@Test`, `#expect`, `#require`. Never
force-unwrap in tests; unwrap optionals with `try #require(...)`.
- **Run tests via the delegated skills**, not `make` directly, so output stays
out of context: `/test` (unit) and `/integration-test` (live API). Re-run after
each red→green and after refactoring.
- **Both layers are required for new behaviour.** Unit tests with JSON fixtures
AND integration tests against the live API — put both kinds of items on the
test list from the start.
- **Models / new endpoints:** when the test list involves decoding, the fixture
must exercise **every** decode branch (all N optional appended properties, plus
a paired "without appended data" test that asserts they're `nil`). Use the TMDb
MCP server (`mcp__tmdb__*`) to fetch **real** API responses for fixtures rather
than inventing JSON — see `.claude/docs/tmdb-api.md` → "Workflow for New
Endpoints".
- **Bug fixes:** the first item on the list is a test that **reproduces the bug**
(red), then the fix (green) — never fix first.
- **New public API:** the test list should include the doc/DocC and README
updates as completion items, even though they aren't tests (per the
`document-swift` skill's consistency checklist).
## When NOT to use it
Pure refactors with existing coverage, formatting, config/CI edits, and docs-only
changes don't start from a new failing test — keep the existing tests green
instead. TDD is for *new behaviour* and *bug fixes*.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |