tdd

TDD

价值： 反馈——通过短周期和可验证的证据，确保 AI 生成的代码可信，并让人类掌握主动权。测试表达意图；证据确认进展。

目的

教授一个适用于任何运行框架的五步 TDD 周期（RED、DOMAIN、GREEN、DOMAIN、COMMIT）。检测可用的委派原语，并切换到引导模式（由人类驱动每个阶段）或自动化模式（由系统编排各阶段）。无论处于哪种模式，都能防止原语痴迷、跳过评审和未经测试的复杂性。

实践

五步周期

每项功能都通过重复以下流程构建：RED -> DOMAIN -> GREEN -> DOMAIN -> COMMIT。

1. RED —— 编写一个失败的测试，并且只包含一个断言。只能编辑测试文件。写出你希望拥有的代码——引用尚不存在的类型和函数。运行测试。粘贴失败输出。停止。 完成条件：测试可以运行并且失败（编译错误或断言失败）。

2. DOMAIN（RED 之后） —— 检查测试是否存在原语痴迷和无效状态风险。创建带有存根函数体的类型定义（todo!()、raise NotImplementedError 等）。不要实现逻辑。停止。 完成条件：测试可以编译，但仍然失败（断言失败或 panic，而不是编译错误）。

3. GREEN —— 解决当前错误——绝不要一次性“让测试通过”。每次修改前检查范围：能否通过函数范围内的工作（约 20 行、一个文件）解决？能 → 修改，运行测试，检查下一个错误。不能 → 通过为所需的最小部分编写一个失败的单元测试来逐步拆解，然后交换角色，按标准 TDD 周期处理。只能编辑生产文件（逐步拆解时除外）。每次修改后都粘贴输出。 完成条件：以最小实现让测试通过。

4. DOMAIN（GREEN 之后） —— 检查实现是否违反领域原则：贫血模型、验证逻辑泄漏，以及遗漏的原语痴迷。如果发现违规，提出疑虑并建议修订。 完成条件：类型设计合理，且测试仍然通过。

5. COMMIT —— 运行完整测试套件。暂存所有更改，并创建一个引用 GWT 场景的 git 提交。提交后运行 git status，确认没有未提交的文件。这是一个硬性门槛：只有创建了此提交且工作树干净后，才能开始新的 RED 阶段。 完成条件：已创建 git 提交、所有测试通过、工作树干净。

第 5 步之后，可以开始下一个 RED 阶段，或整理代码（仅限结构性更改，并单独提交）。

编译失败就是测试失败。不要为了避免编译错误而预先创建类型。类型应从测试中产生，绝不能先于测试。

领域评审有权否决原语痴迷和可表示为有效状态的违规情况。讨论将持续进行，直到问题解决或升级给人类——没有轮数限制。

面向用户的模式

引导模式（/tdd red、/tdd domain、/tdd green、/tdd commit）： 每个阶段都会加载 references/{phase}.md，其中包含该步骤的详细说明。适合希望明确控制各阶段的资深工程师。适用于任何运行框架——无需委派原语。由人类决定何时进入下一阶段。

自动化模式（/tdd 或 /tdd auto）： 系统会检测运行框架的能力，选择执行策略，并编排完整周期。用户看到的是可运行的代码，而不是制作过程。若要查看阶段转换和证据的详细输出，请使用 /tdd auto --verbose。

能力检测（自动模式）

自动模式启动时，按以下顺序检测可用的原语：

1. 是否提供子 Agent？ 检查是否有 Agent 工具。如果有，使用 子 Agent 策略，为各阶段分配专注的 Agent。
2. 回退方案。 使用 串联 策略，在单个上下文中于各阶段之间进行内部角色切换。

选择能力最强的可用策略。缺少相应原语时，不要尝试使用更高级的策略。

你是协调者。 读取此文件的 Agent 会检测能力并直接分派任务。不要生成一个单独的“协调者”子 Agent 来代劳——那会掩盖工作、绕过策略检测，并预先选错策略。无论你是通过 /tdd、流水线还是其他调用方启动的，都要自行检测能力、选择策略并生成各阶段的 Agent。

