tdd-rules

TDD Rules

When loaded

/coder loads this skill unconditionally at startup (alongside coder-rules, spec-check, and the LANGUAGE-resolved tdd-shapes/<LANGUAGE>.md). RGR is the default Phase 2 cycle for every implementation run — no plan-level marker required. Plans MAY still include a ## TDD heading for human-reader emphasis, but the heading is NOT a load predicate (deprecated as a contract; tolerated as prose).

The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Wrote code before the test? Delete it. Implement fresh from a failing test run.

Red-Green-Refactor cycle

For EACH unit of behaviour:

1. RED — write ONE failing test. Run the project test command ({TEST_CMD}). MUST FAIL. If it passes, the test does not exercise new behaviour — revise.
2. GREEN — minimum code to make that one test pass. No extras, no optimisation, no refactor. Hard-coded values acceptable.
3. REFACTOR — improve structure (naming, duplication, helpers) WITHOUT changing behaviour. Tests stay green.

Return to RED for the next behaviour.

Reference shapes — per-language test idioms

Concrete syntax for each step lives in tdd-shapes/<LANGUAGE>.md:

LANGUAGE	File	Idiom
go	tdd-shapes/go.md	*testing.T, table-driven t.Run, testify
python	tdd-shapes/python.md	pytest, @pytest.mark.parametrize, fixtures
typescript	tdd-shapes/typescript.md	Jest/Vitest describe/it, it.each
rust	tdd-shapes/rust.md	#[test], assert_eq!, rstest
java	tdd-shapes/java.md	JUnit 5 @Test, assertEquals, @ParameterizedTest
any other / unset	tdd-shapes/_default.md	pseudocode (no language commitment)

Selector lives in examples.md (reference_shapes block, mirrors planner-rules/examples.md).

Cascade resolution (single source of truth)

Resolution order — highest precedence first:

1. PROJECT-KNOWLEDGE.md → LANGUAGE matches one of {go, python, typescript, rust, java} → load matching tdd-shapes/<LANGUAGE>.md.
2. LANGUAGE slot is unset/empty (PROJECT-KNOWLEDGE.md missing OR slot empty) → fall back to CLAUDE.md Language Profile (kit-default = Go) → load tdd-shapes/go.md. Kit-dogfood C5 constraint preserved.
3. LANGUAGE is set but does NOT match the 5-language enum (e.g., ruby, kotlin, kit's own "config-as-code") → load tdd-shapes/_default.md silently AND emit a consolidated NIT in coder handoff deviations_from_plan array (mirrors CG1 SKIP idiom).

/coder startup step "Load TDD skill (unconditional)" duplicates this cascade — the two narratives MUST stay in sync (T3.6 single source of truth).

Integration with /coder Parts

/coder implements each Part with interleaved tests by default — RED → GREEN → REFACTOR per behaviour. Tests are NOT a separate final Part; they are woven into each Part. Layer-dependency order from the plan is preserved either way.

Plans that still ship a Part N: Tests block (e.g. legacy plans authored before TDD-always-on, or plans following the documentation pattern in .claude/templates/plan-template.md L92-124) are tolerated — /coder will absorb the listed test cases into the per-Part RGR cycles rather than batching them into a final separate Part.

Rules

• NEVER write production code without a failing test (RED must precede GREEN)
• ONE test at a time — do NOT batch multiple test cases before implementing
• Run tests after EVERY step (RED: must fail, GREEN: must pass, REFACTOR: must pass)
• Table-driven / parameterised tests: add cases incrementally, not all at once
• Test names: descriptive — explain the behaviour being verified, not just test1 / TestFoo
• Mock interfaces, not implementations
• Race-detection: use the project's race-detector flag when the package has concurrency primitives

See tdd-shapes/<LANGUAGE>.md + tdd-shapes/INVARIANTS.md for patterns; references/coder-integration.md for rationalisations + red flags.