# Tdd

> Drive a portable red-green-refactor workflow for features, bug fixes, and changes to existing behavior. Use when implementing behavior with test-driven development, reproducing a bug as a failing test before fixing it, changing the semantics of existing code, or when the user asks for TDD, test-first, or red-green-refactor discipline.

- Skill: `shakacode/tdd` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add shakacode/tdd`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shakacode/tdd/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: shakacode (https://skillmd.com/u/shakacode)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/shakacode/tdd

---


# Test-Driven Development

<!-- Keep this skill in sync with `workflows/tdd.md`. -->

Memorable invocation: `$tdd`

Use this skill to move in small, verified behavior slices:

```text
RED -> GREEN -> REFACTOR -> repeat
```

Before writing or changing tests, mocks, or test helpers, apply
[Writing Good Tests](references/writing-good-tests.md).

## Core Loop

1. Choose one observable behavior.
   - For a bug fix, first express the reported failure as one failing regression test.
   - For a feature or behavior change, start with the smallest user-visible or public-interface behavior.
   - Prefer tests through public interfaces and real code paths over tests coupled to private implementation details.
   - Before writing the test body, name a realistic production break it should catch. If only an intentional source or private-structure change would fail it, redesign the test around observable behavior.
2. RED: write one failing test.
   - Use literal expected values or independently hand-checked fixtures when practical. Do not compute expectations through the implementation or helper under test, except in an explicitly named characterization test with independent evidence.
   - Run the new test with the repo's narrowest relevant test invocation. Start from `.agents/bin/test` when present, then narrow using the repo's test framework convention.
   - Confirm the test fails for the right reason: the missing behavior or reproduced bug.
   - If it fails because of a typo, missing import, bad fixture, or harness problem, fix the test setup before touching production code.
   - If it passes immediately, do not proceed to GREEN: the test describes existing behavior; tighten or replace it until you have watched the intended failure.
3. GREEN: write the smallest production change that makes that test pass.
   - Do not add production code before a failing test exists.
   - Do not add speculative behavior for future tests.
   - Rerun the same targeted test and confirm it passes.
4. REFACTOR: improve while green.
   - Remove duplication, clarify names, and simplify structure only with tests passing.
   - Rerun the targeted test after each meaningful refactor step.
5. Repeat with the next behavior.
   - Add one new failing test at a time.
   - Keep each cycle narrow enough that a failure clearly points to the current behavior.

## Guardrails

- Never refactor while RED.
- Never batch-write all tests before implementation; use vertical slices.
- Never claim a bug is fixed without evidence: prefer a regression test that failed before the fix and passes after it.
- Exact source, text, path, and mirror checks prove source or packaging invariants only. For a behavior claim, execute the artifact or pressure-test its consumer when practical.
- Preserve real side effects needed by the behavior. Mock only slow or external boundaries, use realistic complete doubles, and do not treat a mock's existence as behavioral proof.
- Before completion, choose a small finite set of realistic failure modes for the changed behavior and confirm the relevant test fails for them. This bounded mutation check needs no mutation-testing software.
- Only when a direct automated regression test is not practical, document why, then use the closest useful local verification through `.agents/bin/test` or the repo's documented manual surface to capture before and after behavior.
- Before handoff or PR creation, run `.agents/bin/validate` in addition to the targeted tests used during the loop.

## Before Pushing

- If the change affects a developer workflow, exercise that workflow with `.agents/bin/test` or the repo's relevant local verification rather than relying only on unit tests.
- If the change affects app-facing behavior, do minimal manual verification through the repo's relevant local app or manual-test surface when appropriate.
- Try to run the same relevant local tests that CI would run for the changed area before pushing, then run `.agents/bin/validate`.

## Done

The loop is complete when each observable behavior specified in the task or issue has passing test coverage, or documented before-and-after closest-useful verification only when a direct automated regression test is not practical, and the pre-push validation passes clean. Report the behaviors implemented, the tests added, any fallback verification rationale and before/after result, and the result of the pre-push validation.