Tdd

TDD

1. Purpose

/tdd is an implementation skill for changing production behavior by driving work with behavior tests that can be observed through a public interface or stable boundary. It is not generic testing advice. It is a way of implementing real changes through this sequence: observable behavior -> public interface -> observed failing behavior test -> minimal production code change -> observed green -> refactoring while green.

2. What TDD Means In This Skill

In this skill, TDD means:

• Choose one observable production behavior.
• Express it as a behavior test through a public interface or stable boundary.
• Run a focused test and observe it fail as expected.
• Implement only the production code needed to make that test pass.
• Confirm green.
• Refactor only while related tests stay green.

In this skill, TDD does not mean:

• Adding tests after implementation
• Directly testing every internal helper
• Mocking internal collaborators to verify call counts
• Writing all planned behavior tests up front
• Treating any failing test as a valid red
• Replacing an observed red with manual checking

3. When To Use It

Use it when:

• Adding or changing production behavior
• Fixing a bug that needs a regression test
• Designing behavior through a public interface or stable boundary
• Reviewing the TDD chain of AI-generated implementations or pull requests

Do not use the normal TDD cycle when:

• Doing pure investigation without changing behavior
• Making documentation-only or configuration-only changes
• Doing only mechanical renames, moves, or formatting

If needed, use exception mode from references/legacy-and-exceptions.md.

4. Mode Selection

At the start, state which of these modes the request belongs to:

• Implementation mode: Add, change, or fix production behavior. Required evidence is the target behavior, the public interface or stable boundary, the observed red, the minimal green, and the observed green.
• Review mode: Evaluate whether an existing implementation, pull request, plan, or AI-generated code preserves the TDD chain. Required evidence is the target cycle, sequence evidence, observed red or observed green depending on what evidence exists, whether the minimal green is valid, and re-green if refactoring happened. Read references/review-mode.md.
• Exception mode: The normal TDD chain cannot be applied directly. Required evidence is the reason for the exception, the constraint, the alternative taken, and the remaining risk. Read references/legacy-and-exceptions.md.

If the mode is ambiguous, clarify it before proceeding with implementation. For review requests, do not drift into implementation steps. Prioritize evidence gathering and judgment.

5. Core Principle

Every new or changed expected behavior has a corresponding behavior test. Tests verify outcomes a caller or user can observe, not private methods or internal call order. A TDD chain is only valid when it is connected by evidence of an observed red and an observed green.

6. TDD State Model

Plan
-> Choose one behavior
-> Write one behavior test
-> Run a focused test
-> Dirty red or clean red
-> Reach clean red
-> Minimal green
-> Confirm green
-> Refactor if needed
-> Confirm green again
-> Move to the next behavior

A dirty red is a failure that does not yet prove the missing behavior. Examples: the test file will not load, an import cannot be resolved, a symbol is missing, a function signature does not match, or setup fails before the assertion is reached. During dirty red, only changes that let the test reach its assertion are allowed, such as an empty stub, exporting a missing symbol, adjusting a signature, or returning a neutral placeholder value. Real business logic, generic implementation, future behavior, and unrelated refactoring are not allowed. These temporary changes must be removed once they have served their purpose after reaching clean red. If they remain in the final state, explicitly justify them as current behavior.

A clean red is when the test reaches its assertion for a new or changed expected behavior and fails because the target production behavior does not yet exist. Production logic may be added only after a clean red.

Minimal green is the smallest production code change that makes the current clean red pass. Do not add future options, extra error handling not required by the current behavior, new public methods, abstractions without pressure, or test changes made just to fit the implementation. Do not pass the test with test-only branching, hard-coded values, or dummy logic without real implementation intent. Choose a natural implementation for the same class of input, but do not add untested separate behaviors or branches. Here, a natural implementation means the smallest generalization that works for the same input family as the current failing test without introducing extra branching or a broader public surface. When judgment is unclear, read references/guarded-cycle.md.

Refactoring-safe green is the state in which related tests are green and refactoring is allowed. Clarifying renames, duplication removal, helper extraction, type improvement, deepening a module, reducing coupling, and improving test helpers are allowed. New behavior, changes to externally observable behavior, assertion changes that merely ratify the implementation, and refactoring during red are not allowed.

7. Standard Implementation Procedure

1. Choose one observable behavior as a small vertical slice. 2. Choose the public interface or stable boundary. 3. Write one behavior test. 4. Run a focused test and observe either dirty red or clean red. 5. If it is dirty red, make only the minimum change needed to reach the assertion. 6. Once clean red is observed, make the minimal production code change for green. 7. Confirm observed green with the focused test and related tests. 8. Refactor only if needed and only while green, then confirm green again. 9. Move to the next behavior.

