tdd-planning

TDD 规划

你正在制定遵循严格测试驱动开发方法的实施计划。每个实施步骤都遵循 TDD 循环：RED → GREEN → COMMIT/ROLLBACK。

TDD 核心原则

此技能要求遵循严谨的 TDD 工作流：

1. RED：先编写一个失败的测试（测试必须因正确的原因而失败）
2. GREEN：编写最少量的代码，使测试通过（不多做任何事）
3. COMMIT/ROLLBACK：如果测试通过，就提交；如果遇到阻碍，就回滚到上一个通过测试的状态。

没有先编写失败测试，就不能编写实现代码。 这条原则不容妥协。

工作约定

这些说明确立了你与用户之间的工作约定。核心原则如下：

1. AskUserQuestion 是你的主要沟通工具——每当你需要询问用户任何事项（澄清、设计决策、偏好、审批）时，都要使用 AskUserQuestion 工具。不要以纯文本形式提出问题——始终使用结构化工具，方便用户高效回应。

2. 提前了解偏好——在工作流开始时询问用户偏好，而不是等到最后才问，以免用户届时已经想要结束。

3. 自主模式决定互动频率——用户选择的自主程度决定了你需要多频繁地确认，但所有问题仍须通过 AskUserQuestion 提出。

用户偏好

开始规划前（自主模式为 Autopilot 时除外），了解以下偏好：

提交粒度——使用 AskUserQuestion 询问：

问题	选项
"提交应该细化到什么粒度？"	1. 每次 GREEN 后提交（严格 TDD 的推荐做法），2. 每个功能／阶段完成后提交，3. 我会手动处理提交

回滚策略——使用 AskUserQuestion 询问：

问题	选项
"经过合理尝试后，测试仍无法通过时，应采用什么回滚策略？"	1. 使用 git checkout . 回到上次提交（推荐），2. 使用 git stash 暂存更改，以便后续分析，3. 保留失败代码并请求指导

文件审查偏好——检查是否有 file-review 插件（在可用命令中查找 file-review:file-review）。

如果已安装 file-review 插件，则使用 AskUserQuestion 询问：

问题	选项
"计划准备好后，你是否希望使用 file-review 对计划提供行内反馈？"	1. 是，计划准备好后打开 file-review（推荐），2. 否，只展示计划

保存这些偏好，并在实施过程中遵照执行。

适用场景

在以下情况下，此技能会启用：

• 用户调用 TDD 规划命令
• 另一项技能引用 **REQUIRED SUB-SKILL:** Use desplega:tdd-planning
• 用户明确要求基于 TDD 制定计划
• 要实施的功能对测试或安全至关重要

自主模式

规划开始时，根据自主模式调整互动程度：

模式	行为
Autopilot	独立开展研究，制定完整的 TDD 计划，仅提交最终审核
Critical（默认）	在重要决策点征求认可，并验证测试策略
Verbose	每个步骤都进行确认，并在每个循环开始前确认测试方法

自主模式由调用命令传入。如果未指定，则默认为 Critical。

流程步骤

步骤 1：收集上下文并分析测试基础设施

1. 立即完整阅读所有提及的文件：

   • 研究文档、相关计划、JSON/数据文件
   • 重要：使用 Read 工具时，不要设置 limit/offset 参数
   • 关键：启动子任务前，先自行阅读文件

2. 分析测试基础设施：

   • 使用了什么测试框架？（Jest、pytest、Go testing 等）
   • 测试文件放在哪里？（与代码同目录、__tests__/、tests/ 等）
   • 测试命令是什么？（npm test、make test、pytest 等）
   • 是否有现成的测试模式可供参考？

3. 启动初步研究任务：

   • 使用 codebase-locator Agent 查找测试文件和测试工具
   • 使用 codebase-analyzer Agent 了解当前的测试模式
   • 使用 codebase-pattern-finder Agent 查找类似的测试实现
   • 使用 context7 MCP 了解测试库的相关信息

4. 陈述你的理解并提出问题（除非处于 Autopilot 模式）：

   首先，以文本形式陈述你的发现：

   Based on the research of the codebase, I understand we need to [summary].
   
   Test Infrastructure:
   - Framework: [testing framework]
   - Test location: [where tests live]
   - Test command: `[command]`
   - Existing patterns: [relevant patterns found]
   

   然后，如果有问题，请使用 AskUserQuestion。

步骤 2：设计测试策略

1. 确定可测试单元：

   • 最小的可测试单元是什么？
   • 可以验证哪些输入/输出？
   • 哪些边界情况值得关注？

2. 设计测试顺序：

   • 从最简单的情况（正常路径）开始
   • 逐步推进到边界情况
   • 最后处理错误

3. 陈述测试策略（除非处于 Autopilot 模式）：

   使用 AskUserQuestion 确认方案：

   问题	选项
   “我建议从 [最简单的测试用例] 开始，逐步推进到 [更复杂的用例]。这样的测试顺序是否合理？”	1. 是，继续，2. 我们讨论一下顺序，3. 添加更多测试用例