确定策略后，只读取该策略的入口文件：

策略	入口文件
子 Agent	references/orchestrator.md
串联	（无入口文件——请遵循下方的串联部分）

使用串联策略时，不要读取 orchestrator.md。

orchestrator.md 会引用 references/shared-rules.md，其中包含适用于所有策略的规则（领域否决、由外向内推进、流水线集成、实施前上下文检查清单）。策略入口文件指示你读取 shared-rules.md 时，再进行读取。

执行策略：串联（回退方案）

当没有可用的委派原语时使用。Agent 依次扮演每个角色：

1. 加载 references/red.md。执行 RED 阶段。
2. 加载 references/domain.md。对测试执行 DOMAIN 审查。
3. 加载 references/green.md。执行 GREEN 阶段。
4. 加载 references/domain.md。对实现执行 DOMAIN 审查。
5. 加载 references/commit.md。执行 COMMIT 阶段。
6. 重复以上步骤。

此模式下的角色边界仅供参考。Agent 必须自行遵守阶段边界：只能编辑当前阶段允许的文件类型（见 references/phase-boundaries.md）。

执行策略：子 Agent

当 Agent 工具可用于生成专注的子 Agent 时使用。每个阶段都在受限范围的独立子 Agent 中运行。

• 使用提示词模板 references/{phase}-prompt.md，通过 Agent(subagent_type="<agent-name>", prompt="...") 生成每个阶段的 Agent。
• 协调者遵循 references/orchestrator.md 中的协调规则。
• 结构化交接规范（references/handoff-schema.md）：每个阶段的 Agent 都必须返回证据字段（测试输出、变更的文件路径、领域疑虑）。缺少证据字段即阻止交接。协调者必须等到满足规范后，才能进入下一阶段。
• 上下文隔离可通过结构化方式强制执行：每个子 Agent 只会收到与其阶段相关的文件。

命名团队成员角色设定（子 Agent 策略）

当 .claude/agents/ 中存在定义（来自 ensemble-team 技能）时，子 Agent 策略会为 ping 和 pong 角色使用命名角色设定。协调者会根据任务片段的上下文选择团队成员，通过 Agent(subagent_type="<agent-name>", prompt="...") 将其作为子 Agent 生成，并收集结果，作为上下文传递给下一个子 Agent。

有关协调规则，请参阅 references/orchestrator.md；有关角色选择、轮换和配对历史记录，请参阅 references/ping-pong-pairing.md。

阶段边界规则

每个阶段只能编辑自己的文件类型。这可以防止偏移。完整的文件类型矩阵请参阅 references/phase-boundaries.md。

阶段	可以编辑	不能编辑
RED	测试文件	生产代码、类型定义
DOMAIN	类型定义（存根）	测试逻辑、实现代码体
GREEN	实现代码体	测试文件、类型签名
COMMIT	无——仅限 git 操作	所有源文件

如果遇到边界限制，请停止并返回协调器（自动模式），或向用户报告（引导模式）。切勿绕过边界。

优先构建行走骨架

第一个垂直切片必须是一个行走骨架：最精简的端到端路径，用于证明所有架构层均已连通。它可以使用硬编码值或存根。应在其他任何切片之前构建它。这样可以降低架构风险，并为后续切片提供已验证的连线路径以供扩展。

自外而内的 TDD

从应用边界处的验收测试开始——也就是外部输入进入系统的位置。通过单元测试逐步向内推进。外层验收测试保持 RED，而内层单元测试则经历各自的红-绿-领域-提交循环。只有外层验收测试通过后，切片才算完成。

直接调用内部函数的测试属于单元测试，而不是验收测试——即使它断言的是用户可见行为。

按模式执行边界要求：

• Pipeline 模式： CYCLE_COMPLETE 证据必须包含验收测试上的 boundary_type 和 boundary_evidence。Pipeline 的 TDD 门禁会拒绝验收测试直接调用内部函数的证据。
• 自动化模式（非 Pipeline）： 协调器会检查边界范围；如果首个测试不是边界测试，则会重新委派任务。此项仅作提醒——没有门禁阻止流程继续。
• 引导模式： 人类负责确保测试位于边界层级。技能文本会指导正确做法，但无法强制执行。