Do not write many tests first and implement them all later. Do not implement many behaviors first and debug the full test suite afterward.

8. Planning Protocol

Before implementation, give a short plan:

Behavior:
Public interface or stable boundary:
Test location:
Expected red:
Minimal green hypothesis:
Risks or unknowns:

Do not ask the user for confirmation every time. Ask only when the public interface is unclear, the priority of behaviors is ambiguous, business rules conflict, existing ADRs or design constraints are unclear, or test difficulty implies an interface or design change.

9. Cycle Rules

• Each cycle handles exactly one behavior.
• Before implementation, write one behavior test.
• Run a focused test and observe red.
• During dirty red, only stubs, signature adjustments, export fixes, neutral placeholder returns, and minimal wiring are allowed.
• Temporary stubs, placeholder returns, and temporary wiring introduced for dirty red must be removed as soon as they are no longer needed in clean red or minimal green. If they remain, justify them as current behavior.
• Real logic requires a clean red first.
• Minimal green must not go beyond the behavior that is currently failing.
• Refactor only while green.
• After refactoring, rerun related tests.

10. Evidence Contract

Evidence during the work can stay concise:

Next behavior:
Target test:
Focused command:
Red:
Failure summary:
Green:
Pass summary:
Regression:

At completion, report:

Implemented behavior:
Added test:
Target test:
Focused command:
Observed red:
Failure summary:
Observed green:
Pass summary:
Checks not run:
Alternative checks:
Regression confirmation:
Refactoring:
Mocks:
TDD exceptions:
Untested risks:

Always write observed red and observed green. TDD depends on observed feedback, not claims. Target test, focused command, failure summary, and pass summary are the minimum items needed for a reviewer to replay the chain. Do not treat checks that could not be run as observed green.

11. Stop Conditions

Immediately stop production implementation and move to the recovery protocol if any of these happen:

• New or changed expected behavior entered production code without an observed red
• A test added after implementation is being presented as TDD
• A test claimed as the red for new or changed expected behavior passes immediately
• The failure is still dirty red but real logic is about to be added
• Multiple behaviors are being implemented in one cycle
• The implementation goes beyond the behavior that is currently failing
• Internal collaborators are being mocked without boundary-level justification
• Refactoring begins while related tests are still red

Recovery method:

• Name the broken TDD state
• If needed, isolate or revert code that introduced behavior too early
• Write or repair the behavior test
• Reach clean red
• Implement minimal green
• Ask for user confirmation only if recovery specifically requires it

12. Reference Guide

Read references/behavior-tests.md when deciding the test boundary, the test name, or whether a test is looking at behavior or implementation detail.

Read references/guarded-cycle.md when the red or green state is unclear, when implementation may be too early, or when overimplementation is suspected.

Read references/interface-design.md when behavior is hard to test or the public interface looks unstable.

Read references/mocking-policy.md before introducing mocks, spies, fake time, fake networks, fake database boundaries, or call-count assertions.

Read references/legacy-and-exceptions.md when changing legacy code, doing a spike, doing mechanical refactoring, or using a TDD exception.

Read references/review-mode.md when reviewing the TDD discipline of an existing implementation, pull request, plan, or AI-generated code.

13. Completion Checklist

• For each cycle, exactly one production behavior was chosen.
• A behavior test was written through a public interface or stable boundary.
• Observed red was recorded, and dirty red was not used as justification for real logic.
• Clean red existed before production logic.
• Minimal green did not go beyond the current behavior.
• Temporary dirty-red stubs, placeholder returns, and temporary wiring do not remain in the final state, or they are justified as current behavior.
• If refactoring happened, it happened only while green.
• Related tests were rerun after refactoring.
• Mocks were avoided, or justified as real boundaries.
• Target test, focused command, failure summary, and pass summary were recorded so the TDD chain can be rechecked.
• Checks that could not be run were not treated as observed green and were recorded as alternative checks or untested risks.
• If the normal TDD chain could not be applied, the exception was recorded.

tdd

このスキルは何か

観測できるふるまいを、公開インターフェースや安定した境界から 1 つずつテストに落とし込み、赤を確認してから最小の実装を入れていくためのスキルです。

作った意図

TDD は名前だけ広く知られていても、実務では「実装してからテストを足す」「内部メソッドを細かく直接テストする」「赤を見ないまま進める」といった形に崩れやすいことがあります。このスキルは、そうした形だけの TDD ではなく、実際に観測した失敗と成功をつないだ実装の進め方を保つために作っています。

