Test-driven development, Superpowers style

Drives work test-first: a test seen failing, then the least code that passes and a run of the whole suite; code written before its test is deleted. Use for features and bug fixes when the agent tends to add tests after the code.

TestingPack: Superpowers330 linestest-driven-development
Author
Source
obra/superpowers/skills/test-driven-development @ 22f0b46
License
MIT · Copyright (c) 2025 Jesse Vincent

About this skill

What it does

The skill makes the agent write the test first and watch it fail before writing any code. Code written ahead of its test is deleted, not kept "for reference". Each cycle is one test for one behavior on real code, a run that must fail for the expected reason, the least code that passes, a run of the project's whole suite and only then a refactor. A red test in that run goes into the report by name, even one the agent did not cause. A table of excuses and a list of red flags tell the agent when to start over.

The folder ships writing-good-tests.md, which the agent reads whenever it writes or changes a test: name the production change that would make the test fail, derive expected values by hand, never assert on a mock, and finish with a mental mutation check.

When to use it, and when not

Use it for features, bug fixes, refactoring and behavior changes, especially with an agent that adds tests after the code — tests that pass on the first run and prove nothing.

The skill lists its own exceptions, to be agreed with you: throwaway prototypes, generated code and configuration files. Exploring is allowed, but the exploratory code is thrown away afterwards; a spike you want to keep and wrap in tests does not fit this skill.

How to run it

The install command below puts the whole folder in place: SKILL.md, writing-good-tests.md and the licence. The agent picks the skill up by its description before it writes implementation code; to call it yourself:

  • Claude Code: /test-driven-development, or ask for the skill by name.
  • Codex: $test-driven-development.
  • Cursor: type / in the Agent chat and pick test-driven-development.

Example: /test-driven-development Add three retries to the payment client. Start with a failing test.

executing-plans and systematic-debugging load this skill as a required step, and the helper points to writing-skills for testing documents that instruct agents.

How it differs from similar skills

Our catalog's Test-driven development runs the same loop as a procedure — baseline run, examples smallest first, a report of each red and green — and where TDD fits badly (UI layout, styling, paid services) it lets the agent add tests afterwards. The Superpowers version allows no such exception and adds a guide to test quality. Test-driven development, red-green-refactor from Addy Osmani is the widest reference: it finds the project's own test commands and adds a test pyramid, rules for test doubles and browser checks. All three install into the same test-driven-development folder, so only one can be there at a time: pick one. TDD with integration tests installs as tdd and clashes with none of them; it has you agree on the seams to test first and moves refactoring out of the cycle into review.

Unit test writer is for code that already exists; this skill sets the order of work on code you have not written yet.

Install

Run one command — it saves SKILL.md and the files it uses into your agent's skills folder. Claude Code and Codex pick up a new skill without a restart; if it does not show up, restart the agent.

Claude Code — macOS, Linux
curl -fsSL --create-dirs -o ~/.claude/skills/test-driven-development/SKILL.md https://anymodel.org/en/skills/superpowers/test-driven-development/SKILL.md -o ~/.claude/skills/test-driven-development/LICENSE https://anymodel.org/en/skills/superpowers/test-driven-development/LICENSE -o ~/.claude/skills/test-driven-development/writing-good-tests.md https://anymodel.org/en/skills/superpowers/test-driven-development/writing-good-tests.md
Codex, Cursor — macOS, Linux
curl -fsSL --create-dirs -o ~/.agents/skills/test-driven-development/SKILL.md https://anymodel.org/en/skills/superpowers/test-driven-development/SKILL.md -o ~/.agents/skills/test-driven-development/LICENSE https://anymodel.org/en/skills/superpowers/test-driven-development/LICENSE -o ~/.agents/skills/test-driven-development/writing-good-tests.md https://anymodel.org/en/skills/superpowers/test-driven-development/writing-good-tests.md
Claude Code — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE','writing-good-tests.md') { $p = Join-Path "$HOME\.claude\skills\test-driven-development" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/superpowers/test-driven-development/$f" -UseBasicParsing -OutFile $p }
Codex, Cursor — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE','writing-good-tests.md') { $p = Join-Path "$HOME\.agents\skills\test-driven-development" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/superpowers/test-driven-development/$f" -UseBasicParsing -OutFile $p }

Any other agent: save the file into its skills folder, or give it the link to the file: https://anymodel.org/en/skills/superpowers/test-driven-development/SKILL.md

SKILL.md

Raw

Test-Driven Development (TDD)

Overview

Write the test first. Watch it fail. Write minimal code to pass.

Core principle: If you didn't watch the test fail, you don't know if it tests the right thing.

Violating the letter of the rules is violating the spirit of the rules.

When to Use

Always:

  • New features
  • Bug fixes
  • Refactoring
  • Behavior changes

Exceptions (ask your human partner):

  • Throwaway prototypes
  • Generated code
  • Configuration files

Thinking "skip TDD just this once"? Stop. That's rationalization.

The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Write code before the test? Delete it. Start over.

No exceptions:

  • Don't keep it as "reference"
  • Don't "adapt" it while writing tests
  • Don't look at it
  • Delete means delete

