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.
test-driven-development- Author
- Jesse Vincent
- 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 picktest-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.
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
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
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 }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
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.
AnyModel