tdd
Skill2 starsChanged 12 days agoMITView on GitHub
Build behavior test-first: red, green, one cycle per criterion, at the agreed seams. Use when /build picks it, or the user wants to work red-green-refactor.
194 other projects use a version of this.
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 · 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
- 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
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 repository22 other files it gives its agents.
The file
We split this skill into the rules it gives an agent
8 rules. 0 are common, 3 are distinctive, and 5 are very specific to this project.
0
Common
Most of the 187 edited versions we read keep these.
3
Distinctive
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 22
When the work holds a piece that no criterion covers, such as a layout, name each piece in one line: Build: <what>.
- Very specific: line 24
Read the code in parts. Find the lines that a criterion names with grep -n, and read those lines with their function.
- Distinctive: line 33
Green: write the least code that makes it pass.
- Distinctive: line 36
When a new test passes on its first run, it proves nothing yet.
- Very specific: line 47
After the last cycle, build each Build: piece from step 1 in its own commit: Build: <what>.
- Very specific: line 53
Read git diff <base>...HEAD in full.
- Very specific: line 58
Remove duplication, fix names, and move code to where it belongs.
- Distinctive: line 70
Horizontal: all tests first, then all code.
“Common” is measured: kept by at least 6 in 10 of the 187 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
TDD is the red, green loop. Each cycle is a tracer bullet: one failing test, then the least code that makes it pass. The criteria of the ticket, or the behaviors that the user names, are the list of cycles.
1. Prepare
Read the ticket or the request, with its spec when it has one, the glossary that docs/agents/domain.md names, and the ADRs for the area. When the repo has no docs/agents/domain.md, find the glossary as NO-SETUP.md in the folder of the setup-skills skill says. Look up in the glossary, and in its Avoid lists, each noun that you will use in a test, a component or a label, and each English word of the spec. Use the glossary words.
Find the seams in the spec's testing decisions. A seam is the public boundary where a test observes behavior. With no spec, the agreed seams are the ones that the existing tests of the area use. Write tests only at these seams. When a criterion cannot be tested at an agreed seam, stop and ask the user. Propose the new seam in one line: what it catches and what it misses.
When the work holds a piece that no criterion covers, such as a layout, name each piece in one line: Build: <what>.
Read the code in parts. Find the lines that a criterion names with grep -n, and read those lines with their function. Read a whole file only when it is the seam or its test file.
Completion: your message shows one line for each criterion, <criterion> · <seam> · <test file>, and one line for each Build: piece, before the first red. You looked up each noun and each English word in the glossary.
2. Loop
Take the criteria in order. For each criterion:
- Red: write one test at the seam. Run it. It must fail, and the failure message must be about the missing behavior, not a typo or an import. When the ticket or the spec gives a literal, such as a label or a message, the test uses that literal. When you think the literal is wrong, ask the user before the green.
- Green: write the least code that makes it pass. Add nothing for a later criterion.
- Commit:
Green: <criterion>.
When a new test passes on its first run, it proves nothing yet. Do one of these, and name it in the commit message:
- Take a later criterion first, when that criterion makes this test fail.
- Break a committed file for one run, see the test fail, and undo the break with
git checkout -- <file>.
A criterion that sets a rule for the tests, such as how each test sets the clock, gets no cycle. The report names the tests that follow it.
A criterion that keeps existing behavior, such as "marks still work", gets no cycle when existing tests cover it. The report names those tests. Run them after the last change. When this work changed those tests, say so in the report.
A criterion can take more than one cycle. Each cycle gets its own commit. Run the test file in each cycle, and the typecheck in each cycle that changes source.
After the last cycle, build each Build: piece from step 1 in its own commit: Build: <what>. Change only what the piece names.
Completion: each criterion has a passing test and a Green: commit, or names the existing tests that cover it, and each Build: piece has its commit.
3. Refactor
Read git diff <base>...HEAD in full. The base is git merge-base origin/<trunk> HEAD, or the start that a caller names. Then look for the duplication that a read of the diff alone does not show:
- For each new helper, search the codebase for one that does the same job.
- List each place that branches on the new case. Several checks that decide one case are one decision.
Remove duplication, fix names, and move code to where it belongs. Commit each change: Refactor: <what>. Run the test files of each change after it. Formatting is the linter's job, so a format change is no refactor.
Then run the repo's formatter and lint on the diff, and commit any change: Format: <files>. Then run the tests: the test files that the work adds or changes, and each test file that imports a module that it changes. When /build started you, stop there, because /ship runs the full check once. When you run on your own, run the full suite once. Wait for each result.
Completion: the formatter and lint pass, the tests that this step names passed after the last change, and each run has finished. A run in the background counts only when its result is in. You have no more changes to make.
Good tests
A good test checks behavior through a public interface. It reads like a line of the spec, and it survives a refactor. See tests.md for examples and mocking.md for when to mock.
- Implementation-coupled: the test mocks an internal module, tests a private function, or checks through a side door, such as a database query in place of the interface. It breaks on a refactor that keeps the behavior.
- Tautological: the expected value is computed the way the code computes it, so the test cannot fail. Take expected values from a known literal, a worked example or the spec.
- Horizontal: all tests first, then all code. The tests then check an imagined design. Write one test, then its code.
Report
Print the report in your message before you return to the caller:
- Each criterion with its test name, or with the existing tests that cover it.
- Each
Build:piece. - The commits.
- Each seam question and each literal question that the user answered.
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.