特に、バグ修正や仕様変更のときに、何を 1 サイクルとして扱うか、どこまでを最小の green とみなすか、dirty red と clean red をどう区別するかを明確にしたい意図があります。

どういう人・場面に向いているか

• 機能追加やバグ修正を、後付けではなくテスト駆動で安全に進めたい人
• AI が作った実装が、本当に TDD の筋を通しているか確認したい人
• 内部実装ではなく、利用者から見えるふるまいを軸に設計と実装を進めたい人

使いどころの例

• バグ修正に対して、まず再現テストを作ってから最小修正を入れたい
• 新しいユースケースを、公開 API や画面操作などの境界から 1 つずつ足したい
• AI が書いた「TDD で実装しました」という変更に、実際に red と green の証拠があるか見たい

依頼イメージ

入力例: 「このバグを TDD で直して。まず再現テストを公開インターフェース経由で書いて、赤を確認してから最小修正を入れて」

返ってくるもの: 「今回の 1 サイクルで扱うふるまい」「どのテストで赤を観測したか」「最小の green にする修正」「必要なら green のまま行ったリファクタリング」をつないだ実装結果

関連するスキル

• review-orchestrator: TDD 観点だけでなく、実装全体を複数の視点でレビューしたいときに向いています
• quality-requirements-elicitation-coach: そもそも何をふるまいとして保証すべきか曖昧なときに先に使うと整理しやすいです

Behavior Tests

Behavior tests verify production behavior that a caller or user can observe. The goal is not to confirm which private method ran internally. The goal is to confirm that the contract of a public interface or stable boundary is being honored.

Test Boundaries

Preferred boundaries:

• Public API endpoints
• Entry points such as commands, handlers, CLI operations, or component boundaries
• Domain operations called from application code
• Database boundaries when persistence itself is the behavior

Do not directly test private methods. If some behavior can only be reached through a private helper, first suspect that the public interface may be too large, too hidden, or poorly bounded.

Do not couple tests to internal call order. If a behavior-preserving refactor breaks the test, the test is too dependent on implementation detail.

Test Intent

Good test intents:

• "Returns a validation error when the submitted email address is invalid"
• "Keeps the existing subscription active when payment authorization is declined"
• "Records an already-imported item only once even if the same source row is processed twice"

Bad test intents:

• "Calls email validation before saving"
• "Calls the user repository lookup exactly once"
• "Sets the private field to pending"

Good examples describe observable behavior. Bad examples mainly lock in implementation details.

Test Shape

One test should usually verify one logical behavior. If the test name contains "and", it may be packing multiple behaviors together. If those behaviors are separable from the caller's point of view, split them.

Test names should describe behavior, not implementation. Put the condition and the observable outcome in the name.

Assertions should check results that the caller depends on:

• Return values
• Returned responses
• Observable state transitions
• Persisted records when persistence is the behavior
• Messages or events when messages or events are part of the boundary contract

Use direct database inspection carefully. Prefer behavior-visible outcomes unless persistence writes themselves are the production behavior or the database is the stable boundary.

Refactor-Resistant Tests

If a test breaks after a behavior-preserving refactor, it may be too tightly coupled to internal structure.

Helpful test pressure:

• Clarifies the result the caller needs
• Exposes awkward inputs or outputs
• Finds hidden side effects
• Pushes toward a smaller public surface

Test pressure to avoid:

• Freezing private helper names
• Freezing collaborator call order
• Copying the current implementation
• Reimplementing the production algorithm inside the mock

Guarded Cycle

The guarded cycle is state management for preserving the TDD chain.

Observed red -> clean red -> minimal green -> observed green -> refactor while green

Red must be observed. A test that already passes is not evidence that a new test protects a new behavior. A test added afterward is not, by itself, evidence that the missing behavior failed first, so it does not prove a TDD chain.

Dirty Red

Dirty red is a failure that does not yet prove the missing behavior. Examples include the test file not loading, unresolved imports, missing exports, a mismatched signature, or setup failing before the assertion is reached.

Changes allowed during dirty red:

• Empty stubs
• Missing exports
• Signature adjustments
• Neutral temporary return values
• Minimal wiring needed to reach the assertion
• But no real business logic

Do not add real business logic during dirty red. Stubs, placeholder returns, and temporary wiring added for dirty red should be removed once they are no longer needed after reaching clean red. If they remain in the final state, explicitly justify them as current behavior.