步骤 3：制定计划结构

1. 创建 TDD 循环大纲：

   每个功能/阶段都拆分为 TDD 循环：

   ## Feature: [Name]
   
   ### Cycle 1: [Simplest behavior]
   - RED: Test for [specific behavior]
   - GREEN: Implement [minimal code]
   - COMMIT: "[descriptive message]"
   
   ### Cycle 2: [Next behavior]
   ...
   

2. 在编写详细内容前，先征求对结构的反馈（除非处于 Autopilot 模式）

步骤 4：编写详细计划

继续之前，先退出计划模式，以便编写计划文件。

将计划写入 thoughts/<username|shared>/plans/YYYY-MM-DD-tdd-description.md。

路径选择： 如果从上下文中知道用户姓名，请使用用户姓名（例如 thoughts/taras/plans/）。如果不确定，则使用 thoughts/shared/plans/。

关键：每个 TDD 循环都必须包含要编写的精确测试代码和预期失败消息。具体格式请参阅模板。

QA 规范（可选）：更改面向用户行为的功能应在功能级别包含可选的 ### QA Spec (optional): 小节（位于功能标题之后、第一个 TDD 循环之前）。与常规计划按阶段附加 QA 规范不同，TDD 计划按功能附加，因为 RED/GREEN 循环本身已作为每个循环的验证。格式请参阅模板。

模板： 阅读并遵循 cc-plugin/base/skills/tdd-planning/template.md 中的模板。

第 5 步：审查与迭代

1. 展示草案计划的位置：

   I've created the TDD implementation plan at:
   `thoughts/<username|shared>/plans/YYYY-MM-DD-tdd-description.md`
   
   Please review it.
   

2. 根据反馈迭代（如果不是 Autopilot）

3. 提供结构化审查：

   • 迭代后，询问：“你希望我对这份 TDD 计划运行 /review，检查其完整性并分析遗漏吗？”
   • 如果是，则对计划文档调用 desplega:reviewing 技能

4. 学习记录：

   可选子技能： 如果此工作流中出现了重要的见解、模式、注意事项或决策，可以考虑使用 desplega:learning，通过 /learning capture 记录下来。重点记录有助于他人在未来会话中参考的经验。

5. 工作流交接： 计划定稿后（可选择进行审查），使用 AskUserQuestion 询问：

   问题	选项
   "TDD 计划已准备就绪。下一步是什么？"	1. 实施此计划（→ /implement-plan），2. 先进行审查（→ /review），3. 暂时到此为止（搁置计划）

   根据回答：

   • 实施：建议使用 /implement-plan 命令，并提供计划文件路径
   • 审查：对计划文档调用 desplega:reviewing 技能
   • 完成：根据情况将计划的 status 设为 ready 或 parked

6. 完成计划 - 不要开始实施

审查集成

如果 file-review 插件可用，且用户在“用户偏好设置”期间选择了“Yes”：

• 创建计划后，调用 /file-review:file-review <path>
• 如果用户选择了“No”，或自主模式为 Autopilot，则跳过此步骤

TDD 循环要求（强制）

每个实施步骤都必须遵循 TDD 循环。 未包含适当 TDD 循环的计划是不完整的。

每个循环的必需结构

### Cycle N: [Behavior being implemented]

#### RED Phase
**Test to write:**
```[language]
// Exact test code goes here

预期失败：

[Expected error message or failure output]

验证 RED： [test command] 应因上述消息而失败

GREEN 阶段

实施方法： [简要说明所需的最少代码]

要修改的文件：

• path/to/file.ext：[要添加/更改的内容]

验证 GREEN： [test command] 现在应通过

提交/回滚

如果 GREEN：

• 提交消息："[descriptive message following conventional commits]"
• 命令：git add -A && git commit -m "[message]"

如果卡住（经过合理努力仍无法达到 GREEN）：

• 回滚：git checkout .（或根据偏好使用 git stash）
• 重新评估：考虑测试是否过于庞大，或是否需要重新思考设计

### Validation Checklist

Before finalizing any TDD plan, verify:
- [ ] Every implementation step has RED → GREEN → COMMIT/ROLLBACK structure
- [ ] RED phase includes exact test code to write
- [ ] RED phase includes expected failure message
- [ ] GREEN phase describes minimal implementation
- [ ] Each cycle is small enough to complete in one sitting
- [ ] Cycles build on each other progressively
- [ ] Rollback strategy is clear for each cycle

## Important Guidelines

1. **Tests First, Always**: Never describe implementation without the test that drives it
2. **Minimal GREEN**: Only write enough code to pass the test, nothing more
3. **Small Cycles**: If a cycle seems big, break it into smaller cycles
4. **Progressive Complexity**: Start simple, add complexity through new tests
5. **Clear Rollback Points**: Every commit is a safe point to return to
6. **No Speculative Code**: Don't add code "because we'll need it later"