tdd-planning

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TDD Planning

TDD规划

You are creating implementation plans that follow a strict Test-Driven Development approach. Every implementation step follows the TDD cycle: RED → GREEN → COMMIT/ROLLBACK.

你需要创建遵循严格测试驱动开发（Test-Driven Development）方法的实施计划。每个实施步骤都遵循TDD循环：RED → GREEN → COMMIT/ROLLBACK。

Core TDD Principles

TDD核心原则

This skill enforces a disciplined TDD workflow:

RED: Write a failing test first (test must fail for the right reason)
GREEN: Write minimal code to make the test pass (nothing more)
COMMIT/ROLLBACK: If green, commit. If stuck, rollback to last green state.

No implementation code is written without a failing test first. This is non-negotiable.

本技能强制执行规范化的TDD工作流程：

RED：先编写失败的测试用例（测试必须因正确的原因失败）
GREEN：编写最少的代码使测试通过（仅此而已）
COMMIT/ROLLBACK：如果测试通过（GREEN），则提交代码；如果遇到瓶颈，则回退到上一个测试通过的状态。

**在编写失败的测试用例之前，绝对不能编写任何实现代码。**这是不可协商的要求。

Working Agreement

工作协议

These instructions establish a working agreement between you and the user. The key principles are:

AskUserQuestion is your primary communication tool - Whenever you need to ask the user anything (clarifications, design decisions, preferences, approvals), use the AskUserQuestion tool. Don't output questions as plain text - always use the structured tool so the user can respond efficiently.
Establish preferences upfront - Ask about user preferences at the start of the workflow, not at the end when they may want to move on.
Autonomy mode guides interaction level - The user's chosen autonomy level determines how often you check in, but AskUserQuestion remains the mechanism for all questions.

以下指令确立了你与用户之间的工作协议，核心原则如下：

AskUserQuestion是你主要的沟通工具 - 无论何时你需要向用户询问任何内容（澄清疑问、设计决策、偏好选择、审批请求等），都要使用AskUserQuestion工具。不要以纯文本形式输出问题 - 始终使用结构化工具，以便用户高效回复。
提前确认偏好 - 在工作流程开始时就询问用户的偏好，不要等到用户想要推进流程的最后阶段才询问。
自主模式指导交互程度 - 用户选择的自主模式决定了你需要多久进行一次确认，但所有问题都必须通过AskUserQuestion机制提出。

User Preferences

用户偏好

Before starting planning (unless autonomy is Autopilot), establish these preferences:

Commit Granularity - Use AskUserQuestion with:

Question	Options
"How granular should commits be?"	1. Commit after each GREEN (Recommended for strict TDD), 2. Commit after each feature/phase completes, 3. I'll handle commits manually

Rollback Strategy - Use AskUserQuestion with:

Question	Options
"When a test can't be made green after reasonable effort, what's the rollback strategy?"	1. `git checkout .` to last commit (Recommended), 2. `git stash` changes for later analysis, 3. Keep failing code, ask for guidance

File Review Preference - Check if the

file-review

plugin is available (look for

file-review:file-review

in available commands).

If file-review plugin is installed, use AskUserQuestion with:

Question	Options
"Would you like to use file-review for inline feedback on the plan when it's ready?"	1. Yes, open file-review when plan is ready (Recommended), 2. No, just show me the plan

Store these preferences and act on them during implementation.

开始规划前（除非自主模式为Autopilot），需确认以下偏好：

提交粒度 - 使用AskUserQuestion工具询问：

问题	选项
"提交的粒度应该如何设置？"	1. 每次GREEN后提交（严格TDD推荐选项），2. 完成每个功能/阶段后提交，3. 我将手动处理提交

回退策略 - 使用AskUserQuestion工具询问：

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

文件评审偏好 - 检查是否有

file-review

插件可用（在可用命令中查找

file-review:file-review

）。

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

问题	选项
"当计划完成后，是否要使用file-review进行内联反馈？"	1. 是，计划完成后打开file-review（推荐选项），2. 否，仅展示计划内容

保存这些偏好并在实施过程中遵循。

When to Use

使用场景

This skill activates when:

User invokes a TDD-planning command

