This skill should be used when the user asks to "write tests first", "use TDD", "test-driven development", "red green refactor", "test first", "add unit tests before code", "write regression test first", "safe refactor with tests", or when TDD mode is active and the user makes any coding request that affects behavior (features, bugs, refactors).
This skill inherits all available tools. When active, it can use any tool Claude has access to.
examples/jest-tdd-cycle.mdexamples/pytest-tdd-cycle.mdreferences/frameworks.mdreferences/patterns.mdTransform coding behavior into strict Test-Driven Development practice. Enforce the Red→Green→Refactor cycle where no behavior-changing code is written without a failing test first.
TDD is not about testing—it is about design through tests. Tests drive the implementation, not the other way around.
┌─────────────────────────────────────────────────┐
│ │
│ RED: Write a failing test │
│ ↓ │
│ GREEN: Write minimal code to pass │
│ ↓ │
│ REFACTOR: Clean up while staying green │
│ ↓ │
│ (repeat) │
│ │
└─────────────────────────────────────────────────┘
Block any behavior-changing implementation without a failing test:
Warn and prompt for confirmation:
Coach and suggest without blocking:
Only proceed to refactor when all tests are green.
Present test results with progressive detail:
Tests: 12 passed, 3 failed (score: 0.80)
Failing:
- test_user_can_login
- test_validates_email_format
- test_handles_empty_input
Provide complete test runner output when user asks "show full output" or when debugging complex failures.
Default: 5 Red→Green iterations per request.
After 5 cycles without success:
Test file naming: *.test.ts, *.spec.ts, __tests__/*.ts
// RED: Write failing test first
describe('Calculator', () => {
it('should add two numbers', () => {
const calc = new Calculator();
expect(calc.add(2, 3)).toBe(5);
});
});
Run command detection: Check package.json for test script.
Test file naming: test_*.py, *_test.py, tests/
# RED: Write failing test first
def test_user_can_register():
user = User.register("test@example.com", "password123")
assert user.email == "test@example.com"
assert user.is_active is True
Run command detection: Check for pytest.ini, pyproject.toml, or setup.cfg.
For other frameworks (Go, JUnit, etc.):
Default patterns for files where hook blocks/warns:
src/**/*.ts, src/**/*.tsx, src/**/*.jsapp/**/*.py, lib/**/*.py*.go (excluding *_test.go)Files where writing is always allowed:
**/*.test.*, **/*.spec.***/__tests__/**tests/**, test/***_test.go, *_test.pyRead settings from .claude/tdd-dev.local.md:
testCommand: npm test
strictness: strict
maxIterations: 5
sourcePatterns:
- src/**/*.ts
testPatterns:
- **/*.test.*
Merge order: Global (~/.claude/tdd-dev.local.md) → Project → Command flags
For detailed patterns and advanced workflows:
references/patterns.md - Common TDD patterns and anti-patternsreferences/frameworks.md - Framework-specific test templates and commandsWorking examples in examples/:
examples/jest-tdd-cycle.md - Complete Jest TDD cycle walkthroughexamples/pytest-tdd-cycle.md - Complete Pytest TDD cycle walkthrough| Phase | Action | Validation |
|---|---|---|
| RED | Write failing test | Test fails for correct reason |
| GREEN | Minimal implementation | New test passes, no regressions |
| REFACTOR | Clean up code | All tests still pass |
| Mode | On Violation |
|---|---|
| Strict | Block write |
| Standard | Prompt confirmation |
| Relaxed | Show warning |