tdd
Skill2 starsChanged 3 months agoMITView on GitHub
Test-driven development gated on user approval of the failing test. Use when implementing new behavior, fixing a bug, or when the user asks for TDD by any name. Not for docs, config, or refactors already covered by tests.
194 other projects use a version of this.
Adopted by
Most recently taken up by
- 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
- yagizdo/quivertheir 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
tristanphvnSkillketchup-video
Catch the user up like /keel:ketchup, with a short subtitled video of slides for what happened and the waiting calls as text under it. Use for /keel:ketchup-video.
Also in 14 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 54 projects that use this
jaydubya818Skillprinciple-laziness-protocol
Apply when a refactor is adding wrappers or abstractions instead of simplifying.
Also in 45 projects that use this
- +2 more from The-Vibe-Company
- +5 more from jaydubya818
Other versions194 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 194
- mattpocock/skills★ 325ksame name
- Yeachan-Heo/oh-my-claudecode★ 41ksame name
- trpc/trpc★ 41ksame name
- Yeachan-Heo/oh-my-claude-sisyphus★ 41ksame name
- QuivrHQ/quivr★ 40ksame name
- The-Vibe-Company/quivr★ 40ksame name
- ryoppippi/ccusage★ 19ksame name
- ccusage/ccusage★ 19ksame name
- MODSetter/SurfSense★ 17ksame name
- GreyDGL/PentestGPT★ 16ksame name
184 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 repository8 other files it gives its agents.
- .claude/CLAUDE.mdCLAUDE.md
- agent-config-auditSkill
- changesetSkill
- dep-updates-combinerSkill
- explain-clearlySkill
- mentorSkill
- walkthroughSkill
- us-english-spelling-sweepSkill
The file
We split this skill into the rules it gives an agent
6 rules. 0 are common, 6 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 186 edited versions we read keep these.
6
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 32
If the behavior could reasonably be tested at more than one level, that is a design decision, not a lookup.
- Distinctive: line 48
Prefer hand-written stubs and fakes over mocking frameworks — a small stub that returns the expected data.
- Distinctive: line 55
Write the design and nothing else — one behavior, and only the assertions step 2 called for.
- Distinctive: line 60
Run the narrowest command that exercises just this test, taking that command from the project itself — its agent instructions, task or …
- Distinctive: line 110
Do not weaken it. No relaxing an exact-value assertion into a range or a truthiness check, no deleting the awkward case, no "the fake can't …
- Distinctive: line 113
Instead, gather all such cases and present them to the user: what the test expects, what currently exists, why the gap is there, and the …
“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
TDD Loop
The test is the specification. Once a test fails for the right reason, it must not be weakened to accommodate the implementation.
Agree the feedback loop size with the user first — one test per cycle, or a batch prepared ahead. It depends on the task. If unsure, prefer fewer tests per cycle.
1. Choose the test type
What the behavior needs decides this, not preference:
- Unit — pure. No network, no containers, no infrastructure. Use in-memory fakes and stubs. Must pass anywhere with zero setup.
- Integration — needs live infrastructure (a container, a database, a real service).
- End-to-end — full flows through the public entry point.
Then find how this project separates them — a filename suffix, a directory, a test tag, a runner config — by reading the tests that already exist. Projects vary: some split all three, some run unit and integration in one lane and only isolate end-to-end, some make no distinction at all. Adopt whatever is there.
The one rule that holds regardless: every test belongs in a lane that provides the infrastructure it needs. A test requiring a database belongs in a lane that starts one. That is what keeps CI honest — not how the file is labeled.
If the behavior could reasonably be tested at more than one level, that is a design decision, not a lookup. Raise it at the gate in step 5.
Settled when you can name the exact file or lane this test will live in, and point at the existing test that told you.
2. Design the test
- Pin down the exact behavior and the precise assertions before writing anything.
- Fixing a bug? The test must reproduce it. It has to fail because the defect is present, not because a feature is missing — otherwise it isn't pinned to the bug and will pass again for the wrong reason. It stays afterwards as the regression test.
- Assert the value, not its existence. "It is not null", "it is not empty", "it did not throw", "the function was called" — these pass against implementations you already know are wrong. Assert what it equals, what it contains, how many there are, what changed.
- Sanity check every assertion: picture a plausible but incorrect implementation. If the assertion still passes against it, it isn't pinning the behavior down — tighten it before moving on.
- Prefer hand-written stubs and fakes over mocking frameworks — a small stub that returns the expected data.
- Design it so it can be written once and never modified.
Settled when every assertion has survived that sanity check.
3. Write the test
Write the design and nothing else — one behavior, and only the assertions step 2 called for. Fresh ideas arriving now are the next cycle's test, not this one's.
4. Observe RED
Run the narrowest command that exercises just this test, taking that command from the project itself — its agent instructions, task or build configuration, contributing guide, or CI workflow. CI is the most reliable source: those commands are proven to run. Never assume a test runner, package manager, or directory layout — the project has already chosen all three; read that choice.
Confirm it fails for the expected reason — a failed assertion on the behavior under test. A compile or syntax error, a bad import, or a setup crash is not red; fix the harness first, then re-run.
If it passes on the first run, stop — that is not a green light. Either the behavior already exists, so this test drives nothing and the work may already be done, or the assertion is vacuous and would pass against any implementation. Work out which, and tell the user. Never carry a passing test into the gate.
5. GATE — stop for user review
Present the failing test to the user, along with the test type chosen and why. They review it, and ideally commit it, before implementation begins. Approval is what opens the gate; wait for it.
Implementing past an unapproved test means building against a specification nobody agreed to.
6. Implement
The minimum code that makes the test pass. Follow the project's existing conventions and architectural rules.
7. Observe GREEN
Re-run the exact command from step 4. Confirm the new test passes and the surrounding suite still does.
8. Review
Re-read the diff as a reviewer would, then run the same verification this project runs before merge, scoped to what changed. Find it where you found the test command in step 4 — CI is the definitive list.
Which checks exist is the project's decision, and it varies by language and by choice: a compiler, a type checker, a linter, a formatter, static analysis, none of them. Run exactly the set it defines — including the ones that look unrelated to your change, since those are the ones that catch what you didn't predict.
9. Consider refactor
Improve names and structure while the tests stay green. Re-run them afterwards.
Do not touch the tests here. Refactoring changes structure, not behavior, and the tests are the only thing proving that. Editing both at once means nothing is holding behavior fixed. If a refactor appears to require a test change, it is a behavior change — stop, and start a new cycle at step 1.
10. Next item
Return to step 1 for the next behavior.
If the implementation cannot pass the test as written
Do not weaken it. No relaxing an exact-value assertion into a range or a truthiness check, no deleting the awkward case, no "the fake can't do X, so we assert Y instead" substitutions.
Instead, gather all such cases and present them to the user: what the test expects, what currently exists, why the gap is there, and the options for closing it (fix the fake, change the API design, split the behavior). Wait for their decision.
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.

