TDD Skill for Claude Code

A structured, project-agnostic Test-Driven Development process for Claude Code.

Tests give Claude a self-verification loop -- the highest-leverage pattern for agentic coding. This skill wraps that insight in a repeatable process that follows Claude Code's Explore -> Plan -> Implement -> Commit workflow.

What It Does

When you invoke /tdd, Claude follows a 6-phase process:

Phase 1: Analysis        Understand the request, explore code, check standards
Phase 2: Planning        Decompose into chunks, dependency graph, get approval
Phase 3: Pre-Test        Write failing tests (or verify existing coverage)
Phase 4: Implementation  Write production code to make tests pass
Phase 5: Post-Test       Verify chunk tests pass, run full suite on last chunk
Phase 6: Quality         8-point checklist, post-implementation docs

Phases 3-5 repeat per chunk. Small features use a shortcut that skips chunking and planning (but still create a 1-chunk tracker).

When to Use It

Scope	Approach
Trivial (typo, rename, version bump)	Don't use this skill -- just ask Claude directly
Small (single-file logic, simple bug fix)	/tdd with small feature shortcut (1-chunk tracker)
Medium+ (multi-file, unfamiliar code)	/tdd full process
Large (cross-cutting, multi-session)	/tdd full process + session resets between chunks

Rule of thumb: If you can describe the diff in one sentence, skip the skill. If you need tests to verify correctness, use it.

Installation

1. Copy the skill into your project

# From your project root
mkdir -p .claude/skills/tdd
cp -r /path/to/tdd-skill/SKILL.md .claude/skills/tdd/
cp -r /path/to/tdd-skill/references/ .claude/skills/tdd/

Or clone and copy:

git clone https://github.com/openkash/ai-agent-tdd-skill.git /tmp/tdd-skill
mkdir -p .claude/skills/tdd
cp /tmp/tdd-skill/SKILL.md .claude/skills/tdd/
cp -r /tmp/tdd-skill/references/ .claude/skills/tdd/

Claude Code auto-discovers skills in .claude/skills/. Once copied, the skill appears in the / menu and Claude can invoke it automatically when relevant.

2. Create your PROJECT.md

Copy the template and fill in your project's details:

cp /tmp/tdd-skill/PROJECT.md .claude/skills/tdd/PROJECT.md

Or start from an example config:

# Pick your stack
cp /tmp/tdd-skill/project-configs/android-kotlin.md \
   .claude/skills/tdd/PROJECT.md

Edit PROJECT.md with your test commands, architecture rules, and conventions.

3. Use it

Invoke the skill directly:

/tdd implement the user search feature
/tdd fix the pagination bug
/tdd refactor auth to use OAuth2

Or let Claude invoke it automatically when you describe work that needs test verification:

I need to add rate limiting to the API endpoints. Research the
codebase first, then implement with tests.

File Structure

tdd-skill/
├── SKILL.md                     # Core TDD process (project-agnostic)
├── PROJECT.md                   # Template, copy and customize
├── references/
│   ├── chunk-template.md        # How to decompose features into chunks
│   ├── tracker-schema.md        # JSON tracker for all features
│   └── quality-checklist.md     # 8-point quality verification checklist
└── project-configs/             # Example PROJECT.md for common stacks
    ├── android-kotlin.md        # Android / Kotlin / Compose / Hilt
    ├── typescript-node.md       # TypeScript / Node.js / Jest or Vitest
    ├── python-pytest.md         # Python / pytest / FastAPI or Django
    └── rust-cargo.md            # Rust / Cargo

What Goes Where

Content	Location	Committed?
TDD process (universal)	SKILL.md	Yes
Project config (your stack)	PROJECT.md	Your choice
Chunk decomposition guide	references/chunk-template.md	Yes
Tracker schema	references/tracker-schema.md	Yes
Quality checklist	references/quality-checklist.md	Yes
Active tracker (work in progress)	Your docs directory	No (local)

Key Concepts

Chunks

Features get broken into independently testable implementation chunks. Each chunk has explicit dependencies, test files, and resume instructions so work can pick up where it left off. See chunk-template.md.

JSON Tracker

Every feature gets a JSON tracker file — even single-chunk ones. The tracker is a file-based artifact that survives context resets, ensuring any session can pick up where work stopped. See tracker-schema.md.

8-Point Quality Checklist

Applied twice: once to the plan (Phase 2.5, catching design bugs before code) and once after implementation (Phase 6). See quality-checklist.md.

Small Feature Shortcut

Single-file or few-file changes skip chunking and planning but still create a 1-chunk tracker. The process collapses to: Analysis -> Pre-Test -> Implement -> Post-Test -> Quality Verification.

Lessons Learned

The skill includes 18 lessons from real TDD sessions. Things like false positive tests, dead code left behind, constructor cascading breakage. Applied every time.

Customization

Adding Project-Specific Lessons

Add lessons to your PROJECT.md or append to your copy of SKILL.md in the Lessons Learned section. Keep the format:

19. **Your lesson title** --
    What happened, why it matters, what to do differently

Modifying the Quality Checklist

The 8 points are intentionally generic. Customize them in your PROJECT.md under "Standards to Verify" and "Blindspots to Check". The checklist references those sections.

Adjusting the Test Strategy Table

The test strategy table in Phase 3.1 maps chunk types to test approaches. If your project has additional conventions (snapshot tests for components, contract tests for APIs, etc.), add rows to your copy.

Origin

Extracted from an open source calendar app where it was used across RFC compliance work, CalDAV sync, and UI features. The project-specific parts were swapped out for a pluggable PROJECT.md so the core process works with any stack.

License

Apache License 2.0. See LICENSE.