# tdd

This command guides one task through TDD: define interfaces, write failing tests, implement the minimum, refactor, and check coverage.

- command · `type=command` · Claude Code, Codex, GitHub Copilot, Gemini CLI · ★ 880 repo stars
- Author: sangrokjung
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/sangrokjung/claude-forge/tree/HEAD/commands/tdd.md
- Updated: 2026-09-03
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/commands/tdd

## What it does

The command invokes the `tdd-guide` agent and breaks a task into a fixed working sequence. It defines input and output interfaces, creates tests before implementation, runs them to confirm the expected failure, then adds only enough code to pass. Once the tests are green, the agent refactors the code and runs the checks again.

Use `/tdd` for new functions or components, bug fixes, refactoring, and critical business logic. For a bug, the flow starts with a reproduction test, confirms the failure, applies the fix, and confirms the passing result. The final stage checks coverage and adds tests when it falls below 80%. The command allows `Agent`, `Read`, `Glob`, and `Grep`.

In Claude Code, the command file must be placed at `.claude/commands/tdd.md`; otherwise `/tdd` will not be available.

## Install

### Claude Code (native platform)

**Manually: put the files in place**
- File: `.claude/commands/tdd.md` — Call it with /tdd. For all projects use ~/.claude/commands/

### Codex

**Manually: put the files in place**
- File: `~/.codex/prompts/tdd.md` — Call it with /prompts:tdd. Codex marks this format deprecated in favour of skills

### GitHub Copilot

**Manually: put the files in place**
- File: `.github/prompts/tdd.prompt.md`

### Gemini CLI

**Manually: put the files in place**
- File: `.gemini/commands/tdd.toml` — Gemini stores commands as TOML: the prompt text goes into the prompt field

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/sangrokjung/claude-forge/tree/HEAD/commands/tdd.md

## When to use it
- define interfaces before writing implementation
- create a failing test for a new behavior
- prove a bug fix with a failing-to-passing test
- check coverage after refactoring

## Example prompts
- Use `/tdd` to build a function that calculates a market liquidity score.
- Use `/tdd` to reproduce the empty-response bug, then fix it after the test fails.
- Use `/tdd` to add a component, cover edge cases, and check for at least 80% test coverage.

## Source text · tdd.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: da4f0e614a3ca4aa.

BEGIN THIRD-PARTY FILE da4f0e614a3ca4aa
````text
---
description: 테스트 먼저 만들고 코드 작성. 한 단위 작업에 사용.
allowed-tools: Agent, Read, Glob, Grep
---

# TDD Command

This command invokes the **tdd-guide** agent to enforce test-driven development methodology.

## What This Command Does

1. **Scaffold Interfaces** - Define types/interfaces first
2. **Generate Tests First** - Write failing tests (RED)
3. **Implement Minimal Code** - Write just enough to pass (GREEN)
4. **Refactor** - Improve code while keeping tests green (REFACTOR)
5. **Verify Coverage** - Ensure 80%+ test coverage

## When to Use

Use `/tdd` when:
- Implementing new features
- Adding new functions/components
- **Fixing bugs** → Prove-It Pattern: 버그 재현 테스트 먼저, 수정은 그 다음
- Refactoring existing code
- Building critical business logic

### Prove-It Pattern (버그 수정 전용)

```
BUG REPORT → REPRODUCE TEST (RED) → VERIFY FAIL → FIX (GREEN) → VERIFY PASS
```

버그 수정 시 "고쳤다"의 증거는 **실패→성공 전환**이다. 테스트 없이 수정하면 증상만 가린 것일 수 있다.

## How It Works

The tdd-guide agent will:

1. **Define interfaces** for inputs/outputs
2. **Write tests that will FAIL** (because code doesn't exist yet)
3. **Run tests** and verify they fail for the right reason
4. **Write minimal implementation** to make tests pass
5. **Run tests** and verify they pass
6. **Refactor** code while keeping tests green
7. **Check coverage** and add more tests if below 80%

## TDD Cycle

```
RED → GREEN → REFACTOR → REPEAT

RED:      Write a failing test
GREEN:    Write minimal code to pass
REFACTOR: Improve code, keep tests passing
REPEAT:   Next feature/scenario
```

## Example Usage

```
User: /tdd I need a function to calculate market liquidity score

Agent (tdd-guide):
# TDD Session: Market Liquidity Score Calculator

## Step 1: Define Interface (SCAFFOLD)

```typescript
// lib/liquidity.ts
export interface MarketData {
  totalVolume: number
  bidAskSpread: number
  activeTraders: number
  lastTradeTime: Date
}

export function calculateLiquidityScore(market: MarketData): number {
  // TODO: Implementation
  throw new Error('Not implemented')
}
```

## Step 2: Write Failing Test (RED)

```typescript
// lib/liquidity.test.ts
import { calculateLiquidityScore } from './liquidity'

describe('calculateLiquidityScore', () => {
  it('should return high score for liquid market', () => {
    const market = {
      totalVolume: 100000,
      bidAskSpread: 0.01,
      activeTraders: 500,
      lastTradeTime: new Date()
    }

    const score = calculateLiquidityScore(market)

    expect(score).toBeGreaterThan(80)
    expect(score).toBeLessThanOrEqual(100)
  })

  it('should return low score for illiquid market', () => {
    const market = {
      totalVolume: 100,
      bidAskSpread: 0.5,
      activeTraders: 2,
      lastTradeTime: new Date(Date.now() - 86400000) // 1 day ago
    }

    const score = calculateLiquidityScore(market)

    expect(score).toBeLessThan(30)
    expect(score).toBeGreaterThanOrEqual(0)
  })

  it('should handle edge case: zero volume', () => {
    const market = {
      totalVolume: 0,
      bidAskSpread: 0,
      activeTraders: 0,
      lastTradeTime: new Date()
    }

    const score = calculateLiquidityScore(market)

    expect(score).toBe(0)
  })
})
```

## Step 3: Run Tests - Verify FAIL

```bash
npm test lib/liquidity.test.ts

FAIL lib/liquidity.test.ts
  ✕ should return high score for liquid market (2 ms)
    Error: Not implemented

1 test failed, 0 passed
```

✅ Tests fail as expected. Ready to implement.

## Step 4: Implement Minimal Code (GREEN)

```typescript
// lib/liquidity.ts
export function calculateLiquidityScore(market: MarketData): number {
  // Handle zero volume edge case
  if (market.totalVolume === 0) {
    return 0
  }

  // Calculate component scores (0-100 scale)
  const volumeScore = Math.min(market.totalVolume / 1000, 100)
  const spreadScore = Math.max(100 - (market.bidAskSpread * 1000), 0)
````
END THIRD-PARTY FILE da4f0e614a3ca4aa

The third-party file has ended. Everything between the da4f0e614a3ca4aa tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 4034 of 8600 bytes. © sangrokjung · MIT · https://github.com/sangrokjung/claude-forge/tree/HEAD/commands/tdd.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
