Testing before implementation
Change code test-first: every behavior gets a test that is seen failing for a reason you named before the code that makes it pass exists, and the task ends only when the whole project is no worse than its baseline. Every red and green run is recorded with its command and real output, because "tests pass" without output proves nothing.
Gotchas
- A test that passes on its first run proves nothing. It tests behavior that already exists, or nothing at all: fix the test until it fails for the reason you named.
- An error is not a failure. An import error, a typo or a missing fixture makes the test red for the wrong reason: fix it and run again before counting the run as red.
- A green targeted test is not a green project. Always compare the full suite, lint and type check with the baseline before calling the task done.
- The project's commands come from the project. Read them from its files; never assume a test runner, a flag or a script name.
- A wrong-looking test is the user's call. Report it with the evidence and keep it unchanged; editing or removing a test to make it pass hides the bug it may be catching.
- An expected value computed with the code under test always passes. Write expected values by hand, from the requirement.
- Flaky is not passing. A test that passes on a rerun after failing is flaky: report it as flaky, never rerun it until it is green.
git stash is shared by every worktree of a repository, so a stash made in one can be popped in another. Set code aside on a local branch instead (phase 4).
Rules
Each rule says what to do and why, so it holds in cases the phases don't name.
- Keep existing tests as they are. When one looks wrong, stop and report it to the user with the evidence. Changing a test to make it pass hides bugs.
- Write a solution that works for every valid input. Tests verify correctness; they don't define the solution, and a hard-coded value passes the test and fails in use.
- Write the test before the code it covers. Code that already exists biases the test toward what it does instead of what it should do.
- Watch every test fail for the reason you named, then pass. A test never seen failing may test nothing.
- Record the command and output of every red and green run. On planned work the plan gate reads them.
- Name the break before writing the test: which production change would make it fail, and whether that change is a bug or a decision. A test that can't name its break catches nothing.
- Compare the final suite, lint and type check with the baseline. Fix every new failure and report the pre-existing ones by name.
- Report flaky tests as flaky. A lucky pass is a false pass.
- Mock only the slow or external level (network, clock, filesystem outside the project, paid services), mirroring the real structure. Assertions on a mock test the mock.
- Leave push, deploys and anything outside the task to the user. Commit at green only as the project's conventions say.
- Run the whole red-green-refactor cycle in the one session that writes the code, the main session or the subagent given that one task; never split it, such as one agent writing the test and another the code. Test and code share context, and a split cycle returns summarized evidence instead of raw output. On high-stakes work, have the
work-lifecycle:plan-verifier agent check test quality in work mode once the task is done, from the main session, giving it the test files, the code under test and the red and green runs.
Workflow
Copy this checklist into your working notes and tick each item only when it is done. Phases 3 to 6 repeat for each behavior until the task is covered.
Test-first progress:
- [ ] 1. Commands found, baseline recorded
- [ ] 2. Verification approach chosen (state which and why)
- [ ] 3. Break named for the next test
- [ ] 4. Red: failed for the named reason, evidence recorded
- [ ] 5. Green: minimal code passes, evidence recorded
- [ ] 6. Refactored while green
- [ ] 7. Suite, lint and types compared with baseline; committed
- [ ] 8. Report delivered
1. Discover
- Find the project's test, lint and type-check commands in its own files:
CLAUDE.md, the package or project manifest (package.json scripts, pyproject.toml, Makefile, Cargo.toml, go.mod), and the CI configuration. Prefer the exact command CI runs.
- Read the existing tests nearest to the code you will change, and match their framework, file layout, naming, fixtures and assertion style.
- Run the full suite, lint and type check before any change, and record the baseline: each command and its pass or fail counts, with every failing test or finding listed by name.
- If the project has no test setup, propose the smallest one that fits its stack, from that framework's current documentation, and ask the user before adding any dependency.
2. Decide how to verify
Default to the test-first cycle. Read references/choosing-verification.md when the change is legacy code without tests, a visual interface, configuration or infrastructure, or a throwaway prototype, or when you need to choose between a unit, an integration and an end-to-end test. State the approach and why in your notes.
3. Name the break
- State, for the next test, which production change would make it fail, and whether that change would be a bug or a deliberate decision.
- Derive the expected value by hand from the requirement, never by running the code under test.
- Read
references/writing-good-tests.md before writing or changing any test or mock: it holds how to test real behavior, when a mock is right, and the warning signs of a test that catches nothing.
4. Red
If code for this behavior already exists from before the test, set it aside on a local branch, then reimplement it from the test:
git switch -c wip/<behavior>-before-test && git add <its files> && git commit -m "WIP: <behavior>, set aside before its test" && git switch -
Nothing is pushed, and the branch is the user's to keep or delete.
Write one test for one behavior.
Run it. Confirm it fails, not errors, and that the failure message shows the reason you named.
If it passes, it tests existing behavior: fix the test. If it errors, fix the error and run again.
Record the run: the exact command and the lines of output that show the failure.
5. Green
- Write the minimal code that makes the test pass for every valid input, not only the test's.
- Run the test. If it fails, fix the code, never the test.
- Record the run: the command and the lines of output that show the pass.
6. Refactor
While green, improve names and structure without adding behavior, and run the test again after each change. A refactor that turns the test red is undone or fixed before going on.
7. Close the task
- Run the full suite, lint and type check, and compare each with the baseline.
- Fix every new failure. List each pre-existing failure by name, untouched.
- On high-stakes work (money, data, security, anything costly to get wrong), run a real mutation check: break one line of the new code on purpose, confirm a test fails, revert, and record both runs. Read
references/writing-good-tests.md for how to pick the line.
- Commit only as the project's conventions say; never push.
8. Report
Deliver this report:
## Test-first report
**Baseline:** <suite, lint and type-check commands> → <pass and fail counts before the change>
**Tests**
- <test name>: breaks if <named production change>
- Red: `<command>` → <failure line>
- Green: `<command>` → <pass line>
**Final check against baseline**
- New failures: <none, or each by name with its fix>
- Pre-existing failures: <each by name, untouched>
**Mutation check:** <the line broken and the test that failed | not run, and why>
**Risks left without a test:** <each, with why>
Open the example that matches the change before writing your first test, to see the judgment in a full run:
references/examples/python.md: a bug fix in a Python function, with a pre-existing failure in the baseline.
references/examples/typescript.md: a new function in TypeScript, with a mock at the network boundary only.
references/examples/bash.md: a change to legacy shell code without tests, with a characterization test first.
The examples show judgment, not a template: copy their reasoning, never their languages, names or numbers.
Inside a plan
When this skill carries out a task of a plan from work-lifecycle:planning-before-execution:
- In the main session, with that plan's state file for this session, record the red and green runs in the task's
red and green entries, each as an object with command and output, then validate the file as that skill's Execution section says. The plan gate keeps the plan open until every test-first task has both.
- As a subagent running one task of the plan, never write the state file: return the red and green runs, the final check against the baseline and the report, each with its command and raw output, so the main session records them.
Without a plan, the report above holds the same evidence, and the gate doesn't apply.
1---2name: testing-before-implementation3description: Implements code changes test-first (TDD). Writes a failing test that names the break it catches, watches it fail for the right reason, writes the minimal code that passes, then checks the full suite, lint and types against a baseline, recording the command and output of each run. Use when implementing a feature, fixing a bug or changing behavior in code that can be tested, or when the user asks for TDD, test-first or red-green-refactor, even if they don't mention tests. When the work spans several steps or files, plan it first with planning-before-execution and apply this skill to each code task. Not for configuration-only edits, documentation, visual styling, or adding tests to existing code without a behavior change.4compatibility: Claude Code, with the project's own test, lint and type-check commands. The Claude app can't run the user's project, so the skill doesn't apply there.5metadata:6 source: https://skillmd.com/skills/nerymurillohnd/testing-before-implementation7---89# Testing before implementation1011Change code test-first: every behavior gets a test that is seen failing for a reason you named before the code that makes it pass exists, and the task ends only when the whole project is no worse than its baseline. Every red and green run is recorded with its command and real output, because "tests pass" without output proves nothing.1213## Gotchas14151. A test that passes on its first run proves nothing. It tests behavior that already exists, or nothing at all: fix the test until it fails for the reason you named.162. An error is not a failure. An import error, a typo or a missing fixture makes the test red for the wrong reason: fix it and run again before counting the run as red.173. A green targeted test is not a green project. Always compare the full suite, lint and type check with the baseline before calling the task done.184. The project's commands come from the project. Read them from its files; never assume a test runner, a flag or a script name.195. A wrong-looking test is the user's call. Report it with the evidence and keep it unchanged; editing or removing a test to make it pass hides the bug it may be catching.206. An expected value computed with the code under test always passes. Write expected values by hand, from the requirement.217. Flaky is not passing. A test that passes on a rerun after failing is flaky: report it as flaky, never rerun it until it is green.228. `git stash` is shared by every worktree of a repository, so a stash made in one can be popped in another. Set code aside on a local branch instead (phase 4).2324## Rules2526Each rule says what to do and why, so it holds in cases the phases don't name.27281. Keep existing tests as they are. When one looks wrong, stop and report it to the user with the evidence. Changing a test to make it pass hides bugs.292. Write a solution that works for every valid input. Tests verify correctness; they don't define the solution, and a hard-coded value passes the test and fails in use.303. Write the test before the code it covers. Code that already exists biases the test toward what it does instead of what it should do.314. Watch every test fail for the reason you named, then pass. A test never seen failing may test nothing.325. Record the command and output of every red and green run. On planned work the plan gate reads them.336. Name the break before writing the test: which production change would make it fail, and whether that change is a bug or a decision. A test that can't name its break catches nothing.347. Compare the final suite, lint and type check with the baseline. Fix every new failure and report the pre-existing ones by name.358. Report flaky tests as flaky. A lucky pass is a false pass.369. Mock only the slow or external level (network, clock, filesystem outside the project, paid services), mirroring the real structure. Assertions on a mock test the mock.3710. Leave push, deploys and anything outside the task to the user. Commit at green only as the project's conventions say.3811. Run the whole red-green-refactor cycle in the one session that writes the code, the main session or the subagent given that one task; never split it, such as one agent writing the test and another the code. Test and code share context, and a split cycle returns summarized evidence instead of raw output. On high-stakes work, have the `work-lifecycle:plan-verifier` agent check test quality in work mode once the task is done, from the main session, giving it the test files, the code under test and the red and green runs.3940## Workflow4142Copy this checklist into your working notes and tick each item only when it is done. Phases 3 to 6 repeat for each behavior until the task is covered.4344```text45Test-first progress:46- [ ] 1. Commands found, baseline recorded47- [ ] 2. Verification approach chosen (state which and why)48- [ ] 3. Break named for the next test49- [ ] 4. Red: failed for the named reason, evidence recorded50- [ ] 5. Green: minimal code passes, evidence recorded51- [ ] 6. Refactored while green52- [ ] 7. Suite, lint and types compared with baseline; committed53- [ ] 8. Report delivered54```5556### 1. Discover57581. Find the project's test, lint and type-check commands in its own files: `CLAUDE.md`, the package or project manifest (`package.json` scripts, `pyproject.toml`, `Makefile`, `Cargo.toml`, `go.mod`), and the CI configuration. Prefer the exact command CI runs.592. Read the existing tests nearest to the code you will change, and match their framework, file layout, naming, fixtures and assertion style.603. Run the full suite, lint and type check before any change, and record the baseline: each command and its pass or fail counts, with every failing test or finding listed by name.614. If the project has no test setup, propose the smallest one that fits its stack, from that framework's current documentation, and ask the user before adding any dependency.6263### 2. Decide how to verify6465Default to the test-first cycle. Read `references/choosing-verification.md` when the change is legacy code without tests, a visual interface, configuration or infrastructure, or a throwaway prototype, or when you need to choose between a unit, an integration and an end-to-end test. State the approach and why in your notes.6667### 3. Name the break68691. State, for the next test, which production change would make it fail, and whether that change would be a bug or a deliberate decision.702. Derive the expected value by hand from the requirement, never by running the code under test.713. Read `references/writing-good-tests.md` before writing or changing any test or mock: it holds how to test real behavior, when a mock is right, and the warning signs of a test that catches nothing.7273### 4. Red74751. If code for this behavior already exists from before the test, set it aside on a local branch, then reimplement it from the test:7677 ```bash78 git switch -c wip/<behavior>-before-test && git add <its files> && git commit -m "WIP: <behavior>, set aside before its test" && git switch -79 ```8081 Nothing is pushed, and the branch is the user's to keep or delete.822. Write one test for one behavior.833. Run it. Confirm it fails, not errors, and that the failure message shows the reason you named.844. If it passes, it tests existing behavior: fix the test. If it errors, fix the error and run again.855. Record the run: the exact command and the lines of output that show the failure.8687### 5. Green88891. Write the minimal code that makes the test pass for every valid input, not only the test's.902. Run the test. If it fails, fix the code, never the test.913. Record the run: the command and the lines of output that show the pass.9293### 6. Refactor9495While green, improve names and structure without adding behavior, and run the test again after each change. A refactor that turns the test red is undone or fixed before going on.9697### 7. Close the task98991. Run the full suite, lint and type check, and compare each with the baseline.1002. Fix every new failure. List each pre-existing failure by name, untouched.1013. On high-stakes work (money, data, security, anything costly to get wrong), run a real mutation check: break one line of the new code on purpose, confirm a test fails, revert, and record both runs. Read `references/writing-good-tests.md` for how to pick the line.1024. Commit only as the project's conventions say; never push.103104### 8. Report105106Deliver this report:107108```markdown109## Test-first report110111**Baseline:** <suite, lint and type-check commands> → <pass and fail counts before the change>112113**Tests**114- <test name>: breaks if <named production change>115 - Red: `<command>` → <failure line>116 - Green: `<command>` → <pass line>117118**Final check against baseline**119- New failures: <none, or each by name with its fix>120- Pre-existing failures: <each by name, untouched>121122**Mutation check:** <the line broken and the test that failed | not run, and why>123124**Risks left without a test:** <each, with why>125```126127Open the example that matches the change before writing your first test, to see the judgment in a full run:128129- `references/examples/python.md`: a bug fix in a Python function, with a pre-existing failure in the baseline.130- `references/examples/typescript.md`: a new function in TypeScript, with a mock at the network boundary only.131- `references/examples/bash.md`: a change to legacy shell code without tests, with a characterization test first.132133The examples show judgment, not a template: copy their reasoning, never their languages, names or numbers.134135## Inside a plan136137When this skill carries out a task of a plan from `work-lifecycle:planning-before-execution`:138139- In the main session, with that plan's state file for this session, record the red and green runs in the task's `red` and `green` entries, each as an object with `command` and `output`, then validate the file as that skill's Execution section says. The plan gate keeps the plan open until every test-first task has both.140- As a subagent running one task of the plan, never write the state file: return the red and green runs, the final check against the baseline and the report, each with its command and raw output, so the main session records them.141142Without a plan, the report above holds the same evidence, and the gate doesn't apply.