Skip to content
Skills Library
Programming · Building & coding

test-driven-development

/test-driven-development

Build features and fix bugs test-first with red-green-refactor: write one failing test, watch it fail for the right reason, write the least code that makes it pass, then refactor while green. Use this skill whenever you implement a feature, add a function or endpoint, change behavior, fix a bug, or refactor or break up code without changing what it does, in any language, even if the user never says "TDD" or "test first". Also use it when the user asks for TDD, a regression test, or a failing test that reproduces a bug, and whenever you catch yourself writing production code before a test that

Licence
MIT
Last repository change
11.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 11.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Build features and fix bugs test-first with red-green-refactor: write one failing test, watch it fail for the right reason, write the least code that makes it pass, then refactor while green. Use this skill whenever you implement a feature, add a function or endpoint, change behavior, fix a bug, or refactor or break up code without changing what it does, in any language, even if the user never says "TDD" or "test first". Also use it when the user asks for TDD, a regression test, or a failing test that reproduces a bug, and whenever you catch yourself writing production code before a test that

Triggers from the description

TDDtest first
Original author description

Build features and fix bugs test-first with red-green-refactor: write one failing test, watch it fail for the right reason, write the least code that makes it pass, then refactor while green. Use this skill whenever you implement a feature, add a function or endpoint, change behavior, fix a bug, or refactor or break up code without changing what it does, in any language, even if the user never says "TDD" or "test first". Also use it when the user asks for TDD, a regression test, or a failing test that reproduces a bug, and whenever you catch yourself writing production code before a test that

How it works

  1. Start with a Test List
  2. The Cycle
  3. Bug Fixes Start with a Reproduction
  4. Refactoring Existing Code
  5. When Test-First Gets Hard
  6. Rationalizations to Catch
  7. Before You Finish
Original SKILL.md headings · 120 lines, 1,179 words
SKILL.md preview
---
name: test-driven-development
description: >
  Build features and fix bugs test-first with red-green-refactor: write one failing test, watch it fail for the right reason,
  write the least code that makes it pass, then refactor while green. Use this skill whenever you implement a feature, add a
  function or endpoint, change behavior, fix a bug, or refactor or break up code without changing what it does, in any language,
  even if the user never says
  "TDD" or "test first". Also use it when the user asks for TDD, a regression test, or a failing test that reproduces a bug, and
  whenever you catch yourself writing production code before a test that exercises it. Not for how to write a good individual
  test, mocks, or fixtures (use the best-practices skill), or for investigating a failure whose cause is still unknown.
license: MIT
metadata:
  author: Kevin J Bluck <kbluck@users.noreply.github.com>
  copyright: Copyright © 2026 Kevin J. Bluck
  repository: https://github.com/kbluck/agent-resources
  url: https://github.com/kbluck/agent-resources/tree/main/plugins/software-testing/skills/test-driven-development
  version: 1.0.0
---

# Test-Driven Development

Write the test first. Watch it fail. Write the least code that makes it pass. Then clean up.

The reason for the order is evidence. A test you watched fail, for the reason you expected, has proven it can detect the missing
behavior. A test written after the code usually passes on its first run, and a test that has only ever passed has proven nothing: it
might be asserting on the wrong thing, or not running at all.

So the rule is: **no production code without a failing test that demands it.** If you notice you have written code first, set it
aside, write the test, watch it fail against the code without your change, then bring the code back.

The project's test conventions win over anything here. If the user explicitly asks you to skip tests or work another way, do what
they ask and mention what is left untested.

## Start with a Test List

Before the first test, write down the behaviors the request implies, one line each: every rule it states, then the edge cases those
rules raise (empty input, boundaries, invalid input, and the awkward members of each category, such as letters that have no simple
ASCII form when the rule is "accented letters become ASCII"). The best-practices skill has a checklist of edges. Work through the
list one cycle at a time, adding to it as you discover cases. Anything you decide not to handle, tell the user.

## The Cycle

```text
   RED                 GREEN                 REFACTOR
   write one     -->   write the least  -->  clean up with     --+
   failing test        code to pass          tests still green   |
     ^                                                           |
     +-----------------------  next behavior  <------------------+
```

### Red: Write One Failing Test

Write a single test for the next small piece of behavior. Small means one rule, one case, one branch: "rejects an empty email", not
"validates the form".

- Name it for the behavior, so the name reads as a requirement.
- Use real code; reach for a double only for something slow, nondeterministic, or external. See the best-practices skill.
- Assert on the outcome a caller would observe.

### Verify Red: Watch It Fail

Run just that test with the project's runner. Do not skip this step; it is the whole point of writing the test first.

Confirm three things:

1. **It fails**, not passes. A test that passes before the change is not testing the change. Either the behavior already exists, or
   the test is wrong.
