tdd
Use when writing or changing production behavior: implementing a feature, fixing a bug whose cause is already known, or altering stored, transformed, migrated, serialized, or externally transmitted data. Also use when a user says "use TDD", "test first", or "red-green-refactor", and when code is being written before a failing test. For a failure whose cause is unknown, diagnose first.
- License 许可
- MIT
- 最近更新
- 2026-11-12
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- tdd
- license
- MIT
- metadata
- { "summary": "Enforces observable red-green-refactor cycles through stable behavior seams, with real data-boundary evidence.", "category": "Building" }
- description
- Use when writing or changing production behavior: implementing a feature, fixing a bug whose cause is already known, or altering stored, transformed, migrated, serialized, or externally transmitted data. Also use when a user says "use TDD", "test first", or "red-green-refactor", and when code is being written before a failing test. For a failure whose cause is unknown, diagnose first.
02 资源文件 37
- 其他evals/cases.jsonl4.5 KB
- 参考文档evals/fixtures/customer-migration/fixtures/customers.json89 B
- 参考文档evals/fixtures/customer-migration/package.json132 B
- 参考文档evals/fixtures/customer-migration/README.md572 B
- 脚本evals/fixtures/customer-migration/src/migrate-customers.js161 B
- 参考文档evals/fixtures/free-shipping/package.json127 B
- 参考文档evals/fixtures/free-shipping/README.md276 B
- 脚本evals/fixtures/free-shipping/src/shipping.js63 B
- 参考文档evals/results/atomic-restore-2026-09-07/heldout-free-shipping/case.json1.2 KB
- 参考文档evals/results/atomic-restore-2026-09-07/heldout-free-shipping/output.md1.2 KB
- 参考文档evals/results/atomic-restore-2026-09-07/heldout-free-shipping/result.json786 B
- 参考文档evals/results/atomic-restore-2026-09-07/heldout-free-shipping/workspace-after/package.json127 B
- 参考文档evals/results/atomic-restore-2026-09-07/heldout-free-shipping/workspace-after/README.md276 B
- 脚本evals/results/atomic-restore-2026-09-07/heldout-free-shipping/workspace-after/src/shipping.js233 B
- 脚本evals/results/atomic-restore-2026-09-07/heldout-free-shipping/workspace-after/test/shipping.test.js575 B
- 参考文档evals/results/atomic-restore-2026-09-07/prompt-template.md959 B
- 参考文档evals/results/atomic-restore-2026-09-07/README.md2.3 KB
- 参考文档evals/results/atomic-restore-2026-09-07/regression-code-first-pressure/case.json1.1 KB
- 参考文档evals/results/atomic-restore-2026-09-07/regression-code-first-pressure/output.md1.3 KB
- 参考文档evals/results/atomic-restore-2026-09-07/regression-code-first-pressure/result.json775 B
- 参考文档evals/results/atomic-restore-2026-09-07/regression-code-first-pressure/workspace-after/package.json127 B
- 参考文档evals/results/atomic-restore-2026-09-07/regression-code-first-pressure/workspace-after/README.md276 B
- 脚本evals/results/atomic-restore-2026-09-07/regression-code-first-pressure/workspace-after/src/shipping.js233 B
- 脚本evals/results/atomic-restore-2026-09-07/regression-code-first-pressure/workspace-after/test/shipping.test.js627 B
- 参考文档evals/results/atomic-restore-2026-09-07/regression-data-boundary/case.json1008 B
- 参考文档evals/results/atomic-restore-2026-09-07/regression-data-boundary/output.md1.4 KB
- 参考文档evals/results/atomic-restore-2026-09-07/regression-data-boundary/result.json782 B
- 参考文档evals/results/atomic-restore-2026-09-07/regression-data-boundary/workspace-after/fixtures/customers.json89 B
- 参考文档evals/results/atomic-restore-2026-09-07/regression-data-boundary/workspace-after/package.json132 B
- 参考文档evals/results/atomic-restore-2026-09-07/regression-data-boundary/workspace-after/README.md572 B
- 脚本evals/results/atomic-restore-2026-09-07/regression-data-boundary/workspace-after/src/migrate-customers.js429 B
- 脚本evals/results/atomic-restore-2026-09-07/regression-data-boundary/workspace-after/test/migrate-customers.test.js1.3 KB
- 参考文档evals/results/atomic-rewrite-2026-08-29.md2.0 KB
- 参考文档evals/results/README.md4.0 KB
- 参考文档evals/results/tier2-2026-08-01.md4.9 KB
- 参考文档evals/skill-brief.md2.6 KB
- 参考文档references/pressure.md1.2 KB
03 SKILL.md 正文
Test-Driven Development
No new production behavior before an observed, behaviorally valid red test. Work one red-green-refactor tracer bullet at a time. Prove the test detects missing behavior. Write the smallest green change. Refactor only while green.
Scope
Use for:
- New caller- or user-visible behavior.
- Fixes for bugs whose cause is already known.
- API, validation, workflow, or state changes.
- Stored, transformed, migrated, serialized, or transmitted data.
- Legacy behavior that needs a stable test seam.
- Work where agent-authored production code appeared before red.
Do not use for:
- Unknown root causes. Diagnose first.
- Documentation, formatting, generated output, or mechanical renames with no behavior effect.
- Immediate incident containment. Restore service first; test-drive the permanent fix.
- Throwaway prototypes. Restart under TDD before shipping or using one as a reference implementation.
When another workflow owns the task, use TDD at its implementation seam. Adversarial testing of the finished result is a separate task (verify-work when installed); it is not part of this workflow.
Required Context
Establish:
- One requested observable behavior and its source of truth.
- Repository instructions and current worktree ownership.
- The existing test framework, focused command, and affected-suite command.
- The narrowest stable public seam.
- Any real persistence, serialization, migration, retry, or external boundary.
Use existing test tools and conventions. Ask one question only when behavior or the correct seam cannot be inferred safely.
Done when one behavior, one seam, one red command, and worktree authority are explicit.
Workflow
1. Restore red-first order
Inspect the diff. If the agent wrote production code for the active behavior before red, revert only those known agent-authored hunks. Never comment them out, copy them into notes, or consult them while designing the test, so the test comes from the contract, not from the implementation.
Preserve pre-existing and user-authored work. Ask before reverting when authorship is ambiguous. Existing legacy code is not a violation; test its new expectation directly.
Done when no agent-authored implementation for the active behavior precedes its test.
2. Choose one tracer bullet
Test one observable behavior through the narrowest stable public seam. Use a unit seam for pure logic. Use an integration seam for real boundaries. Use end-to-end only when smaller tests cannot represent the contract.
Assert public outcomes. Never assert private methods, incidental call counts, or an expected value calculated by the algorithm under test.
For legacy code without a stable seam:
- Characterize current observable behavior.
- Keep that test green while creating the smallest behavior-preserving seam.
- Write the new behavior test at that seam.
Stop when no meaningful seam can be created safely. A shallow test that cannot catch the defect is not progress.
For data paths, choose the seam from this table before writing the test:
| Path | Evidence |
|---|---|
| Pure transformation | Representative inputs, outputs, and boundary values |
| Database write | Isolated test database or transaction |
| Migration | Before/after fixture; rollback when supported |
| Retry or upsert | Duplicate execution without corruption or unintended duplication |
| Serialization or file output | Write, read back, and validate bytes or representation |
| External service | Faithful fake or contract-tested adapter; never production |
Mocks may isolate nondeterministic external systems, time, or randomness. Mocks alone never prove stored, migrated, serialized, or transmitted data. Test public results instead of internal collaborator calls.
Done when the test names one behavior, can fail specifically when that behavior is absent, and exercises the closest real boundary of every data contract it changes.
3. Prove valid red
Write the smallest test for the active behavior. Include a boundary or failure case when it defines the same contract. Run the focused command and capture its output.
Red counts only when the behavioral assertion fails for the expected reason. Syntax errors, imports, missing dependencies, broken fixtures, unrelated timeouts, manual throws, skips, and unrelated failures do not count. Repair setup without changing production behavior until the right assertion fails.
If the test passes first, check whether behavior already exists or the test is insensitive. Strengthen the test from the contract. Never break production code to manufacture red.
Done when the focused command's captured failure identifies the missing behavior.
4. Make the smallest green change
Write only enough production code to satisfy the red test. Run the same focused command after each small change. Add no speculative options, abstractions, adjacent cleanup, or unrequested behavior.
Keep the test contract fixed. Never weaken assertions, relax input, blindly update snapshots, skip tests, or redefine the requirement to manufacture green. Stop for confirmation when the requirement appears wrong, then re-establish valid red.
Done when the unchanged test is green because production behavior satisfies it.
5. Refactor while green
Improve names, duplication, boundaries, or structure only after green. Run the focused test after each refactor. Revert a refactor that breaks it.
Start every new behavior as a new red-green-refactor cycle. Pick the next smallest requested behavior or boundary case and repeat from step 2. Keep only tests that protect observable contracts.
Done when the code is as simple as the proven behavior permits and the test remains green.
6. Verify and report
Run:
- Every new or changed focused test.
- The affected package or subsystem suite.
- The full repository suite when proportionate and available.
Inspect the diff for weakened assertions, skipped or focused-only tests, blind snapshot updates, unrelated code, and temporary fixtures.
Report the red command and decisive failure. Report the green command and result. Report affected and full-suite results, or why a suite was not run. Name changed files.
Follow the discipline silently while working. Deliver evidence, not a TDD lecture.
Done when every requested behavior and material boundary case completed its own observed cycle, the evidence is reproducible, the diff is scoped, and every unrun check is named.
Core Example
Request: “Treat usernames that differ only by case or surrounding spaces as the same user.”
Write the behavior test first:
import assert from "node:assert/strict";
import test from "node:test";
import { createUserStore } from "../src/users.js";
test("a username is taken regardless of case or surrounding spaces", () => {
const users = createUserStore();
users.register("ada");
assert.throws(() => users.register(" Ada "), /taken/);
});
Run node --test test/users.test.js. Capture the expected failure: the second register does not throw. Then implement only the normalization, applied before the existing uniqueness check:
const normalize = (name) => name.trim().toLowerCase();
Run the same command green, then the affected suite. A normalizer written first followed by a first-run-green test has no red evidence and fails this workflow.
Pressure
Read references/pressure.md when urgency, authority, sunk cost, or an uncertain shortcut threatens the workflow. Those pressures do not waive its evidence or authority requirements.
Genuine Exceptions
When a rule is genuinely impossible, name the blocked rule and show the evidence. Use the closest safe alternative and state the weaker conclusion. A missing or broken test framework needs reported evidence and authorization before installing or replacing tooling. Ask once per session: add a minimal test setup, or proceed without red and say so in the report. Apply the answer to later changes without asking again. An unavailable real data boundary takes the closest faithful substitute; never imply a mock proved persistence. Time pressure, tiny size, sunk cost, a green existing suite, and "just code it" never qualify.
Verification
- Every production behavior follows an observed, valid red test.
- Premature agent work is reverted without touching user work.
- Tests use stable public seams and independent expectations.
- Data changes prove their closest real boundary.
- Every cycle reaches minimal green before refactoring.
- No test or requirement is weakened to manufacture green.
- Focused and affected suites pass; full-suite omissions are explicit.
- Final evidence names red, green, and verification commands.
No new production behavior before valid red. Restore the order whenever it breaks.
04 同仓库更多 Skills
write-agent-instructions
Make the smallest evidence-backed change to persistent project instructions and test downstream behavior.
verify-work
Use when a finished, runnable artifact (a script, config, parser, prompt, or CLI, not a diff under review) must survive hostile input before shipping: the user asks to "verify this script", "find the loopholes", "test this properly against bad input", or asks "is this ready to ship" about one. Also when a shipped artifact failed on an input nobody tried, or when verification so far is a happy-path smoke test.
understand-codebase
Use when the user asks to "understand this codebase", "how does this feature work in this repo?", "trace this feature through the code", or needs onboarding, an architecture explanation, or answers about unfamiliar code. Also use for read-only code-path questions before a change.
simplify-code
Use when the user asks to "simplify this code", "remove the fluff", or "clean up this over-engineered module", or wants working code that is bloated, duplicated, over-abstracted, or dependency-heavy reduced without changing behavior.
review-session
Review an agent session for evidence-backed friction and the smallest measurable remedies.
review-code
Use when a user asks to "review this branch", "review this PR", "review my changes", or "review since main". Also use when asked whether a branch, PR, or diff is ready to merge or ship, and for work-in-progress diffs, staged changes, suspected regressions in a patch, or checking implementation against a specification.