Hai Tdd

Hai TDD

For Chinese readers, see SKILL.zh_CN.md. The English SKILL.md is the execution source of truth.

Overview

Drive development with tests: write a failing test first, confirm it fails for the right reason, write the smallest implementation that passes, then refactor while keeping tests green. This is not "add tests at the end" — TDD defines behavior before implementation.

Core Principle

Red, then green, then refactor.

Do not write production code before a failing test. A test that never failed first has not proven it constrains the target behavior — so the RED failure is the evidence, not a formality. If implementation already exists without a test, do not call the process TDD; either label it as tests-after or return to a test-first path.

Skip or ask first when

The skill is already triggered; the open decision is whether TDD fits this change. Pause and confirm with the user when:

• The work is a throwaway prototype or a spike, or the user asked for code reading before implementation.
• The change is pure configuration, copy, or styling.
• The behavior cannot reasonably be verified automatically yet.

Workflow

1. Define the target behavior.

• Pick one minimal behavior slice.
• State input, output, side effect, boundary, and failure condition.
• If the work is too broad, use hai-goal to split it into verifiable phases.

2. RED: write the failing test first.

• The test name should describe behavior, not say "works".
• Test one behavior at a time.
• Prefer public APIs, user-observable behavior, or stable boundaries — they keep the test stable when you refactor internals.
• Avoid mocks unless external systems, time, network, randomness, or permissions force them; mocks tie the test to implementation and hide real behavior.

3. Verify RED.

• Run the smallest relevant test command and confirm the test fails.
• Confirm it fails because the target behavior is missing, not because of syntax, imports, bad test code, or environment setup — that distinction is what makes the RED a real constraint rather than a broken test.
• If the test passes immediately, it did not prove new behavior; fix the test.

4. GREEN: write the minimal implementation.

• Write only enough code to pass the current test. Extra code is unverified by any failing test, so it falls outside TDD's safety net.
• Do not add future features and do not mix in unrelated refactors.
• Do not skip the minimal implementation step for a larger "complete" design.

5. Verify GREEN.

• Rerun the relevant tests.
• Confirm the new test passes.
• Based on risk, run broader tests for the directory, module, or full suite.

6. REFACTOR.

• Refactor only after green.
• Improve duplication, naming, structure, or boundaries.
• Rerun tests after refactoring.

7. Continue with the next behavior.

• Every new behavior returns to RED.
• Do not put multiple behaviors into one large test.

Test Quality Bar

Good TDD tests:

• Test behavior rather than implementation details.
• Have names that communicate business or system meaning.
• Fail with a message that points to the missing behavior.
• Are stable under refactoring.
• Are small, but not brittle white-box tests.
• Serve as behavior documentation for future maintainers.

Common Mistakes

Traps not already caught by the workflow steps above:

• Distorting the production API just to make tests convenient — the test should adapt to a good design, not the design to the test.
• Testing only whether a mock was called, not the real behavior, so the test passes even when the behavior is wrong.

Use a different skill when

• The work is too broad to slice into one verifiable behavior, or the goal/phasing is unclear — use hai-goal to turn it into verifiable phases first, then return here to drive each phase.
• The question is module boundaries, abstraction depth, or dependency direction rather than behavior under test — use hai-architecture.
• You are deciding whether the feature is worth building at all — use hai-idea.
• You are choosing the name of the unit, function, or concept under test — use hai-naming.

Output

Report using references/output-template.md — fill every RED / GREEN / REFACTOR field with real evidence; do not collapse it to "tested, passing". Read the template before finalizing.

Hai TDD 输出模板

用于记录 TDD 执行过程。不要只写“已测试”，必须给出 RED/GREEN/REFACTOR 的证据。

# Hai TDD: <feature or bug>

## Target Behavior
<本轮要驱动的最小行为切片。>

## RED
- **Test added**: `<test file or test name>`
- **Behavior asserted**: <测试约束的行为>
- **Command**: `<command>`
- **Observed failure**: <失败信息摘要>
- **Failure is correct because**: <为什么这是目标行为缺失，而不是测试/环境错误>