Clean Red

Clean red means the test reaches its assertion and fails because the production behavior needed for the new or changed expectation is missing. Production logic may be added only after clean red.

If a test claimed as red passes immediately, stop. The behavior may already exist, the test may not be asserting the intended behavior, or the wrong test may be running.

Minimal Green

Minimal green is production code that exists only to make the clean red for the current behavior pass. It is not permission to complete the entire design. You may not pass the test with test-only branching, hard-coded values, or dummy logic without real implementation intent. By natural implementation, this skill means the smallest generalization that works for the same input family as the current failing test without increasing branching or expanding the public surface.

Examples of overimplementation:

• Adding options the current behavior does not require
• Adding error handling not present in the observed failing behavior test
• Introducing abstractions with no duplication or change pressure
• Adding public methods for future behavior
• Changing multiple behavior paths in one cycle
• Weakening assertions to make the test pass
• Adding branches or constants that only satisfy the test data

Rationalization Detection

Stop and inspect the TDD state when these phrases appear:

• "We'll add the test later"
• "This doesn't really need a test"
• "Manual checking is enough"
• "The implementation is already done"
• "This is just wiring"
• "This is only a small change"
• "Testing this is too difficult, so let's skip it"
• "The mock proves it works"
• "All the tests pass, so the new behavior is probably covered too"
• "It will be easier to do TDD after refactoring first"

Recovery is not punishment. It is a practical reset. Name the broken state, isolate or revert behavior that came too early if needed, write or fix the behavior test, reach clean red, then implement minimal green.

Recovery Protocol

1. Name the state: dirty red, missing red, overimplementation, post-hoc test, or refactoring during red. 2. Identify the smallest problematic production behavior. 3. If production behavior came too early, isolate or revert the too-early part as needed. 4. Write or repair the behavior test through a public interface or stable boundary. 5. Run a focused test and observe either dirty red or clean red. 6. If it is dirty red, add only empty stubs, missing exports, signature adjustments, neutral placeholder returns, or minimal wiring until the assertion-level failure is reached. 7. After clean red, add minimal green. 8. Confirm observed green. 9. Refactor only while green, then confirm green again.

Interface Design

TDD should apply pressure to the interface, not freeze a bad internal structure in place. When behavior is hard to test, treat that as design feedback.

Difficulty in testing often signals difficulty in use, a poor boundary, or hidden side effects. Before reaching for private-method tests or internal mocks, reconsider the public interface or stable boundary.

Design Guidance

• If a dependency is a real boundary, prefer receiving it rather than creating it internally.
• Prefer returning results over hiding everything behind side effects.
• Keep the public surface small.
• Use stable boundaries in tests.
• Do not create shallow modules just to make tests easier.
• Let behavior tests expose awkward inputs, awkward outputs, and responsibility-placement problems.

Stable Boundaries

A stable boundary is a contract a caller can reasonably depend on.

• Request and response shapes
• Command inputs and outputs
• Domain operations exposed to application code
• Event or message schemas
• Persistence contracts when persistence is the behavior

Do not treat an internal function as a stable boundary just because it happens to be easy to call.

Deep Modules

A good module has a small interface and useful depth. It hides meaningful complexity behind a small interface.

Do not add thin wrappers just for testing. A wrapper that only forwards calls without creating a real boundary can increase brittleness rather than testability.

Feedback From Testability

When behavior tests are hard to write, check:

• Is the caller-visible behavior clear?
• Is the operation carrying too many responsibilities?
• Are dependency boundaries hidden inside the function?
• Are results observable only through brittle side effects?
• Would a smaller, deeper public interface make the behavior easier to express?

Change the interface only when it improves the production design. Do not change it just to shorten tests.

Legacy And Exceptions

TDD needs to stay usable even in legacy work. When the normal TDD chain cannot be started cleanly, treat that as an explicit mode rather than a vague excuse.

Characterization Mode

Use this before changing existing untested code, to understand and pin the current behavior. This is not a replacement for the normal TDD cycle. It is an explicit pre-step before beginning the normal TDD cycle.

Procedure:

1. Observe the existing behavior. 2. Write a characterization test. 3. Confirm that the characterization test passes. 4. Write a failing test for the intended behavior change. 5. Implement the minimal change. 6. Confirm that existing behavior still holds.

A characterization test records current behavior, but it does not waive the need for an observed failing behavior test for the new change.

Spike Mode

Use this when design, API behavior, or library behavior is unknown and exploration is required.

Rules:

