Test-Driven Development
Use a few behavior tests through the public interface. This skill is opt-in
when the user asks for TDD/test-first, or repository instructions require
that cycle. Follow codebase-design for shared readability
rules and when-to-write-tests for test scope.
When to use
- The user asked for TDD, test-first, or red-green-refactor
- Repository instructions require a failing-test-first cycle for the change
When not to use
- Ordinary implementation or refactors without a TDD request or requirement
- Private helper moves, comment edits, or docs edits alone
- A request for a contract test without a request or requirement for TDD; use
when-to-write-tests to choose that test
- "Every new function/method"
- Edges an advisory invented that are not the contract
- Existing tests already cover the public behavior
Default is no new test. Smoke the changed path. See
.
What to write
One (or a few) tests that walk the real path: input at the public boundary → through the system → observable result.
Good: seed the old inbound tables, apply the migration, list events, assert facts and metadata survived.
Bad: a test per helper, encoder, or bind-list rewrite.
Prefer real collaborators over mocks. Exercise the route/store/UI path for
those contracts; test a public pure function through its inputs and outputs. Supporting notes: tests.md, mocking.md.
Where tests live
Next to the source:
beside
. Do not create a separate top-level
or
directory in a package for these.
Exception: an end-to-end test that spawns the real server or CLI, or spans packages, lives in the repo-root
(for example
).
Cycle (only when this skill applies)
- Name one observable behavior in a sentence.
- Write one failing test through its public interface.
- Write the simplest complete implementation that makes it pass.
- Refactor only when it improves understanding; keep related logic together.
- Repeat for the next required behavior. Do not add tests for each new helper.
Include failure, completion, and cleanup behavior when the contract requires it;
a public pure function does not need an application-wide E2E harness.
Do not delete working code to restart TDD. Outside a requested or required TDD
cycle, use the repository's proportional validation policy.
Conflicts
User instructions and repository requirements take precedence. Use
to avoid redundant tests, not to waive required public
behavior or lifecycle coverage.