## GREEN
- **Minimal implementation**: <做了哪些最小代码改动>
- **Command**: `<command>`
- **Observed pass**: <通过结果摘要>

## REFACTOR
- **Refactor done**: yes / no
- **Change**: <命名、去重、结构调整，或 no refactor needed>
- **Command after refactor**: `<command or not needed>`
- **Observed result**: <通过结果摘要>

## Next Behavior
<下一个需要进入 RED 的行为，或 done。>

Hai TDD 中文版

本文件是中文阅读版；执行规则以 SKILL.md 为准。

概览

用测试驱动开发：先写失败测试，确认它因为正确原因失败，再写最小实现让测试通过，最后在测试保持通过的前提下重构。它不是"最后补测试"——TDD 先定义行为，再实现行为。

核心原则

先红，再绿，再重构。

没有先失败的测试，就不要写生产代码。测试如果没有先失败过，就不能证明它真的约束了目标行为——所以 RED 的失败是证据，不是走过场。已经写了实现但没有测试时，不要假装这是 TDD；要么说明这是 tests-after，要么回到测试先行。

何时先停下来确认

skill 已经触发；还没定的是这次改动到底适不适合 TDD。遇到以下情况，先和用户确认：

• 这是用完即弃的原型或 spike，或者用户要求先读代码再实现。
• 改动纯粹是配置、文案或样式。
• 行为暂时还无法合理地自动验证。

工作流

1. 明确目标行为。

• 选一个最小行为切片。
• 说清输入、输出、副作用、边界和失败条件。
• 如果范围太大，先用 hai-goal 拆成可验证的阶段。

2. RED：先写失败测试。

• 测试名应描述行为，而不是写"works"。
• 一次只测一个行为。
• 优先针对公开 API、用户可观察行为或稳定边界——这样重构内部实现时测试不会跟着碎。
• 除非外部系统、时间、网络、随机性或权限逼着你 mock，否则不要 mock；mock 会把测试绑死在实现上，掩盖真实行为。

3. 验证 RED。

• 运行最小相关的测试命令，确认测试失败。
• 确认它失败是因为目标行为缺失，而不是语法、import、测试代码本身或环境配置出错——正是这个区分让 RED 成为真正的约束，而不是一个坏掉的测试。
• 如果测试一上来就通过，它没有证明任何新行为；修测试。

4. GREEN：写最小实现。

• 只写刚好让当前测试通过的代码。多写的代码没有任何失败测试约束它，落在 TDD 的安全网之外。
• 不要顺手加未来功能，也不要混入无关重构。
• 不要为了一个更"完整"的设计而跳过最小实现这一步。

5. 验证 GREEN。

• 重跑相关测试。
• 确认新测试通过。
• 按风险扩大范围，跑目录、模块或全量测试。

6. REFACTOR。

• 只在绿灯后重构。
• 改善重复、命名、结构或边界。
• 重构后重跑测试。

7. 进入下一个行为。

• 每个新行为都重新进入 RED。
• 不要把多个行为塞进一个大测试。

测试质量要求

好的 TDD 测试：

• 测行为，而不是实现细节。
• 名字能传达业务或系统含义。
• 失败信息能指向缺失的行为。
• 对重构不敏感。
• 小，但不是脆弱的白盒测试。
• 能作为未来维护者的行为文档。

常见错误

工作流步骤还没覆盖到的坑：

• 为了测试方便而扭曲生产 API——应该让测试去适配好设计，而不是让设计去迁就测试。
• 只测试 mock 有没有被调用，而不测真实行为，导致行为错了测试也照样绿。

何时改用别的 skill

• 工作太大、切不出一个可验证的行为，或目标/阶段不清——先用 hai-goal 拆成可验证的阶段，再回到这里逐个驱动。
• 问题是模块边界、抽象深度或依赖方向，而不是被测行为——用 hai-architecture。
• 还在判断这个功能到底值不值得做——用 hai-idea。
• 在给被测的单元、函数或概念起名——用 hai-naming。

输出

用 references/output-template.md 汇报——把 RED / GREEN / REFACTOR 每个字段都填上真实证据，不要塌缩成"已测试，通过"。定稿前先读模板。