• The output of a spike is knowledge, not production code.
• Do not mix spike code directly into production code.
• After the spike, reimplement through a TDD cycle.

Record what the spike taught you and which production behavior should be tested first.

Mechanical Refactoring Mode

Use this for behavior-preserving mechanical changes such as renames, moves, formatting, or type-only changes.

Rules:

• Green evidence is required before the change.
• Behavior must not change.
• Confirm tests after the change.

If a behavior change becomes necessary, stop mechanical refactoring mode and resume the TDD cycle.

Configuration Or Documentation Mode

Use this for documentation-only or configuration-only changes.

Rules:

• It is valid only when production behavior is untouched.
• If configuration changes runtime behavior, treat that as production behavior and apply a TDD cycle, or explicitly record an exception.

Emergency Mode

Use this when an urgent production fix is required before the normal cycle can be completed.

Rules:

• State that it is an exception.
• State the risk.
• Add a follow-up testing plan.

Required exception log:

TDD exception:
Reason:
Risk:
Follow-up testing plan:
Deadline:
Tracking destination:

Emergency mode is not a shortcut around normal engineering pressure. It is explicit risk acceptance.

Mocking Policy

Mocks are mainly allowed at system boundaries. Use them to observe production behavior without directly touching systems that are unavailable, slow, random, or external.

Usually Acceptable Mock Boundaries

• External HTTP APIs
• Clocks and time
• Randomness
• File systems
• Networks
• Payment, email, and third-party providers
• Database boundaries when preparing a real database would be disproportionately heavy

Prefer fakes or contract-level test doubles that express the behavior of the boundary clearly, rather than call-count assertions.

Usually Not Allowed

• Private methods
• Internal modules
• Domain services owned inside the codebase
• Repositories mocked only to assert call counts
• Mocks that reproduce implementation logic

Mocking internal collaborators easily turns behavior tests into implementation-detail tests. If a test only proves that one internal object called another internal object, it probably is not protecting observable behavior.

Danger Signals

• Mock setup is longer than the assertion
• The test mainly checks "called with these arguments" or call counts
• The test passes even if real behavior is broken
• The test is really testing the mock's behavior
• Removing the mock makes the test meaningless

Boundary Justification

Before introducing a mock, write a short justification:

Boundary:
Why using the real dependency is disproportionate:
Observable behavior being protected:
Risk if the mock drifts:
How drift will be detected:

If the mock is not tied to observable behavior, do not add it. For How drift will be detected, state whether drift is caught by a contract test, a thin integration test, a smoke test, or why none applies.

Review Mode

Review mode checks whether an implementation, pull request, plan, or AI-generated code preserves the TDD chain. It is a mode integrated into /tdd, not a separate skill.

Do not look only at the final test file. Check the sequence:

• Which production behavior was chosen
• Which public interface or stable boundary was used
• Whether there was an observed failing behavior test
• Whether the red was dirty red or clean red
• Whether production logic waited for clean red
• Whether the implementation was minimal green
• Whether refactoring happened only while green
• Whether mocks were justified as real boundaries

Severity

Blocker:

• New or changed expected behavior entered production code without an observed red
• A post-hoc test is being presented as TDD
• A test claimed as the red for a new or changed expected behavior passes immediately

Major:

• Implementation-detail tests
• Unnecessary internal mocks
• Overimplementation beyond the current behavior
• Refactoring mixed with behavior changes
• Using dirty red as permission to add real logic

Minor:

• Unclear test names
• Multiple behaviors packed into one test
• Missing evidence summary

Judgment labels:

• TDD chain unproven
• Partially verified
• Verified

Application rules:

• If there is no sequence evidence, use TDD chain unproven
• If only red can be confirmed, use Partially verified and write red only in the evidence field
• If only green can be confirmed, use Partially verified and write green only in the evidence field
• If the target cycle includes red, minimal green, and observed green, use Verified
• If refactoring happened, use Verified only when re-green can also be confirmed

Output Format

Use this format for each finding:

Finding:
Severity:
Judgment:
Broken TDD principle:
Evidence:
Risk:
Recovery instruction:

Recovery instructions should give concrete steps the implementer can use to restore the TDD chain. Do not stop at criticism.

Review Guidance

Prioritize concrete evidence:

• Commit order or diff order, when available
• Test output showing observed red or green
• Test names and assertions
• Production code that goes beyond the current behavior
• Mocks that verify internal collaboration instead of behavior

If sequence evidence is unavailable, say so clearly and review the artifacts that do exist. Do not claim TDD happened just because tests exist.