Another skill references

**REQUIRED SUB-SKILL:** Use desplega:tdd-planning

User explicitly asks for TDD-based planning
The feature being implemented is test-critical or safety-critical

当出现以下情况时，激活本技能：

用户调用TDD规划命令

其他技能引用

**REQUIRED SUB-SKILL:** Use desplega:tdd-planning

用户明确要求基于TDD的规划
正在实施的功能是测试关键型或安全关键型

Autonomy Mode

自主模式

At the start of planning, adapt your interaction level based on the autonomy mode:

Mode	Behavior
Autopilot	Research independently, create complete TDD plan, present for final review only
Critical (Default)	Get buy-in at major decision points, validate test strategy
Verbose	Check in at each step, confirm test approach before each cycle

The autonomy mode is passed by the invoking command. If not specified, default to Critical.

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

模式	行为
Autopilot	独立调研，创建完整的TDD计划，仅在最终阶段提交审核
Critical（默认）	在主要决策节点获取用户认可，验证测试策略
Verbose	每一步都进行确认，在每个循环前验证测试方法

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

Process Steps

流程步骤

Step 1: Context Gathering & Test Infrastructure Analysis

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

Read all mentioned files immediately and FULLY:
- Research documents, related plans, JSON/data files
- IMPORTANT: Use Read tool WITHOUT limit/offset parameters
- CRITICAL: Read files yourself before spawning sub-tasks
Analyze test infrastructure:
- What testing framework is used? (Jest, pytest, Go testing, etc.)
- Where do tests live? (co-located,
```
__tests__/
```
  ,
```
tests/
```
  , etc.)
- What's the test command? (
```
npm test
```
  ,
```
make test
```
  ,
```
pytest
```
  , etc.)
- Are there existing test patterns to follow?
Spawn initial research tasks:
- Use codebase-locator agent to find test files and test utilities
- Use codebase-analyzer agent to understand current test patterns
- Use codebase-pattern-finder agent to find similar test implementations
- Use context7 MCP for testing library insights

Present understanding and questions (if not Autopilot):

First, present your findings as text:

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]

Then, if there are questions, use AskUserQuestion.

立即完整阅读所有提及的文件：
- 调研文档、相关计划、JSON/数据文件
- 重要提示：使用Read工具时不要添加limit/offset参数
- 关键要求：在生成子任务前自行阅读文件
分析测试基础设施：
- 使用的测试框架是什么？（Jest、pytest、Go testing等）
- 测试文件存放位置？（与代码同目录、
```
__tests__/
```
  、
```
tests/
```
  等）
- 测试命令是什么？（
```
npm test
```
  、
```
make test
```
  、
```
pytest
```
  等）
- 是否有需要遵循的现有测试模式？
生成初始调研任务：
- 使用codebase-locator代理查找测试文件和测试工具
- 使用codebase-analyzer代理理解当前测试模式
- 使用codebase-pattern-finder代理查找类似的测试实现
- 使用context7 MCP获取测试库相关见解

（如果不是Autopilot模式）展示理解结果并提出问题：

首先，以文本形式展示你的调研结果：

基于对代码库的调研，我理解我们需要[总结内容]。

测试基础设施：
- 框架：[测试框架名称]
- 测试文件位置：[测试文件存放路径]
- 测试命令：`[命令内容]`
- 现有模式：[发现的相关模式]

然后，如果有问题，使用AskUserQuestion工具提出。

Step 2: Test Strategy Design

步骤2：测试策略设计

Identify testable units:
- What are the smallest testable pieces?
- What inputs/outputs can be verified?
- What edge cases matter?
Design test progression:
- Start with simplest case (happy path)
- Progress to edge cases
- End with error handling

Present test strategy (if not Autopilot):

Use AskUserQuestion to validate approach:

Question	Options
"I propose starting with [simplest test case] and progressing to [more complex cases]. Does this test progression make sense?"	1. Yes, proceed, 2. Let's discuss the order, 3. Add more test cases

识别可测试单元：
- 最小的可测试模块是什么？
- 哪些输入/输出可以被验证？
- 哪些边缘情况需要关注？
设计测试推进顺序：
- 从最简单的场景（正常流程）开始
- 逐步推进到边缘情况
- 最后处理错误逻辑
（如果不是Autopilot模式）展示测试策略：

