Claude Code Test-Driven Development Skill

README.md

Test-Driven Development For Claude Code

This is a SKILL.md file for Claude Code and other agentic coding environments which teaches the assistant how to do test driven development. In my experience this is how you get production-quality, working, functional and polished code out of these things.

How To Use This

1. Install Claude Code
2. Download the attached SKILL.md file, and copy it to ~/.claude/skills/tdd/SKILL.md. (You may need to mkdir -p ~/.claude/skills/tdd first.)
3. Start Claude Code in a project directory.
4. Load the skill by typing /tdd

SKILL.md

name	test-driven-devel
description	Plan-and-test-first workflow discipline to follow BEFORE starting any coding task, milestone, or feature in a software project. Enforces the sequence: have a PLAN → break it into a TODO.md checklist → work items one at a time → nothing is "done" until it is documented and tested-passing → cap failed-fix attempts. Use this at the moment work begins on a programming project or a new milestone/feature within one — i.e. before writing implementation code — and refer back to it while working through the task list.
when_to_use	Trigger when about to begin implementation on a software project: starting a new project, milestone, feature, or sizable task; resuming coding work after planning; or any time the user says "let's start building / implementing / coding". Not for one-line edits, quick answers, or pure research/reading.
metadata	type version tags workflow 1.0.0 workflow tdd planning project-discipline

Test-Driven Development Workflow

Follow this discipline before and during any coding task, milestone, or feature. Do the steps in order. Don't skip ahead to writing implementation code.

1. Have a PLAN first

Never start implementing without a plan.

• If there is no plan yet, make one — this is what plan mode is for.
• Check the project docs first (DESIGN.md, PLAN.md, README.md, a prompts/ or docs/ folder): a plan may already be recorded there.
• The plan defines what and in what order; the TODO list (step 2) defines the concrete work.

2. Work from a TODO.md

• Turn the PLAN into a markdown checklist in TODO.md at the project root.
• Break the work into manageable tasks, and subtasks where a task is large. Record the hierarchy with a brief description per item.
• If TODO.md already exists, append to it rather than overwriting.

Example:

## Milestone: SVG path parse/serialize
- [ ] Tokenizer for the `d`-attribute grammar
  - [ ] Handle implicit repeated commands
  - [ ] Handle relative vs absolute
- [ ] Serializer (lossless round-trip)
- [ ] Tests: round-trip corpus + fuzz

3. Work the list one item at a time

• Go through the unfinished items in order.
• Complete an item fully, then check it off (- [x]) before moving to the next.
• Keep TODO.md current as the single source of truth for progress and blockers.

4. An item isn't "done" until it is documented AND tested-passing

Before checking an item off, it must have:

• Tests in tests/ that pass. First check the project docs for the required test framework and any conventions; otherwise follow what already exists in tests/ and use good judgement. At minimum, a smoke test that the new code builds/imports, is visible/exported, and works in its simplest form. Don't chase every edge case.
• Documentation where appropriate — docs/, README.md, DESIGN.md, REFERENCE.md, and doc comments on non-trivial code.

Effort guideline (rule of thumb, not a commandment): spend roughly 1/5 to 1/3 as much time on tests as on the feature code itself.

5. Cap failed-fix attempts — don't grind

When a build or test fails, it's your job to read the error, diagnose, and fix it. But when running in fully automatic mode:

• Make at most 3 attempts without forward progress on the same problem.
• "No forward progress" means the same failure persists with no new information.
• After that, stop and check in with the user. Explain what you tried, what the error is, and what you'd try next. Grinding through many blind attempts wastes tokens; escalation is the user's call.

---

Also honor the user's standing workflow rules: maintain DESIGN.md (specs, intent, architecture) for new projects/major features, and a CHANGELOG.md (dated, grouped Added/Changed/Fixed/Removed) updated after each significant piece of work.