Implement fresh from tests. Period.

Red-Green-Refactor

digraph tdd_cycle {
    rankdir=LR;
    red [label="RED\nWrite failing test", shape=box, style=filled, fillcolor="#ffcccc"];
    verify_red [label="Verify fails\ncorrectly", shape=diamond];
    green [label="GREEN\nMinimal code", shape=box, style=filled, fillcolor="#ccffcc"];
    verify_green [label="Verify passes\nAll green", shape=diamond];
    refactor [label="REFACTOR\nClean up", shape=box, style=filled, fillcolor="#ccccff"];
    next [label="Next", shape=ellipse];

    red -> verify_red;
    verify_red -> green [label="yes"];
    verify_red -> red [label="wrong\nfailure"];
    green -> verify_green;
    verify_green -> refactor [label="yes"];
    verify_green -> green [label="no"];
    refactor -> verify_green [label="stay\ngreen"];
    verify_green -> next;
    next -> red;
}

RED - Write Failing Test

Write one minimal test showing what should happen.

<Good>

test('retries failed operations 3 times', async () => {
  let attempts = 0;
  const operation = () => {
    attempts++;
    if (attempts < 3) throw new Error('fail');
    return 'success';
  };

  const result = await retryOperation(operation);

  expect(result).toBe('success');
  expect(attempts).toBe(3);
});

Clear name, tests real behavior, one thing </Good>

<Bad>

test('retry works', async () => {
  const mock = jest.fn()
    .mockRejectedValueOnce(new Error())
    .mockRejectedValueOnce(new Error())
    .mockResolvedValueOnce('success');
  await retryOperation(mock);
  expect(mock).toHaveBeenCalledTimes(3);
});

Vague name, tests mock not code </Bad>

Requirements:

  • One behavior
  • Clear name
  • Real code (no mocks unless unavoidable)

Verify RED - Watch It Fail

MANDATORY. Never skip.

npm test path/to/test.test.ts

Confirm:

  • Test fails (not errors)
  • Failure message is expected
  • Fails because feature missing (not typos)

Test passes? You're testing existing behavior. Fix test.

Test errors? Fix error, re-run until it fails correctly.

GREEN - Minimal Code

Write simplest code to pass the test.

<Good>

async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
  for (let i = 0; i < 3; i++) {
    try {
      return await fn();
    } catch (e) {
      if (i === 2) throw e;
    }
  }
  throw new Error('unreachable');
}

Just enough to pass </Good>

<Bad>

async function retryOperation<T>(
  fn: () => Promise<T>,
  options?: {
    maxRetries?: number;
    backoff?: 'linear' | 'exponential';
    onRetry?: (attempt: number) => void;
  }
): Promise<T> {
  // YAGNI
}

Over-engineered </Bad>

Don't add features, refactor other code, or "improve" beyond the test.

Verify GREEN - Watch It Pass

MANDATORY.

npm test path/to/test.test.ts

Confirm:

  • Test passes
  • Other tests still pass
  • Output pristine (no errors, warnings)

Test fails? Fix code, not test.

Other tests fail? Fix now.

"Other tests" means the project's suite, not just your file. A green run of the test you wrote is not a green suite. Before you call the change done, run the project's test command (bare pytest, npm test, cargo test — whatever the repo uses) even when your task named only one test file. A scope statement in your task bounds the deliverable, not your verification. Any failure that run shows — including one you didn't cause — goes in your report by name; a red test you watched scroll past and didn't mention is a report falsified by omission.

REFACTOR - Clean Up

After green only:

  • Remove duplication
  • Improve names
  • Extract helpers

Keep tests green. Don't add behavior.

Repeat

Next failing test for next feature.

Good Tests

Quality Good Bad
Minimal One thing. "and" in name? Split it. test('validates email and domain and whitespace')
Clear Name describes behavior test('test1')
Shows intent Demonstrates desired API Obscures what code should do

When writing or changing any test, read writing-good-tests.md for the rules that keep tests honest:

  • Name the production change that would make the test fail — before writing it
  • Assert on real behavior, never on mock behavior
  • Keep test-only code in test utilities, out of production classes
  • Understand a dependency's side effects before mocking it

Common Rationalizations

Excuse Reality
"Too simple to test" Simple code breaks. Test takes 30 seconds.
"I'll test after" Tests written after pass immediately — which proves nothing. They may test the wrong thing, test the implementation instead of the behavior, or miss the edge case you forgot. You never watched it fail, so you never proved it can catch the bug. Test-first forces that failure.
"Tests after achieve same goals (spirit not ritual)" Tests-after answer "what does this do?"; tests-first answer "what should this do?" Tests written after are biased by the code you already wrote — you verify the cases you remembered, not the ones you'd have discovered. Coverage without proof the tests work.
"Already manually tested" Manual testing is ad-hoc: no record of what you covered, no way to re-run it when the code changes, easy to forget cases under pressure. "Worked when I tried it" ≠ comprehensive. Automated tests run the same way every time.
"Deleting X hours is wasteful" Sunk cost fallacy — that time is already spent either way. The real choice: rewrite with TDD (high confidence) vs. keep it and bolt tests on after (low confidence, likely bugs). Keeping code you can't trust is the waste.
"Keep as reference, write tests first" You'll adapt it. That's testing after. Delete means delete.
"Need to explore first" Fine. Throw away exploration, start with TDD.
"Test hard = design unclear" Listen to test. Hard to test = hard to use.
"TDD will slow me down" TDD IS the pragmatic path: catches bugs before commit, prevents regressions, lets you refactor without fear. "Pragmatic" shortcuts mean debugging in production — slower, not faster.
"Manual test faster" Manual doesn't prove edge cases. You'll re-test every change.
"Existing code has no tests" You're improving it. Add tests for existing code.