使用AskUserQuestion工具验证方案：

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

Step 3: Plan Structure Development

步骤3：计划结构制定

Create TDD cycle outline:

Each feature/phase is broken into TDD cycles:

## Feature: [Name]

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

### Cycle 2: [Next behavior]
...

Get feedback on structure before writing details (unless Autopilot)

创建TDD循环大纲：

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

## 功能：[名称]

### 循环1：[最简单的行为]
- RED：针对[具体行为]编写测试
- GREEN：实现[最少代码]
- COMMIT："[描述性提交信息]"

### 循环2：[下一个行为]
...

（除非是Autopilot模式）在编写详细内容前获取结构反馈

Step 4: Detailed Plan Writing

步骤4：详细计划编写

Before proceeding, exit plan mode to write the plan file.

Write the plan to

thoughts/<username|shared>/plans/YYYY-MM-DD-tdd-description.md

Path selection: Use the user's name (e.g.,

thoughts/taras/plans/

) if known from context. Fall back to

thoughts/shared/plans/

when unclear.

CRITICAL: Every TDD cycle MUST include exact test code to write and expected failure message. See template for exact format.

QA Specs (optional): Features that change user-facing behavior SHOULD include an optional

### QA Spec (optional):

section at the Feature level (after the feature header, before the first TDD cycle). Unlike regular plans where QA specs attach per-phase, TDD plans attach them per-feature since the RED/GREEN cycle itself serves as the per-cycle verification. See the template for the format.

Template: Read and follow the template at

cc-plugin/base/skills/tdd-planning/template.md

在开始前，退出计划模式以编写计划文件。

将计划写入

thoughts/<username|shared>/plans/YYYY-MM-DD-tdd-description.md

。

路径选择：如果从上下文中得知用户名，则使用用户名称路径（例如

thoughts/taras/plans/

）。如果不明确，则回退到

thoughts/shared/plans/

。

关键要求：每个TDD循环必须包含要编写的精确测试代码和预期失败信息。请参考模板中的精确格式。

QA规格（可选）：改变用户交互行为的功能应在功能级别（功能标题之后、第一个TDD循环之前）添加可选的

### QA Spec (optional):

部分。与常规计划中QA规格附加到每个阶段不同，TDD计划将其附加到每个功能，因为RED/GREEN循环本身就作为每个循环的验证机制。请参考模板中的格式。

模板：阅读并遵循

cc-plugin/base/skills/tdd-planning/template.md

中的模板

Step 5: Review and Iterate

步骤5：评审与迭代

Present draft plan location:

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

Please review it.

Iterate based on feedback (if not Autopilot)
Offer structured review:
- After iteration, offer: "Would you like me to run
```
/review
```
  on this TDD plan for completeness and gap analysis?"
- If yes, invoke the
```
desplega:reviewing
```
  skill on the plan document
Learning Capture:
OPTIONAL SUB-SKILL: If significant insights, patterns, gotchas, or decisions emerged during this workflow, consider using
```
desplega:learning
```
to capture them via
```
/learning capture
```
. Focus on learnings that would help someone else in a future session.
Workflow handoff: After the plan is finalized (and optionally reviewed), use AskUserQuestion with:
Question Options
"The TDD plan is ready. What's the next step?" 1. Implement this plan (→
/implement-plan
), 2. Run a review first (→
/review
), 3. Done for now (park the plan)
Based on the answer:
- Implement: Suggest the
```
/implement-plan
```
  command with the plan file path
- Review: Invoke the
```
desplega:reviewing
```
  skill on the plan document
- Done: Set the plan's
```
status
```
  to
```
ready
```
  or
```
parked
```
  as appropriate
Finalize the plan - DO NOT START implementation

Question	Options
"The TDD plan is ready. What's the next step?"	1. Implement this plan (→ `/implement-plan` ), 2. Run a review first (→ `/review` ), 3. Done for now (park the plan)

展示草稿计划位置：

我已创建TDD实施计划，路径为：
`thoughts/<username|shared>/plans/YYYY-MM-DD-tdd-description.md`

