# Tdd

> Guide implementation using a strict test-driven development loop, focusing on interface design, behavior-first tests, and iterative red-green-refactor cycles to improve code quality and structure.

- Skill: `spicy-samson/tdd` (Agent Skill)
- Install (CLI): `npx skillmds@latest add spicy-samson/tdd`
- Raw SKILL.md: https://api.skillmd.com/api/skills/spicy-samson/tdd/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: spicy-samson (https://skillmd.com/u/spicy-samson)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/spicy-samson/tdd

---


# TDD (Test-Driven Development)

## Intent

Use this skill when implementing or changing behavior where correctness, safety, or long-term maintainability are important.  

The goal is to drive design and implementation **from tests first**, using a red–green–refactor loop.

## Core Principles

1. **Behavior first**  
   - Start from externally visible behavior or API contracts.  
   - Tests describe “what” the system should do, not internal details.

2. **Interfaces for testability**  
   - Prefer clear, narrow interfaces over exposing internals just to make testing easier.  
   - Group related behavior into deeper modules with thin public surfaces.

3. **Strict red–green–refactor loop**  
   - Red: write a failing test that expresses the next behavior.  
   - Green: write the simplest implementation that makes the test pass.  
   - Refactor: improve design with tests staying green.

## Workflow

1. **Clarify the behavior**
   - Restate the change in terms of observable behavior (inputs, outputs, side effects).  
   - Confirm with the user if anything is ambiguous or underspecified.

2. **Locate test boundaries**
   - Explore the codebase to find existing test patterns and natural seams (modules, services, handlers).  
   - Choose the **highest level** that gives good feedback without being brittle (often a service or use-case layer, not individual helpers).

3. **Design or refine interfaces**
   - Sketch the function, method, or module interface(s) needed.  
   - Ensure they are testable: deterministic inputs/outputs, minimized global state, clear dependencies (passed in, not hidden).

4. **Write the first test (Red)**
   - Add or modify a test that:
     - Fails for the right reason initially.  
     - Uses realistic data and names.  
     - Captures one concrete behavior (happy path or key edge case).

5. **Implement just enough code (Green)**
   - Modify production code minimally to make the new test pass.  
   - Avoid over-generalizing or implementing future features.

6. **Refactor**
   - With tests green, look for:  
     - Duplication across tests or code  
     - Overly complex functions or conditionals  
     - Poorly named or misplaced modules  
   - Refactor in small steps, keeping tests passing after each.

7. **Repeat**
   - Add the next most important test:  
     - New scenario, edge case, or failure mode.  
   - Continue the red–green–refactor loop until the behavior is well covered and design feels stable.

## Style Guidelines

- Prefer **fewer, higher-value tests** that capture behavior over many mechanical tests of tiny details.  
- Use realistic naming and examples to keep tests readable.  
- Use mocks or fakes sparingly; when you mock heavily, consider whether the module boundaries are in the right place.  
- When refactoring, be explicit about which changes are purely structural vs. behavioral.