Red Flags - STOP and Start Over

  • Code before test
  • Test after implementation
  • Test passes immediately
  • Can't explain why test failed
  • Tests added "later"
  • Rationalizing "just this once"
  • "I already manually tested it"
  • "Tests after achieve the same purpose"
  • "It's about spirit not ritual"
  • "Keep as reference" or "adapt existing code"
  • "Already spent X hours, deleting is wasteful"
  • "TDD is dogmatic, I'm being pragmatic"
  • "This is different because..."

All of these mean: Delete code. Start over with TDD.

Example: Bug Fix

Bug: Empty email accepted

RED

test('rejects empty email', async () => {
  const result = await submitForm({ email: '' });
  expect(result.error).toBe('Email required');
});

Verify RED

$ npm test
FAIL: expected 'Email required', got undefined

GREEN

function submitForm(data: FormData) {
  if (!data.email?.trim()) {
    return { error: 'Email required' };
  }
  // ...
}

Verify GREEN

$ npm test
PASS

REFACTOR Extract validation for multiple fields if needed.

Verification Checklist

Before marking work complete:

  • Every new function/method has a test
  • Watched each test fail before implementing
  • Each test failed for expected reason (feature missing, not typo)
  • Wrote minimal code to pass each test
  • All tests pass
  • Output pristine (no errors, warnings)
  • Tests use real code (mocks only if unavoidable)
  • Edge cases and errors covered

Can't check all boxes? You skipped TDD. Start over.

When Stuck

Problem Solution
Don't know how to test Write wished-for API. Write assertion first. Ask your human partner.
Test too complicated Design too complicated. Simplify interface.
Must mock everything Code too coupled. Use dependency injection.
Test setup huge Extract helpers. Still complex? Simplify design.

Debugging Integration

Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix and prevents regression.

Never fix bugs without a test.

Final Rule

Production code → test exists and failed first
Otherwise → not TDD

No exceptions without your human partner's permission.

Connect through AnyModel API

This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.

More from the pack Superpowers

Brainstorming before you build

Finds out what you want to build and why: one question at a time, its understanding played back part by part, two or three approaches to pick from and a design doc, with no code until you approve it. Use for a new feature or change when the request leaves the essentials open.

Dispatching parallel agents

Splits independent problems between parallel subagents, each with one domain and a self-contained brief with scope, constraints and the report expected back, then checks their edits for conflicts and runs the full suite. Use when several unrelated things fail at once.

Executing plans

Runs a plan from writing-plans in the current session with no subagent per task: tasks in order through TDD, a ledger of progress and rulings that survives context compaction, and one fresh review of the whole branch at the end. Use when per-task review is not needed or there are no subagents.

Finishing a development branch

Finishes a branch: runs the tests, offers to merge locally, open a pull request or keep it as is, reruns the tests after a merge and removes its own worktree, and discards work only after you type "discard". Use when the implementation is done.

Receiving code review

Checks each review comment against the code before changing anything, clears up every unclear item first, pushes back with technical reasons and never performs agreement. Use when working through review feedback without blind fixes.

Requesting code review

Hands finished work to a fresh reviewer subagent through a template: the commit range, the plan or requirements, findings by severity and a verdict on merging. Use when a task or feature is done and a merge to main is next.

Subagent-driven development

Executes a plan through subagents: a fresh implementer and reviewer for every task, checking spec compliance and code quality, up to five fix rounds and a final review of the whole branch. Use for a plan of independent tasks when each one needs a review.

Systematic debugging

Keeps the agent from guessing at fixes: reproduce the bug and find the root cause first, test one hypothesis at a time, fix with a failing test, and question the design after three failed fixes. Use for any bug, test failure or unexpected behavior.

Using git worktrees

Moves feature work into an isolated git worktree: checks whether the agent is already isolated, prefers the harness's own worktree tool, keeps the folder git-ignored, installs dependencies and runs a baseline test. Use when the work must not land on the branch you have open.

Verification before completion

Stops the agent from saying "done" or "tests pass" until it has rerun the check and read the whole output. Use whenever the agent reports success, commits or opens a pull request.

Writing implementation plans

Turns a spec into a plan for an implementer new to the codebase: files, signatures, interfaces between tasks, tests with exact values and TDD steps with each command's expected output. Use for a multi-step task when the spec is ready and no code exists yet.

Writing skills

Writes and edits skills the TDD way: a subagent first does the task without the skill and its mistakes are written down, then the smallest text that answers them goes in and the loopholes get closed. Use for a skill that other agents will load.