周期完成证据

每个完整的 RED-DOMAIN-GREEN-DOMAIN-COMMIT 周期结束时，都要生成一个 CYCLE_COMPLETE 证据包，其中包含：slice_id、acceptance_test {file, name, output, boundary_type, boundary_evidence}、unit_tests {count, all_passing, output}、domain_reviews [{phase, verdict, concerns}]、 commits [{hash, message}]、rework_cycles、team {ping, pong, domain_reviewer}。

当上下文元数据中提供 pipeline-state 时，TDD 技能将以 Pipeline 模式运行：接收一个 slice_id，并将证据存储到 .factory/audit-trail/slices/<slice-id>/tdd-cycles/cycle-NNN.json。 独立运行时，证据仅供参考（不会存储）。

完整架构请参阅 references/cycle-evidence.md。

特定 Harness 的指导

如果在 Claude Code 上运行，也请阅读 references/claude-code.md，了解 Harness 特定规则，包括基于钩子的强制执行方式。如需最大程度的机械化强制执行，请让引导技能从 references/hooks/claude-code-hooks.json 安装可选钩子。

强制执行说明

• 引导模式：仅作提醒。由人类通过控制阶段转换来强制执行。
• 链式模式：仅作提醒。由 Agent 自行强制执行阶段边界。
• Subagent 模式：结构化强制执行。上下文隔离和交接架构会强制执行阶段边界。缺少证据会阻止交接。
• Pipeline 模式：门禁强制执行。证据门禁会拒绝不完整的阶段转换。
• 可选钩子（Claude Code）：机械化强制执行。工具调用前钩子会按阶段阻止未经授权的文件编辑。请参阅 references/claude-code.md。

硬性约束：

• 阶段边界违规（在错误阶段编辑了错误的文件类型）：[H]
• 领域否决升级（有争议的设计决策）：[RP]
• 提交门禁（上一周期提交前不得开始新的 RED）：[H]

如需了解 Pipeline 模式下的返工预算冲突和领域否决处理，请参阅模板目录中的 references/constraint-resolution.md。

约束

• 串联模式自我约束：自我约束意味着你产出的文件类型限制，应与由不同 Agent 分别执行约束时相同。即使没有机制阻止，在 RED 阶段编写生产代码也违反此约束。如果你发现自己在思考为何串联模式不受阶段边界约束，那你就违反了此约束。
• “约 20 行、一个文件”范围检查：这是判断启发式，而非精确阈值。其要点是：如果改动涉及多个关注点、多个文件，或需要理解相距较远的代码，那么对于单个周期来说范围就太大了。不要在一个文件中跨两个函数进行 40 行改动，却声称这只是“一个文件”，以此钻空子。

验证

完成一个周期后，请验证：

• 每个失败的测试都在实现之前编写
• 每个 RED 和 GREEN 阶段之后都进行了领域审查
• 遵守了阶段边界规则（文件类型限制）
• 每次交接时都提供了证据（测试输出）
• 每个完成的 RED-GREEN 周期都有对应的提交
• GREEN 阶段逐个处理失败，而不是一次性完成全部实现
• 每次 COMMIT 后工作区都干净（已验证 git status）
• 已首先完成 Walking Skeleton（第一个垂直切片）

硬性门槛——提交（开始任何新的 RED 阶段之前必须通过）：

• 所有测试均通过
• 已创建 Git 提交，提交消息中引用了当前 GWT 场景
• 此提交完成之前没有开始新的 RED 阶段

依赖项

此技能可独立使用。若要增强工作流，可与以下内容集成：

• **domain-modeling：**通过“解析而非验证”、语义类型和防止无效状态的原则，强化领域审查阶段。
• **code-review：**在 TDD 周期完成后进行三阶段审查（规范符合性、代码质量、领域完整性）。
• **mutation-testing：**通过检查测试能否检测到注入生产代码的变异，验证测试质量。
• **ensemble-team：**为结对选择和群体审查提供真实世界的专家角色。

缺少依赖项？请使用以下命令安装：

npx skills add jwilger/agent-skills --skill domain-modeling