TDD Workflow
Red-green-refactor with a gate that blocks code before its failing test exists — light enough for a single function.
v1.0.0 · ~608 tokens · ⬇ 0 · Updated July 6, 2026
What it does
Enforces test-before-code: one behavior at a time, confirm the test fails for the right reason, minimum code to pass, refactor only on green. Includes an automatable gate (new exported function with no referencing test → fail) and an honest 'when to skip TDD' section. Refuses the anti-pattern of editing the test to match wrong code.
Example uses
Test-drive a new utility
You are building new logic and want the tests to define the behavior before the implementation exists.
Test-drive a slugify() utility for our blog engine: lowercase, hyphen-separated, strips emoji, transliterates accented characters, caps length at 80. Red first — one failing test per behavior, show me it fails for the right reason, then the minimum code to go green, then refactor on green.Fix a bug test-first
A bug needs fixing and you want a failing test that pins it down before the fix goes in.
Users report our rate limiter lets 11 requests through when the limit is 10, but only right after a window resets. TDD the fix: write the failing test that reproduces the off-by-one at the window boundary, confirm it fails red, then fix the code — and if the test disagrees with the implementation, suspect the code first.Build pricing logic red-green
The logic is edge-case heavy — money, tiers, stacking rules — which is exactly where test-first pays off.
We're adding tiered discounts to our Node checkout: 5% over $100, 10% over $500, plus stacking rules with coupon codes. Build it strictly red-green-refactor, one behavior per loop, and don't write a single implementation line before a failing test points at it.Install
# 1. Create the skill folder in your Claude setup mkdir -p ~/.claude/skills/tdd-workflow # 2. Download SKILL.md into it (or move the file you just downloaded) # → ~/.claude/skills/tdd-workflow/SKILL.md # 3. Claude Code auto-discovers it on next launch.
Inside the skill
---
name: tdd-workflow
description: Test-driven development with a real red-green-refactor gate. Use when building a new function/feature/bugfix and the user wants tests to drive the code ("do this TDD", "write the test first", "test-drive this"). Enforces test-before-code without the ceremony.
---
# TDD Workflow
Red → Green → Refactor, with a gate that actually blocks. Lightweight enough to use on
a single function, not just a whole feature.
## The loop (one behavior at a time)
1. **RED** — write ONE failing test for the next smallest behavior. Run it. Confirm it
fails *for the right reason* (assertion, not import error). A test that never failed
proves nothing.
2. **GREEN** — write the minimum code to pass. Not the elegant version — the passing
version. Run the test. It passes.
3. **REFACTOR** — now improve names/structure with the test as your safety net. Run
again. Still green. Only refactor on green.
4. Repeat for the next behavior.
## The gate (enforce, don't trust)
Before writing any implementation line, the matching test must exist AND have been run
red. If you're about to write code with no failing test pointing at it — stop, back up,
write the test. This is the whole discipline; everything else is style.
Practical gate you can automate: block the commit if a new exported function has no
referencing test file. Rough check — new `export function foo` with zero `foo(` in any
`*.test.*`/`*.spec.*` → fail with "no test drives foo".
## What to test (and not)
- Test **behavior and contracts**: inputs → outputs, edge cases, error paths.
- Test the **bug** before fixing it: a failing test that reproduces it, then the fix.
- Don't test framework internals, getters, or the language. Don't test implementation
details that lock in structure (test what it does, not how).
## Anti-patterns (refuse)
- Writing the code, then a test that just mirrors it (that's not TDD, it's decoration).
- **Editing the test to match a wrong implementation.** The test encodes intent; if it's
failing, suspect the code first.
- Giant tests covering five behaviors — one behavior, one test, one reason to fail.
- Skipping RED "because it's obviously right" — obviously-right code fails tests weekly.
## When to skip TDD (be honest)
Throwaway spikes, exploratory prototypes, pure config. Say so out loud rather than
faking a test afterward. Convert the spike with tests once the design is known.
Changelog
- v1.0.02026-07-03Initial clean-room write.
Frequently asked questions
Is TDD Workflow free?
Yes. TDD Workflow is free to download and MIT-licensed.
Where do I install TDD Workflow?
Place the SKILL.md file in ~/.claude/skills/tdd-workflow/ and Claude Code auto-discovers it on next launch.
How many tokens does TDD Workflow use?
About 608 tokens — it is designed to be token-lean.
We're developers and SaaS builders who use these tools daily in production. Every review comes from hands-on experience building real products — DealPropFirm, ThePlanetIndicator, PropFirmsCodes, and many more. We don't just review tools — we build and ship with them every day.
Written and tested by developers who build with these tools daily.