tdd
Skill5 starsChanged 46 days agoMITView on GitHub
use this when implementing a feature or bugfix, changing behavior, or refactoring — write a failing test first, watch it fail for the right reason, then write the smallest code that passes.
194 other projects use a version of this.
Adopted by
Most recently taken up by
- ishandutta2007/Awesome-Claude-Skillstheir own version, first seen Nov 8, 2026
- trpc/trpctheir own version, first seen Nov 8, 2026
- wowyuarm/dsh-agent-teamtheir own version, first seen Nov 8, 2026
- Contexera/dsh-agent-teamtheir own version, first seen Nov 8, 2026
- Dimon94/dveritytheir own version, first seen Nov 8, 2026
- Dimon94/skillstheir own version, first seen Nov 8, 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-CompanySkill
design-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 silent 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
- jaydubya818Skill
principle-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★ 309ksame name
- trpc/trpc★ 41ksame name
- Yeachan-Heo/oh-my-claude-sisyphus★ 41ksame name
- Yeachan-Heo/oh-my-claudecode★ 41ksame name
- QuivrHQ/quivr★ 40ksame name
- The-Vibe-Company/quivr★ 40ksame name
- ccusage/ccusage★ 19ksame name
- ryoppippi/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 repository49 other files it gives its agents.
- AGENTS.mdAGENTS.md
- maintainers/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- buying-researcherSkill
- cursor-cloud-agents-whenSkill
- debug-anthropicSkill
- debug-pocockSkill
- debugSkill
- discover-the-ideaSkill
- docs-google-styleSkill
- golang-safetySkill
- golang-securitySkill
- golang-testingSkill
- grok-acpSkill
- host-config-pyinfraSkill
- lang-cppSkill
- lang-csharpSkill
- lang-cSkill
- lang-dartSkill
- lang-dockerSkill
- lang-goSkill
- lang-javaSkill
- lang-js-tsSkill
- lang-kotlinSkill
- lang-luaSkill
- lang-makefileSkill
- lang-phpSkill
- lang-powershellSkill
- lang-protobufSkill
- lang-pythonSkill
- lang-rubySkill
- lang-rustSkill
- lang-shellSkill
- lang-sqlSkill
- lang-swiftSkill
- lang-terraformSkill
- language-routerSkill
- lang-web-markupSkill
- modern-pythonSkill
- pr-reviewSkill
- sdlc-artifactsSkill
- sdlc-onboardingSkill
- security-hardeningSkill
- shell-safetySkill
- tracker-sdlcSkill
- ui-craftSkill
- ux-designSkill
- verify-before-doneSkill
- yagniSkill
The file
We split this skill into the rules it gives an agent
8 rules. 0 are common, 8 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 186 edited versions we read keep these.
8
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 18
Stop and ask the operator, or someone the operator names in writing, before skipping the cycle for a topic below.
- Distinctive: line 33
Red: Write one minimal failing test for the next behavior.
- Distinctive: line 35
Green: Write the smallest production code that makes that test pass.
- Distinctive: line 37
Refactor: Only after green. Clean names and duplication.
- Distinctive: line 48
Test already passes? You are testing existing behavior.
- Distinctive: line 93
Test passes on the first run
- Distinctive: line 99
All of these mean: delete the production code.
- Distinctive: line 114
Before calling the work done:
“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
Rewrite of obra/superpowers skills/test-driven-development @ b36e0829c6d0140e93cfef2ca599b1b07d4a7797. Compress, not a paste. skills/tdd/ is the skill home.
The iron law
No production code without a failing test first.
Wrote code first? Delete it. Restart from a failing test. Do not keep it as reference, do not adapt it, do not glance at it while writing tests. Delete means delete.
Ask first
Stop and ask the operator, or someone the operator names in writing, before skipping the cycle for a topic below. Ask per Asking the operator.
| Topic | Why it is a stop |
| Renames / mechanical moves | Easy to treat as "no behavior" and skip the proof |
| Configuration-only changes | Config can still change runtime behavior |
| Throwaway / prototype | Fine to explore; throw the exploration away and rebuild the change with TDD if it ships |
| Generated code | Confirm it is generated and not behavior you owe a test |
Thinking "skip TDD just this once"? Stop. That is rationalization. Ask first — do not self-except.
Red → green → refactor
One behavior at a time. Text cycle, not a diagram.
- Red. Write one minimal failing test for the next behavior. Name the behavior. Prefer real code over mocks.
- Watch it fail for the right reason. Run the test. Confirm it fails because the feature is missing — not a typo, import error, or assertion on existing behavior. If it passes immediately, the test is wrong. If it errors, fix the harness until it is a real failure.
- Green. Write the smallest production code that makes that test pass. No extra features. No drive-by refactors.
- Watch it pass. The new test is green; the rest of the suite stays green; output is clean.
- Refactor. Only after green. Clean names and duplication. Do not add behavior. Stay green.
- Repeat for the next behavior.
Watch the fail
Mandatory. If you did not watch the test fail, you do not know it tests the right thing.
- Fail (assertion), not crash (syntax / import)
- Failure message matches what you expected
- Cause is "feature missing," not a broken test
Test already passes? You are testing existing behavior. Fix the test.
Green is minimal
YAGNI. Hard-code if that is enough for this test. Do not add options, retries, or helpers the test does not require.
Good tests
| Quality | Do | Don't |
| Minimal | One behavior. "And" in the name? Split. | validates email and domain and whitespace |
| Clear | Name the behavior | test1, works |
| Real | Assert on the code's behavior | Assert that a mock was called |
| Intent | Show the API you want | Hide the contract behind fixtures |
Example: bug fix
Bug: empty email accepted.
Red — rejects empty email calls submitForm({ email: '' }) and expects error: 'Email required'.
Watch the fail — assertion fails because the error is missing, not because the test cannot import the function.
Green — reject blank email. Nothing else.
Refactor — extract shared validation only if a later test demands it.
Rationalizations (all false)
| Excuse | Reality |
| Too simple to test | Simple code still breaks. The test is cheaper than the bug. |
| I'll test after | After-the-fact tests pass immediately and prove nothing. You never watched them catch the miss. |
| Same goals, skip the ritual | Tests-after ask "what does this do?"; tests-first ask "what should this do?" |
| Already manually tested | No record, no rerun, easy to miss edges. |
| Deleting hours of code is waste | Sunk cost. Untrusted code is the waste. |
| Keep as reference | You will adapt it. That is testing after. Delete. |
| Need to explore first | Explore, then throw it away and start at red. |
| Hard to test | The design is wrong. Simplify the interface. |
| TDD will slow me down | Debugging in production is slower. |
Red flags — delete and restart
- Production code before a failing test
- Tests written after the implementation
- Test passes on the first run
- Cannot explain why it failed
- "Just this once"
- "Keep as reference" / "adapt the existing code"
- "Spirit not ritual" / "I'm being pragmatic"
All of these mean: delete the production code. Start over at red.
When stuck
| Problem | Move |
| Don't know how to test | Write the wished-for API and the assertion first. Ask. |
| Test is a novel | Design is a novel. Shrink the interface. |
| Everything needs a mock | Too coupled. Inject dependencies. |
| Setup is huge | Extract helpers; if still huge, simplify. |
Bug found later? Reproduce with a failing test, then follow the cycle. Never ship a bugfix with no test.
Checklist
Before calling the work done:
- Each new behavior has a test
- Each test was watched failing for the right reason
- Production code was the minimum to go green
- Suite is green and output is clean
- Mocks only when unavoidable
- Edges and error paths covered
Missing a box? You skipped TDD. Restart.
Final rule
Production code exists only after a test existed and failed first. Otherwise it is not TDD. No self-exceptions — Ask first.
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.