tdd-loop
Skill9 starsChanged 2 months agoMITView on GitHub
Writes the failing test first, watches it fail for the right reason, then makes it pass with the smallest change. Use before implementing any feature or bug fix, when adding a regression test, or when a change needs proof it works. Refuses to write implementation code before a red test exists.
9 other projects use a version of this.
Adopted by
Most recently taken up by
- milad-ahmd/agent-skillstheir own version, first seen Nov 8, 2026
- OrionArchitekton/orion-skillstheir own version, first seen Nov 2, 2026
- michaelalber/ai-toolkittheir own version, first seen Nov 1, 2026
- daniel-kindl/dkstacktheir own version, first seen Nov 1, 2026
- sbradl/claude-skillstheir own version, first seen Oct 15, 2026
- dagarre00/claude-code-templatetheir own version, first seen Oct 15, 2026
Other versions9 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 9
- ramboz/jig★ 7same name
- milad-ahmd/agent-skills★ 5same name
- michaelalber/ai-toolkit★ 3same name
- OrionArchitekton/orion-skills★ 2same name
- qyndex/claude-init★ 2same name
- dagarre00/claude-code-template★ 1same name
- daniel-kindl/dkstack★ 1same name
- itsmuskanagarwal/claude-pack★ 0same name
- sbradl/claude-skills★ 0same name
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 repository28 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- api-designSkill
- architecture-decisionSkill
- autonomous-relaySkill
- browser-verificationSkill
- code-review-passSkill
- data-analysisSkill
- data-modelingSkill
- data-pipelineSkill
- data-qualitySkill
- documentationSkill
- firmware-buildSkill
- frontend-buildSkill
- incident-responseSkill
- incremental-deliverySkill
- ml-lifecycleSkill
- performance-passSkill
- release-and-rollbackSkill
- requirements-interviewSkill
- security-hardeningSkill
- simplification-passSkill
- spec-writingSkill
- systematic-debuggingSkill
- team-escalationSkill
- using-agent-dev-teamSkill
- work-breakdownSkill
The file
We split this skill into the rules it gives an agent
7 rules. 0 are common, 6 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 9 edited versions we read keep these.
6
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 19
Red: Write one failing test for the next smallest piece of behavior.
- Distinctive: line 20
Run it: Read the failure message. Confirm it fails for the reason you expect.
- Distinctive: line 22
Green: Write the smallest change that makes it pass.
- Distinctive: line 29
Commit at each green. A green commit is a safe point to return to.
- Distinctive: line 33
Start from the acceptance criterion, not from the function you plan to write.
- Distinctive: line 41
If you cannot write the test because you do not know what the behavior should be, that is a requirements problem.
- Very specific: line 45
If you cannot write the test because the code is hard to reach, that is a design problem.
“Common” is measured: kept by at least 6 in 10 of the 9 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 discipline is not "have tests". It is watch the test fail before you make it pass. A test you never saw red proves only that it passes, which is also true of a test that asserts nothing.
The loop
- Red. Write one failing test for the next smallest piece of behavior.
- Run it. Read the failure message. Confirm it fails for the reason you expect. A test failing on an import error or a typo is not red, it is broken.
- Green. Write the smallest change that makes it pass. Not the general version. Not the version you can already see you will need.
- Run the whole suite. A green new test with a red suite is a broken build.
- Refactor. With the suite green, improve the shape. Tests do not change during a refactor; if they must, it was not a refactor.
- Repeat.
Commit at each green. A green commit is a safe point to return to.
Writing the first test
Start from the acceptance criterion, not from the function you plan to write. The test names the behavior a caller cares about:
Bad: sumLines returns 0 for []
Good: an empty cart totals zeroIf you cannot write the test because you do not know what the behavior should be, that is a requirements problem. Stop and ask, or escalate. It is not a reason to write the code first and infer the behavior from it.
If you cannot write the test because the code is hard to reach, that is a design problem.
The seam is missing. Escalate to senior-engineer rather than mocking around it.
For a bug fix
- Reproduce the bug in a test. The test fails with the same symptom the user reported.
- Name the test after the bug, not the fix: "rejects a refund larger than the original charge".
- Fix it.
- The test now passes, and it stays in the suite forever as the guard.
A bug fix without a reproducing test will be reintroduced.
Choosing the level
The cheapest level that would actually catch the failure. Unit for logic and boundaries;
integration for wiring, serialization, and queries; end to end for the one critical path
a user walks. See references/testing-patterns.md.
When the test is written after the code
Sometimes it is. Then you must manufacture red: break the implementation deliberately, run the test, confirm it fails, restore the implementation, confirm it passes. Skipping this leaves you with a test that passes for reasons you have not verified.
Verification
Report all four, quoted:
Red: <the failing run, with the assertion message>
Green: <the passing run>
Suite: <the full-suite summary line>
Build: <type check or build summary line>Then check references/definition-of-done.md.
Red flags
| Thought | Reality |
| "It is too small to test" | Small changes break things. The test costs a minute. |
| "I'll write the tests at the end" | Then they are written to fit the code, and they test your implementation rather than the requirement. |
| "The test passed the first time I ran it" | Then you have not seen it fail. Break the code and watch. |
| "It fails, that is enough" | Read why it fails. An import error is not a red test. |
| "I'll make it general while I'm here" | Smallest change. The general version is usually the wrong general version. |
| "Refactoring broke a test so I updated the test" | Then it was a behavior change. Separate the commits. |
| "Six mocks were needed but it works" | Six mocks is a design finding. Escalate it. |
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.