2. **It fails on the assertion**, not with an import error, a typo, or a missing fixture. Those failures prove nothing about the
   behavior. In compiled languages, add the minimal stub (signature only, returning a default) so the test compiles, then run it
   again to see the assertion fail.
3. **The failure message says what you expected**: the expected value against the actual one, or the error that should have been
   raised.

### Green: Write the Least Code That Passes

Write the simplest code that makes this test pass. Hard-coding a return value is acceptable when it is genuinely the simplest thing;
the next test will force the general solution. Do not add features, options, or error handling that no test asks for yet.

### Verify Green: Watch It Pass

Run the test again and confirm it passes. Then run the surrounding file or module, and the whole suite at natural checkpoints, to
confirm nothing else broke. The output should be clean, with no new warnings or noise.

### Refactor: Tidy While Green

Only with every test passing: remove duplication, improve names, extract helpers, simplify. Run the tests after each change. Do not
add behavior during refactoring; new behavior starts with a new red test.

Then pick the next behavior and go around again.

## Bug Fixes Start with a Reproduction

For a bug, the first red test is one that reproduces it:

1. Write a test that exercises the reported scenario and asserts the correct behavior.
2. Run it and confirm it fails *the way the bug report describes*. If it passes, you have not reproduced the bug yet; keep narrowing
   the test before touching the code.
3. Fix the code and watch the test pass.
4. Keep the test. It is the regression test that stops the bug coming back.

If you do not yet understand why the bug happens, find the cause first, then return here to write the reproduction.

## Refactoring Existing Code

Refactoring changes structure without changing behavior, so the tests come first in a different way: make sure the behavior you are
about to move is covered *before* you move it. If it is not, add characterization tests that pin down what the code does today, and
check they pass. Then refactor in small steps, running the tests after each one.

## When Test-First Gets Hard

| Situation | What to do |
| :-------- | :--------- |
| You do not know what the design should be | Spike in a scratch branch or file to learn, then discard it and rebuild test-first |
| The code is hard to test (globals, hidden I/O, no seams) | Write a higher-level test around it first, then introduce a seam so a unit test can reach it |
| Pure layout, styling, or generated code | Test-first adds little; verify it another way and say so |
| Configuration or build changes | The "test" may be running the build or the app; still watch it fail before and pass after |
| An existing test suite is already red | Do not build on a red baseline. Report the failures and ask before continuing |

## Rationalizations to Catch

| You think | Reality |
| :-------- | :------ |
| "Too simple to need a test" | Simple code breaks too, and the test takes a minute |
| "I'll write the tests after" | Tests written after pass on the first run and prove nothing until you break the code to check them |
| "I already tested it by hand" | A manual check leaves no record and cannot be re-run on the next change |
| "TDD will slow me down" | It is slower than skipping tests and faster than debugging what skipping them produced |
| "Just this once" | The cases that feel safe to skip are the ones you thought least about |

Stop and restart the cycle if any of these happen: you wrote code before its test, a new test passed on its first run, you cannot
explain why a test failed, or you are adding behavior during a refactor.

## Before You Finish

- [ ] Every new behavior has a test, and you saw each one fail before the code that makes it pass existed.
- [ ] Each test failed on its assertion, with the message you expected.
- [ ] The code is no more general than the tests require.
- [ ] The whole suite passes in a fresh run, with clean output.

Versions

RepositoryScoreLicence
This page · kbluck/agent-resources100MIT
GanyuanRan/Aegis100MIT
lucasouzadev/agent-kit-skill100MIT
zeative/satgas100AGPL-3.0
nikospavlopoulos/devops-mutant-powers100MIT
JohnStrunk/CommonCast100LGPL
Sanit-mann/The-Insectoids100MIT
mastro993/fstack100MIT
jelvodev/yaap100MIT

Database snapshot: 13.11.2026 · package version cbb06f178651 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100tdd
    Red-green-refactor procedure: write the failing test first, show it fail, write the minimum code, refactor on green. Use for any bug fix or new behavior in code that has or could have tests, including 'fix this bug', 'add a function', 'use TDD' and 'write the test first'.
  • 100red-green-refactor
    Guides the red-green-refactor TDD workflow: write a failing test first, implement the minimum code to make it pass, then refactor while keeping tests green. Use when a user asks to practice TDD, write tests first, follow red-green-refactor, do test-driven development, write…
  • 100054-design-tdd
    Use when Java implementation work should be guided by Test-Driven Development, including maintaining a test list, choosing the next behavior, writing a failing test first, implementing only enough production code to pass, and refactoring while keeping tests green. This should…
  • 85tdd
    Red, green, refactor for exactly one behaviour. Pick the test level, run only that file, watch it fail for the right reason, make it pass, refactor, commit. The implement-issue skill uses it. Use it directly for a bug fix, with the reproducer first.
  • 100tdd
    Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
  • 100tdd
    Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.