tdd
Skill199 starsChanged 2 months agoMITView on GitHub
Implement features using Test-Driven Development (TDD) with Red-Green-Refactor cycle.
194 other projects use a version of this, 2 of them edited.
Adopted by
Most recently taken up by
- bamlab/flashlighttheir own version, first seen Nov 16, 2026
- lhotwll217/owner-operatortheir own version, first seen Nov 16, 2026
- philoserf/claude-code-configtheir own version, first seen Nov 15, 2026
- e2b-dev/E2Btheir own version, first seen Nov 15, 2026
- backnotprop/pstacktheir own version, first seen Nov 15, 2026
- quickchatai/quickreviewtheir own version, first seen Nov 15, 2026
Used with
Projects with it also use capture-learning-tools, design-frontend-dev and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
The-Vibe-CompanySkillcapture-learning-tools
Turn technical conversations, bugs, CI failures, review comments,
Also in 5 projects that use this
The-Vibe-CompanySkilldesign-frontend-dev
Clean Impeccable frontend design skill. Use when the user wants to
Also in 5 projects that use this
jaydubya818Skillfigure-it-out
Use when novel or multi-phase work needs an auditable workflow and no narrower playbook fits.
Also in 61 projects that use this
jaydubya818Skillprinciple-minimize-reader-load
Apply when layers, wrappers, or hidden state make simple behavior hard to follow.
Also in 53 projects that use this
- +2 more from The-Vibe-Company
- +6 more from jaydubya818
Other versions194 projects use a version of this.
Word for word · 0
None found.
Edited · 2
- gaebalai/claude-code-orchestrator★ 1866% same
- ilhae-ai/claude-code-orchestrator★ 1866% same
Wrote their own version · 192
- mattpocock/skills★ 325ksame name
- Yeachan-Heo/oh-my-claudecode★ 41ksame name
- trpc/trpc★ 41ksame name
- Yeachan-Heo/oh-my-claude-sisyphus★ 41ksame name
- The-Vibe-Company/quivr★ 40ksame name
- QuivrHQ/quivr★ 40ksame name
- ccusage/ccusage★ 19ksame name
- ryoppippi/ccusage★ 19ksame name
- MODSetter/SurfSense★ 17ksame name
- GreyDGL/PentestGPT★ 16ksame name
182 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository17 other files it gives its agents.
- .agents/AGENTS.mdAGENTS.md
- AGENTS.mdAGENTS.md
- .codex/AGENTS.mdAGENTS.md
- catchupSkill
- checkpointingSkill
- codex-systemSkill
- context-loaderSkill
- design-trackerSkill
- featureSkill
- initSkill
- planSkill
- research-libSkill
- simplifySkill
- spikeSkill
- team-executeSkill
- troubleshootSkill
- update-lib-docsSkill
The file
We split this skill into the rules it gives an agent
10 rules. 0 are common, 7 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 186 edited versions we read keep these.
7
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 39
Only a *single trivial cycle* on a file already open in context stays with the lead (Self-Handle List item 2).
- Very specific: line 55
Read observed in the JSON — a non-zero exit is not all the same red:
- Distinctive: line 174
Write minimal code to pass the test:
- Distinctive: line 175
Don't aim for perfection
- Distinctive: line 201
When to refactor, and how far, stays a judgment call.
- Distinctive: line 209
Run the full quality gates:
- Very specific: line 215
Read the JSON: overall is pass / fail / no_gates.
- Very specific: line 260
Every [x] above must correspond to a run_tests.py --expect pass run that exited 0.
- Distinctive: line 265
Write tests first (not after)
- Distinctive: line 266
Keep each cycle small
“Common” is measured: kept by at least 6 in 10 of the 186 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Test-Driven Development
Implement $ARGUMENTS using Test-Driven Development (TDD).
TDD Cycle
Repeat: Red → Green → Refactor
1. Red: Write a failing test
2. Green: Write minimal code to pass the test
3. Refactor: Clean up code (tests still pass)Which test cases matter, and when to refactor, is judgment. The one thing that
is not judgment is whether a run came out the way you expected: every test run
in this skill goes through .claude/skills/_shared/run_tests.py, which turns
"confirm failure" / "confirm success" into an exit code.
Who Does What (delegation-first)
Per .claude/rules/delegation.md, the lead does not write the cycles by hand.
The split is fixed:
| Work | Owner |
| Requirement clarification, test-case list, boundary values | Lead (judgment, Self-Handle List item 5) |
| Writing the tests and the production code, cycle by cycle | general-purpose-sonnet |
| Cycles with ambiguous design, cross-cutting invariants, or security / concurrency / data-integrity risk | general-purpose-opus |
| A Red that is red for the wrong reason, or a Green that will not go green after one retry | codex-debugger |
Every run_tests.py / verify.sh gate and the final report | Lead — verification never delegates |
Only a single trivial cycle on a file already open in context stays with the lead (Self-Handle List item 2). Two or more cycles, or a module the lead has not read, is delegated. Independent modules are delegated in parallel in one message; they share no test file, so nothing serializes them.
The Red/Green Invariant
python3 .claude/skills/_shared/run_tests.py \
--target tests/test_{module}.py --expect fail --label red-1--expect fail|pass (required) and --target PATH (repeatable, at least one)
are the whole interface; --label names the log file under .claude/logs/
(default run-tests), so a later cycle does not overwrite an earlier log.
Read observed in the JSON — a non-zero exit is not all the same red:
observed | pytest exit | What it actually means |
failed | 1 | The test ran and failed. This is the only valid Red. |
passed | 0 | Nothing new is being asserted — the test cannot drive any code. |
collection_error | 2 | The file did not import (syntax error, bad fixture, missing import): red for the wrong reason. Fix the test, not the production code. |
no_tests_collected | 5 | Nothing was selected — the test was never written, or the name does not match the discovery pattern. |
Exit codes: 0 observed matches --expect; 1 bad arguments — including a
--target that does not exist (the mistyped path, caught before pytest runs)
and a pytest usage error (exit 4, e.g. an unknown ::node id); 2 observed
does not match --expect, or coverage is below --min-coverage; 3 external
failure — no pytest runner available, a timeout (--timeout, default 600s), or
a pytest internal error. On 1 and 3 the payload's observed is null: the
script reports that it has no observation rather than guessing one.
Other payload fields: expected, runner, command, exit_code, summary,
failed_tests (node ids from the short summary), coverage_percent,
min_coverage, log_file, artifacts, error.
The runner is resolved, not hardcoded: uv run pytest when uv and a
pyproject.toml are present, otherwise pytest from PATH, otherwise
python -m pytest (probed for importability first). --runner pins one
explicitly. If none is available the result is exit 3, never a silent pass.
Implementation Steps
Phase 1: Test Design
- Confirm Requirements
- What is the input
- What is the output
- What are the edge cases
- List Test Cases — record them with TodoWrite (one todo per case), so the
remaining cases survive a context reset instead of living only in this
conversation:
- [ ] Happy path: Basic functionality - [ ] Happy path: Boundary values - [ ] Error case: Invalid input - [ ] Error case: Error handling
Which cases to write, and which boundary values matter, is domain reasoning — never delegate it to a script.
Phase 2: Red-Green-Refactor
Step 0: Hand the Cycles Off
Delegate the Red-Green-Refactor loop with the six-element prompt contract from
.claude/rules/delegation.md. One delegation per module, all launched together:
Task tool:
subagent_type: "general-purpose-sonnet" # or general-purpose-opus, see the table above
prompt: |
Objective: Implement {module} by strict TDD, one test case at a time.
Scope:
- Write only tests/test_{module}.py and src/{module}.py. Touch nothing else.
- Do not modify existing tests, and never skip, delete, or weaken an assertion.
Inputs:
- Test cases to implement, in this order: {the Phase 1 list}
- Read .claude/rules/coding-principles.md and .claude/rules/testing.md first.
- Existing conventions to follow: {paths of comparable modules}
Acceptance checks — run these yourself, per cycle, and never skip Red:
python3 .claude/skills/_shared/run_tests.py \
--target tests/test_{module}.py --expect fail --label red-{n}
python3 .claude/skills/_shared/run_tests.py \
--target tests/test_{module}.py --expect pass --label green-{n}
A Red that exits 2 with observed=passed/collection_error/no_tests_collected
is not a Red: fix the test, not the production code, and re-run.
Output shape:
## Cycles completed (case -> red label -> green label)
## Files changed
## Deviations from the requested test cases, and why
## Anything that did not go green
Context discipline: return this summary only; the run logs stay in
.claude/logs/ and are referenced by label, not pasted.Then verify rather than trust: re-run run_tests.py --expect pass yourself and
read the diff. A reported cycle with no matching run_tests.py exit 0 did not
happen. If a cycle came back unfinished, escalate it (general-purpose-opus or
codex-debugger) instead of re-sending the same prompt to the same tier.
The steps below are the contract the delegate follows — and what the lead runs directly in the single-trivial-cycle case.
Step 1: Write First Test (Red)
# tests/test_{module}.py
def test_{function}_basic():
"""Test the most basic case"""
result = function(input)
assert result == expectedConfirm the test is red for the right reason:
python3 .claude/skills/_shared/run_tests.py \
--target tests/test_{module}.py --expect fail --label red-{n}Exit 0 means it genuinely failed. Do not proceed to Green on any other exit
code: on exit 2 read observed (see the table above), on exit 1/3 read
error and log_file.
Step 2: Implementation (Green)
Write minimal code to pass the test:
- Don't aim for perfection
- Hardcoding is OK
- Just make the test pass
Confirm success:
python3 .claude/skills/_shared/run_tests.py \
--target tests/test_{module}.py --expect pass --label green-{n}Exit 0 means the test now passes. Exit 2 with observed: failed means the
implementation is not there yet — read failed_tests.
Step 3: Refactoring (Refactor)
Improve while tests still pass:
- Remove duplication
- Improve naming
- Clean up structure
python3 .claude/skills/_shared/run_tests.py \
--target tests/test_{module}.py --expect pass --label refactor-{n}When to refactor, and how far, stays a judgment call.
Step 4: Next Test
Return to Step 1 with the next test case from the Phase 1 list.
Phase 3: Completion Check
Run the full quality gates:
bash .claude/skills/_shared/verify.shRead the JSON: overall is pass / fail / no_gates. Exit 0 means
overall: pass; exit 2 means a gate failed or no gate could run at all —
inspect log_file and tools. no_gates is a failure by default because a
code-editing session must not be able to declare done with zero checks
executed; if the project genuinely has no configured gates, re-run with
--allow-no-gates and verify manually with the project's own commands, and say
in the report that you did so. Exit 1 is bad arguments, 3 the log file could
not be written.
Then check coverage — with a threshold, so the answer is a gate and not a glance
at term-missing output:
python3 .claude/skills/_shared/run_tests.py \
--target tests/test_{module}.py --expect pass \
--cov {module} --min-coverage {N} --label coverage--cov MODULE (repeatable) requires the pytest-cov plugin; without it pytest
reports a usage error and run_tests.py exits 1 pointing at log_file.
Coverage below --min-coverage is exit 2; --cov with no coverage total in
the output is exit 3, never a silent pass. --min-coverage requires --cov.
Choosing the threshold is a project decision.
Report Format
## TDD Complete: {Feature Name}
### Test Cases
- [x] {test1}: {description}
- [x] {test2}: {description}
...
### Coverage
- {coverage_percent}% (threshold {min_coverage}%) — from run_tests.py, label `coverage`
### Quality Gates
- verify.sh: {overall} — `{log_file}`
### Implementation Files
- `src/{module}.py`: {description}
- `tests/test_{module}.py`: {N} testsEvery [x] above must correspond to a run_tests.py --expect pass run that
exited 0; mark nothing complete on the strength of having written it.
Notes
- Write tests first (not after)
- Keep each cycle small
- Refactor after tests pass
- Prioritize working code over perfection
- Where the production code belongs follows the project's existing layout — that is a design decision, not a derived path
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

