recursive-tdd

recursive-tdd

概述

所有递归模式的实现工作都必须采用测试驱动开发。此技能确保严格遵循先编写测试的原则，并以递归模式工具可验证的方式记录过程。

核心原则： 如果你没有亲眼看到测试失败，就不知道它是否测试了正确的内容。

递归模式的铁律：

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

触发示例

• Implement Phase 3 for run '<run-id>'
• Add a failing regression test first, then fix the bug
• I already wrote the code; now add tests（应触发 TDD 重置指导）
• Follow RED-GREEN-REFACTOR for this change

何时使用

始终在 Phase 3（实现阶段）使用：

• 新功能
• Bug 修复
• 重构
• 行为变更

默认规则：

• 不是只针对“简单”变更
• 不是在“时间紧迫”时例外
• 不能因为“事后补测试也能达到同样的目标”

仅允许明确声明例外：

• 如果严格遵循先 RED 的流程确实不可行，请在 Phase 3 产物中声明 TDD Mode: pragmatic
• 记录具体的例外原因
• 在 /.recursive/run/<run-id>/evidence/ 下记录补充验证证据
• 将此视为明确偏离，而非悄悄走捷径

RED-GREEN-REFACTOR 循环

digraph tdd_cycle {
    rankdir=LR;
    red [label="RED\nWrite failing test", shape=box, style=filled, fillcolor="#ffcccc"];
    verify_red [label="Verify fails\ncorrectly", shape=diamond];
    green [label="GREEN\nMinimal code", shape=box, style=filled, fillcolor="#ccffcc"];
    verify_green [label="Verify passes\nAll green", shape=diamond];
    refactor [label="REFACTOR\nClean up", shape=box, style=filled, fillcolor="#ccccff"];
    record [label="Record in\nPhase 3 artifact", shape=box];

    red -> verify_red;
    verify_red -> green [label="yes"];
    verify_red -> red [label="wrong\nfailure"];
    green -> verify_green;
    verify_green -> refactor [label="yes"];
    verify_green -> green [label="no"];
    refactor -> verify_green [label="stay\ngreen"];
    verify_green -> record;
}

RED - 编写失败的测试

编写一个最小测试，说明应该发生什么。

要求：

• 每个测试只验证一种行为
• 名称清晰且具有描述性
• 测试真实代码（除非无法避免，否则不要使用模拟对象）
• 断言清晰地表明预期结果

```typescript test('rejects empty email with clear error message', async () => { const result = await submitForm({ email: '' }); expect(result.error).toBe('Email is required'); }); ``` ```typescript test('email validation works', async () => { const mock = jest.fn().mockResolvedValue({ valid: true }); const result = await validateEmail(mock); expect(mock).toHaveBeenCalled(); }); ```

验证 RED - 观察测试失败

强制要求。绝不可跳过。

npm test path/to/test.test.ts

确认：

• 测试失败（而非出错）
• 失败消息符合预期
• 失败是因为缺少功能（而非拼写错误）

在 Phase 3 产物中记录：

### TDD Cycle for R3 (Email Validation)

TDD Mode: strict

RED Evidence:
- `/.recursive/run/<run-id>/evidence/logs/red/<file>.log`

GREEN Evidence:
- `/.recursive/run/<run-id>/evidence/logs/green/<file>.log`

**RED Phase:**
- Test: `rejects empty email with clear error message`
- Command: `npm test src/forms/email.test.ts`
- Expected failure: "Email is required" not found
- Actual failure: [paste output]
- RED verified: PASS

GREEN - 编写最少代码

编写能通过测试的最简单代码。

规则：

• 只编写足以通过测试的代码
• 不添加额外功能
• 不做“顺便改进”
• 暂不重构

```typescript function submitForm(data: FormData) { if (!data.email?.trim()) { return { error: 'Email is required' }; } // ... rest of form handling } ``` ```typescript function submitForm( data: FormData, options?: { strictMode?: boolean; customValidators?: Validator[]; onValidationError?: (err: Error) => void; } ) { // YAGNI - over-engineered } ```

在 Phase 3 产物中记录：

**GREEN Phase:**
- Implementation: Added null check for email field
- Command: `npm test src/forms/email.test.ts`
- Result: PASS
- GREEN verified: PASS

REFACTOR - 清理代码

只有在测试通过后才能：

• 消除重复
• 改进命名
• 提取辅助函数
• 保持测试通过

重构期间绝不添加行为。

在 Phase 3 产物中记录：

**REFACTOR Phase:**
- Extracted `validateRequired(field, name)` helper
- Renamed `submitForm` to `processFormSubmission` for clarity
- All tests still passing: PASS

常见流程捷径（停止）

借口	事实
“这只是个简单修复，不需要测试”	简单的代码也会出错。测试只需 30 秒。
“我确认修复有效后再测试”	测试一开始就通过，证明不了任何事。你从未看到它捕获 Bug。
“事后补测试也能达到同样的目标”	先写测试 =“这段代码做什么？”先写测试 =“这段代码应该做什么？”
“我已经手动测试过了”	临时测试 ≠ 系统化测试。没有记录，无法重新运行，也无法防止回归。
“删除能运行的代码很浪费”	这是沉没成本谬误。保留未经验证的代码就是技术债务。
“TDD 是教条，我只是在务实处理”	TDD 本身就很务实。它能在提交前发现 Bug，并支持重构。
“我会留着这段代码作为参考”	你会据此修改代码。这就是事后测试。删除就是删除。
“测试很难 = 设计不清晰”	倾听测试的反馈。难以测试 = 难以使用。简化设计。
“我需要先探索一下”	可以。丢弃探索代码，重新开始 TDD。
“这次情况不同，因为……”	并非如此。规则没有例外。

