test-driven-development

Overview

What this skill does

The test-driven-development skill encodes a strict Test-Driven Development (TDD) workflow: you always write a failing test before any production code, then apply a disciplined Red-Green-Refactor cycle.

Instead of loose “write some tests eventually” guidance, this skill gives hard rules:

• No production code without a failing test first
• Always verify the test fails for the right reason
• Only write minimal code to make tests pass
• Refactor once everything is green

It also links to a dedicated testing-anti-patterns guide that helps you avoid fragile, misleading tests.

Who it is for

Use the test-driven-development skill if you are:

• A developer who wants a reliable workflow for features, bugfixes, and refactors
• A team standardizing on TDD and needing clear rules everyone can follow
• A coach or tech lead who wants to enforce consistent test automation habits

It is especially useful in JavaScript and TypeScript codebases, but the principles apply to any language and test framework.

Problems this skill solves

This skill is designed to fix common problems in day-to-day development:

• Writing code first and adding tests later, or never
• Unclear whether tests actually verify behavior
• Fear of refactoring because tests are weak or missing
• Overuse or misuse of mocks that test fake behavior instead of real behavior

By following the test-driven-development workflow, you:

• Get fast feedback from failing tests
• Keep a clear record of intended behavior
• Make refactoring safer because behavior is locked in by tests
• Avoid brittle tests that only verify mocks or implementation details

When to use (and when not to)

The upstream skill explicitly recommends using TDD for:

• New features
• Bug fixes
• Refactoring work
• Any behavior change

And it calls out exceptions to discuss with a human partner, such as:

• Throwaway prototypes
• Generated code
• Configuration files

If you are “just exploring” or hacking a quick spike that you plan to throw away, this strict test-driven-development skill may be heavier than you need. For production features, however, it is intended to be the default workflow, not an optional extra.

How to Use

Installation

To install the test-driven-development skill from the obra/superpowers repository, run:

npx skills add https://github.com/obra/superpowers --skill test-driven-development

This pulls the test-driven-development skill definition and supporting files into your Agent Skills environment. Once installed, you can open the skill’s files to see the detailed rules and anti-pattern examples.

Key files referenced by this skill include:

• SKILL.md – the core TDD rules, including the Iron Law and Red-Green-Refactor
• testing-anti-patterns.md – a focused guide on what not to do in tests

Core principle: The Iron Law

At the heart of this skill is what the source calls the Iron Law:

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

In practical terms:

• If you wrote production code before a test, you delete that code and start again
• You do not keep it as a “reference” or adapt it while writing tests
• You do not peek at the deleted code when re-implementing from tests

This hard rule ensures that every line of production code is driven by a real test.

Step-by-step TDD workflow

Once the test-driven-development skill is installed, apply it as your default workflow:

1. Write a failing test (RED)

• Identify a single behavior (feature, bugfix, or refactor outcome)
• Write a new test that expresses the expected behavior
• Run the tests and confirm that this new test fails

You are not done with the RED step until you:

• See the test fail
• Confirm it is failing for the correct reason (the right assertion, the right error)

If the failure is wrong (e.g., the test crashes or fails in setup), fix the test and re-run until it fails in a meaningful way.

2. Add minimal code to pass (GREEN)

• Implement only the simplest possible code to make the failing test pass
• Avoid premature design, abstractions, or extra logic
• Run the test suite and ensure the new test is now green and existing tests still pass

The skill’s guidance emphasizes that this step is intentionally narrow: your goal is not to “finish the feature,” but to satisfy the test.

3. Refactor safely (REFACTOR)

With everything green:

• Clean up production code: remove duplication, simplify logic, clarify names
• Clean up tests: make them more readable, extract helpers if needed
• Keep running tests frequently to ensure behavior has not changed

This preserves behavior while improving the design, backed by your test suite.

4. Repeat the cycle

For each small behavior or edge case:

• Add another test (RED)
• Make it pass (GREEN)
• Refactor as needed (REFACTOR)

The test-driven-development skill’s job is to keep you in this loop and to make it hard to rationalize skipping steps.

Integrating with your stack

The repository examples are written with a focus on JavaScript and TypeScript, but you can apply the TDD rules regardless of your stack:

• In JavaScript/TypeScript projects (e.g., using Jest, Vitest, or Mocha):

  • Always create or modify tests (e.g., in *.test.ts or *.spec.ts) before editing production files
  • Use the Red-Green-Refactor cycle around every change to application code

• In other languages (e.g., Python, Java, Go, C#):

  • Map the same steps to your testing framework (pytest, JUnit, Go test, xUnit, etc.)
  • The strict rule “no production code without a failing test” still applies

The skill itself does not lock you into a specific framework; it encodes workflow rules, not library dependencies.

Using the testing anti-patterns guide

The included testing-anti-patterns.md file acts as a companion to the test-driven-development skill. Load or reference it whenever you:

• Are writing or changing tests
• Are adding mocks or stubs
• Are tempted to add test-only hooks into production classes or modules

Key principles from this guide include:

• Never test mock behavior – tests should verify real behavior, not that a mock exists
• Never add test-only methods to production classes – keep production APIs clean
• Never mock without understanding dependencies – over-mocking leads to false confidence

The anti-pattern examples use TypeScript-style tests to show bad vs good tests, which you can adapt to your own test framework.

Adapting the workflow to your team

After installation, you can adapt the test-driven-development skill’s rules to your reality while preserving the core intent:

• Align on which types of changes must follow strict TDD (e.g., all production modules, domain logic, critical flows)
• Agree on the few exception cases (e.g., quick spikes or generated code), but keep them explicit
• Incorporate the Iron Law into your code review checklist:
  • “Where is the failing test that drove this change?”
  • “Was the test written first?”

This helps you use the skill as a team standard, not just a personal habit.

FAQ

Is the test-driven-development skill framework-specific?

No. The test-driven-development skill defines a workflow and rules, not a particular test framework. The repository examples lean on JavaScript and TypeScript, but you can apply the same Red-Green-Refactor loop in any language.

Do I really have to delete code I wrote without tests?

According to the Iron Law in SKILL.md, yes. If you wrote production code before a failing test, the rule is to delete it and start over from tests. The idea is to remove any temptation to treat tests as an afterthought.

When is this skill not a good fit?

The upstream guidance lists a few potential exceptions, like throwaway prototypes, generated code, or configuration files. For short-lived experimental spikes, strict test-driven-development may be heavier than necessary. For production features, bugfixes, and refactors, this skill is intended to be the default.

How does this skill help with debugging and refactoring?

When fixing a bug or refactoring:

• First, write a failing test that reproduces the bug or describes the intended behavior
• Then change code until the test passes
• Finally, refactor with confidence, because the tests enforce behavior

This makes debugging more systematic and makes refactoring safer.

Can I use this with existing legacy code that has no tests?

Yes, but you will likely apply it incrementally:

• When you touch a legacy area, first add a test that captures the current or desired behavior
• Watch it fail (if you are changing behavior), then make it pass
• Use the Red-Green-Refactor loop to gradually bring that part of the codebase under test

Over time, more of your legacy code becomes protected by tests.

Where should I start after installation?

After running the install command, open:

• SKILL.md for the core test-driven-development rules and the Red-Green-Refactor description
• testing-anti-patterns.md for common mistakes to avoid when writing tests

Use these two files as the reference for your day-to-day development workflow.