请进行评审。

（如果不是Autopilot模式）根据反馈进行迭代
提供结构化评审选项：
- 迭代完成后，询问："是否需要我对这份TDD计划运行
```
/review
```
  命令以检查完整性和分析漏洞？"
- 如果用户同意，对计划文档调用
```
desplega:reviewing
```
  技能
经验总结：
可选子技能：如果在工作流程中获得了重要见解、模式、注意事项或决策，可以考虑使用
```
desplega:learning
```
通过
```
/learning capture
```
命令记录这些内容。重点记录能帮助未来会话中其他人员的经验。
工作流交接： 计划定稿后（可选完成评审），使用AskUserQuestion工具询问：
| 问题 | 选项 | |----------|---------| | "TDD计划已准备就绪。下一步是什么？" | 1. 实施此计划（→
```
/implement-plan
```
），2. 先进行评审（→
```
/review
```
），3. 暂时结束（搁置计划） |
根据用户回复：
- 实施：建议使用
```
/implement-plan
```
  命令并传入计划文件路径
- 评审：对计划文档调用
```
desplega:reviewing
```
  技能
- 结束：将计划的
```
status
```
  设置为
```
ready
```
  或
```
parked
```
  （根据情况）
最终确定计划 - 不要开始实施

Review Integration

评审集成

If the

file-review

plugin is available and the user selected "Yes" during User Preferences setup:

After creating plans, invoke
```
/file-review:file-review <path>
```
If user selected "No" or autonomy mode is Autopilot, skip this step

如果

file-review

插件可用且用户在用户偏好设置中选择了"是"：

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

TDD Cycle Requirements (MANDATORY)

TDD循环要求（强制性）

Every implementation step MUST follow the TDD cycle. Plans without proper TDD cycles are incomplete.

每个实施步骤必须遵循TDD循环。 没有正确TDD循环的计划是不完整的。

Required Structure for Each Cycle

每个循环的必填结构

markdown

undefined

markdown

undefined

Cycle N: [Behavior being implemented]

循环N：[正在实现的行为]

RED Phase

RED阶段

Test to write:

// Exact test code goes here

Expected failure:

[Expected error message or failure output]

Verify RED:

[test command]

should fail with the above message

要编写的测试：

// 此处写入精确的测试代码

预期失败结果：

[预期错误信息或失败输出]

验证RED状态：

[测试命令]

应返回上述失败信息

GREEN Phase

GREEN阶段

Implementation approach: [Brief description of minimal code needed]

Files to modify:

```
path/to/file.ext
```
: [what to add/change]

Verify GREEN:

[test command]

should now pass

实现方案： [简要描述所需的最少代码]

需要修改的文件：

```
path/to/file.ext
```
：[添加/修改的内容]

验证GREEN状态：

[测试命令]

现在应执行通过

COMMIT/ROLLBACK

If GREEN:

Commit message:

"[descriptive message following conventional commits]"

Command:
```
git add -A && git commit -m "[message]"
```

If STUCK (can't reach GREEN after reasonable effort):

Rollback:
```
git checkout .
```
(or
```
git stash
```
based on preference)
Reassess: Consider if the test is too big, or if design needs rethinking

undefined

如果测试通过（GREEN）：

提交信息：
```
"[符合规范的描述性信息]"
```

命令：

git add -A && git commit -m "[信息内容]"

如果遇到瓶颈（经过合理尝试仍无法达到GREEN状态）：

回退：
```
git checkout .
```
（或根据偏好使用
```
git stash
```
）
重新评估：考虑测试是否过于复杂，或者是否需要重新设计方案

undefined

Validation Checklist

验证检查清单

Important Guidelines

重要指导原则

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

始终先写测试：绝不要在没有驱动它的测试的情况下描述实现代码
最少化GREEN代码：只编写足够使测试通过的代码，不要多写
小循环：如果一个循环看起来太大，将其拆分为更小的循环
渐进式复杂度：从简单开始，通过新测试逐步增加复杂度
清晰的回退点：每次提交都是可以安全回退的节点
无投机性代码：不要添加"以后可能需要"的代码