警示信号 - 停下并重新开始

如果遇到以下任一情况，请删除代码并从 TDD 重新开始：

• 先写了代码，后写测试
• 测试立即通过（说明测试的并非你以为的内容）
• “我之后再补测试”
• “这太简单，不值得测试”
• “我知道自己在做什么，不需要这些仪式”
• 无法解释测试为何失败（或为何没有失败）
• 测试的是模拟行为，而非真实行为
• 一个测试包含多种行为（测试名称中有“和”）

与 recursive-mode Phase 3 的集成

路由感知

如果 TDD 执行涉及委派审查、测试审计或有界路由实现协助，请在选择委派 CLI/模型之前立即重新读取：

• /.recursive/config/recursive-router.json
• /.recursive/config/recursive-router-discovered.json

并使用路由策略或明确的回退方案，而不是临时选择模型。

第 3 阶段制品 TDD 部分

每个第 3 阶段制品都必须包含：

## TODO

- [ ] Replace every placeholder with concrete TDD evidence for the current implementation phase.

## Audit Context

Audit Execution Mode: self-audit / subagent
Subagent Availability: available / unavailable
Subagent Capability Probe: [what proved availability or unavailability]
Delegation Decision Basis: [why self-audit or delegation was chosen]

## TDD Compliance Log

TDD Mode: strict

RED Evidence:
- `/.recursive/run/<run-id>/evidence/logs/red/<file>.log`

GREEN Evidence:
- `/.recursive/run/<run-id>/evidence/logs/green/<file>.log`

### Requirement R1 (Feature X)

**Test:** `test/features/x.test.ts` - "should do Y when Z"
- RED: [timestamp] - Failed as expected: [output]
- GREEN: [timestamp] - Minimal implementation: [description]
- REFACTOR: [timestamp] - Cleanups: [description]
- Final state: PASS - all tests passing

### Requirement R2 (Bug Fix)

**Regression Test:** `test/bugs/issue-123.test.ts` - "reproduces crash on empty input"
- RED: [timestamp] - Confirmed bug: [output]
- GREEN: [timestamp] - Fix applied: [description]
- REFACTOR: [timestamp] - N/A (minimal fix)
- Final state: PASS - test passes, bug fixed

## Requirement Completion Status

- `R1` | `implemented` | Changed Files: `path/to/file`
- `R1` | `verified` | Evidence: `/.recursive/run/<run-id>/evidence/logs/green/<file>.log`

如果无法遵循严格模式，制品必须包含：

## Pragmatic TDD Exception

Exception reason: [specific reason strict RED-first flow was not feasible]
Compensating validation:
- [extra tests, targeted manual verification, diff review, etc.]
- `/.recursive/run/<run-id>/evidence/<supporting-file>`

第 3 阶段覆盖率门禁补充

## Coverage Gate

- [ ] Every new function has a corresponding test
- [ ] Every bug fix has a regression test that fails before fix
- [ ] All RED phases documented with failure output
- [ ] All GREEN phases documented with minimal implementation
- [ ] All tests passing (no skipped tests)
- [ ] No production code written before failing test

TDD Compliance: PASS / FAIL

第 3 阶段审批门禁补充

## Approval Gate

- [ ] TDD Compliance: PASS
- [ ] Implementation matches Phase 3 plan
- [ ] No code without preceding failing test
- [ ] All tests documented in TDD Compliance Log

Approval: PASS / FAIL

Bug 修复 TDD 流程

1. 先添加回归测试

   • 编写可复现 bug 的测试
   • 运行测试，确认其因预期错误而失败
   • 在第 3 阶段制品中记录失败情况

2. 实施最小修复

   • 仅修复使测试通过所需的部分
   • 运行测试，确认其通过
   • 在第 3 阶段制品中记录修复情况

3. 确认没有回归

   • 运行完整测试套件
   • 确认其他内容均未损坏
   • 在第 3 阶段制品中记录确认结果

4. 锁定第 3 阶段

   • 已声明 TDD 模式
   • TDD 合规性：PASS
   • 审批：PASS
   • 状态：LOCKED

示例：完整的第 3 阶段 TDD 部分

## TDD Compliance Log

### R1: Add email validation

**Test:** `test/forms/validation.test.ts`

RED Phase (2026-02-21T10:15:00Z):
```bash
$ npm test test/forms/validation.test.ts
FAIL: Expected 'Email is required', got undefined

RED 已验证：PASS

GREEN 阶段（2026-02-21T10:18:00Z）：

• 在 submitForm() 函数中添加空值检查
• 测试通过 GREEN 已验证：PASS

REFACTOR 阶段（2026-02-21T10:22:00Z）：

• 提取 validateRequired() 辅助函数
• 所有测试仍然通过 REFACTOR 完成：PASS

R2：修复空数组导致的崩溃

回归测试： test/utils/array.test.ts

RED 阶段（2026-02-21T10:25:00Z）：

$ npm test test/utils/array.test.ts
FAIL: TypeError: Cannot read property 'map' of undefined

RED 已验证：已复现 Bug PASS

GREEN 阶段（2026-02-21T10:27:00Z）：

• 在 processItems() 中添加保护子句
• 测试通过 GREEN 已验证：PASS

REFACTOR：不适用（最小的 2 行修复）

验证

完整测试套件运行：npm test 结果：47 项通过，0 项失败

## References

- **REQUIRED:** Follow this skill for all Phase 3 implementation work