task-driven-tdd-workflow

name	task-driven-tdd-workflow
description	将需求文档、org 文档或功能请求转化为任务包，包含原则、上下文、任务文件、Agent Brief、验收标准和提交规范。当用户提供需求文档或 org 文件，并希望获得结构化的实施计划、TDD 任务拆分、验收点或可执行的任务文件时使用此技能。

任务驱动的 TDD 工作流

快速开始

当用户提供具体的需求文档、org 文档或功能请求时：

1. 阅读原始材料，确定实施范围
2. 创建 tasks/<topic>/
3. 先创建共享文档：
   • README.md
   • PRINCIPLES.md
   • 00-context-and-scope.md
4. 将工作拆分为编号的任务文件：
   • 01-...md
   • 02-...md
   • 03-...md
5. 确保每个任务文件包含：
   • 任务目标
   • 边界范围
   • 验收标准
   • Agent Brief
6. 使任务包可通过最小提示词执行，例如：

请执行任务：`tasks/<topic>/0X-xxx.md`

产出内容

创建一个任务包，让后续实施只需最少的提示词工程即可推进。

共享文件

README.md

• 面向人类读者
• 说明这组任务在做什么
• 给出当前阶段范围、文档导航、推荐阅读顺序和使用方式
• 不要塞过多只对 AI 执行有意义的技术推理

PRINCIPLES.md

• 所有任务共享的硬约束
• TDD 要求
• 长期有效的架构边界
• 反模式
• 提交要求
• 完成汇报要求
• 不要混入只对当前阶段成立的技术判断

00-context-and-scope.md

• 面向 AI/Agent
• 提供执行具体任务前必须掌握的阶段技术上下文
• 包含需求来源、MVP 范围、明确排除的范围
• 包含“为什么这一阶段这样做”的技术推理
• 包含当前阶段的技术执行判断、推荐实现切分、当前不要提前做的事
• 如果某些技术推理会直接影响任务拆分、测试范围和实现路径，就应该放在这里而不是 README.md

任务文件模式

每个任务文件应包含：

Agent Brief

• 首先阅读什么
• 本任务可以做什么
• 本任务不能做什么
• 完成后汇报什么

任务主体

• 任务目标
• 必需行为
• 建议的文件或模块
• 建议的测试
• 验收标准
• 完成标准

工作流程

第一阶段：理解需求

• 提取用户可见的行为
• 区分 MVP 和延后的范围
• 识别必须成为共享原则的架构约束
• 识别哪些内容是“给人看的背景”，哪些内容是“给 AI 执行时必须知道的技术上下文”

第二阶段：创建任务包

• 先创建共享文档
• 再创建编号的任务文件
• 确保任务顺序支持 TDD 推进：
  • 领域规则
  • 纯逻辑
  • 解析器/建模
  • 命令层
  • 集成测试
  • 注册/发布 wiring

第三阶段：强化任务执行

• 为每个任务添加验收标准
• 为每个任务添加 Agent Brief
• 确保用户一句话就能触发任务
• 确保 Agent Brief 的前置阅读顺序合理：
  • 一般先读 PRINCIPLES.md
  • 再读 00-context-and-scope.md
  • 最后读当前任务文件

第四阶段：提交纪律

• 在 PRINCIPLES.md 中记录提交期望
• 按任务边界优先原子提交
• 文档、实施和不相关的清理分开提交，除非用户另有要求

TDD 期望

• 任务是实施导向时，从失败的测试开始
• 优先纯逻辑测试，再做 UI 或集成测试
• 将命令层编排与核心规则分开
• 明确说明测试了什么，什么保持延后

好用的默认值

• 使用 tasks/<topic>/ 作为包根目录
• 使用编号文件名暗示执行顺序
• 将所有全局约束放在 PRINCIPLES.md，不在各处重复
• 将类提示词指令放入每个任务文件的 Agent Brief
• 保持任务文件简洁、以执行为导向

共享文档分工校验

创建或重构任务包后，主动检查三份共享文档是否职责清晰：

README.md 应承载什么

• 人类读者第一次进入目录时需要知道的信息
• 当前阶段目标与范围
• 文档结构
• 推荐阅读顺序
• 推荐启动方式

README.md 不应承载什么

• 只对 AI 执行有意义的详细技术推理
• 过细的实现切分判断
• 大量跨任务硬约束

PRINCIPLES.md 应承载什么

• 所有任务共享且长期有效的规则
• TDD、分层、抽象边界、反模式
• 提交和汇报要求

PRINCIPLES.md 不应承载什么

• 只对当前阶段成立的技术策略
• 需求背景摘录
• 当前这轮做什么不做什么的详细范围说明

00-context-and-scope.md 应承载什么

• 面向 AI/Agent 的阶段技术上下文
• 会影响后续任务拆分与实现路径的推理
• 当前阶段的架构判断
• 当前阶段推荐的实现切分
• 当前阶段不要提前做的事

00-context-and-scope.md 不应承载什么

• 纯导航信息
• 与 README.md 完全重复的介绍性文字
• 所有任务长期共享的硬规则

任务文件校验

创建每个 01+ 任务文件时，检查：

• 任务文件是否主要描述“本任务做什么”，而不是重复共享文档
• 任务文件中若引用 PRINCIPLES.md 和 00-context-and-scope.md，是否确实依赖它们
• 领域任务不要混入命令层或 UI 约束
• 命令层任务不要把纯领域规则重新写一遍
• 若某段内容同时出现在多个任务文件中，优先上提到共享文档

附加资源

• 文件模板和推荐章节见 reference.md
• 具体示例见 examples.md