编写 working-plan

将完整的技术设计转化为详细的 working-plan，拆分为可在 10 分钟内完成的小任务。

任务清单

• ] 入口检查 — 确认 technical-spec 文件存在且设计已完整
• ] 读取 technical-spec — 理解设计概述、组件接口、数据流、验收标准
• ] 提取组件 — 列出需要创建或修改的文件和函数/类接口
• ] 识别任务类型 — 创建、修改、测试、配置、文档
• ] 拆解为小任务 — 每个任务控制在 10 分钟以内，成对安排实现与测试任务
• ] 排序任务 — 按依赖关系排序，基础优先，测试紧随
• ] 编写详细计划 — 每个任务包含确切文件路径、完整代码、验证步骤
• ] 深度自检 — 执行整合自检清单：完整性、规范对齐、任务分解、可构建性、验收标准覆盖、粒度、明确性、可验证性、顺序合理性
• ] 展示计划摘要 — 向用户展示计划概览，自动保存文件
• ] 保存计划 — 保存到 docs/sw-agiledevelopment/plans/，提交 Git 前每次询问用户
• ] 自动调用 sw-subagent-development — 交接计划文件路径和依赖摘要

核心原则

每个任务必须包含：

• 确切的文件路径
• 完整的代码（或代码结构）
• 验证步骤

任务大小： 每个任务应该能在 10 分钟以内完成。

TDD 集成： 每个实现任务后必须紧跟对应的测试任务。测试验证必须包含 RED（先失败）→ GREEN（实现后通过）。

铁律：

• 调用 sw-subagent-development 开始实现前，必须完成深度自检并保存计划文件
• 严禁跳过深度自检
• 严禁忽略入口检查直接读取 technical-spec

何时使用

mermaid
flowchart TD
    A{设计已完成？} -->|是| B{有书面 technical-spec？}
    A -->|否| C[先执行 sw-requirements-clarification]
    B -->|是| D[sw-working-plan]
    B -->|否| C

流程

mermaid
flowchart TD
    Start([开始]) --> Gate{0. 入口检查<br/>规范存在？设计完整？}
    Gate -->|否| NeedDesign[返回<br/>sw-technical-spec]
    Gate -->|是| ReadSpec[1. 读取 technical-spec 文件]
    ReadSpec --> Extract[2. 提取组件和接口]
    Extract --> Identify[3. 识别实现任务]
    Identify --> BreakDown[4. 拆解为小任务<br/>每个控制在 10 分钟以内]
    BreakDown --> Order[5. 排序任务<br/>按依赖关系]
    Order --> WritePlan[6. 编写详细计划]
    WritePlan --> SelfReview[7. 深度自检<br/>整合自检清单]
    SelfReview -->|发现问题| SelfFix[修复问题]
    SelfFix --> SelfReview
    SelfReview -->|通过| ShowSummary[8. 展示计划摘要]
    ShowSummary --> SavePlan[9. 保存计划<br/>提交前每次询问]
    SavePlan --> InvokeSubagent([10. 调用 sw-subagent-development])

详细步骤

0. 入口检查

在开始前检查以下两项：

1. technical-spec 文件是否存在：docs/sw-agiledevelopment/technical-specs/YYYY-MM-DD--<feature>.md 是否存在？
2. 设计是否已完成：该 technical-spec 是否已通过 sw-technical-spec 的快速自检？

如果任一检查未通过：

• technical-spec 不存在 → 告知用户："未找到 technical-spec 文件。请先执行 sw-technical-spec 完成技术设计阶段。"
• 设计不完整 → 告知用户："technical-spec 尚未完成快速自检。请返回 sw-technical-spec 完成自检流程。"
• 两项均通过 → 继续执行第 1 步

1. 读取 technical-spec 文件

读取 docs/sw-agiledevelopment/technical-specs/YYYY-MM-DD--<feature>.md 文件，理解以下内容：

• 设计概述
• 组件和接口
• 数据流
• 验收标准

2. 提取组件和接口

从 technical-spec 中提取：

• 需要创建或修改的文件
• 函数/类接口定义
• 依赖关系
• 验收标准清单 — 列出所有验收标准，作为后续覆盖检查的基准

3. 识别实现任务

基于组件识别任务类型：

• 创建文件 — 新模块、类、函数
• 修改文件 — 添加功能、修复 bug
• 编写测试 — 单元测试、集成测试
• 配置变更 — 配置文件、环境变量
• 文档更新 — README、注释

4. 拆解为小任务

任务大小标准： 每个任务控制在 10 分钟以内

TDD 成对要求： 每个实现任务后必须紧跟对应的测试任务，不允许累积多个实现后再统一测试。

拆解原则：

❌ 大任务: "实现用户认证模块"
✅ 小任务（成对出现）:
  - 创建 User 模型类（实现）
  - 编写 User 模型测试（测试）← 依赖上一任务
  - 实现密码哈希函数（实现）
  - 编写密码哈希测试（测试）← 依赖上一任务

5. 排序任务

成对排序原则： 实现任务和对应的测试任务必须相邻，中间不得插入其他实现任务。

按依赖关系排序：

1. 基础优先 — 被依赖的组件先实现
2. 测试紧随 — 每个实现任务后必须紧跟其测试任务
3. 集成在后 — 组件完成后再集成

错误排序示例（禁止）：

1. 创建数据模型
2. 实现业务逻辑  ← 错误：未先测试数据模型
3. 编写模型测试

正确排序示例：

1. 创建数据模型
2. 编写模型测试
3. 实现业务逻辑
4. 编写业务逻辑测试
5. 实现 API 接口
6. 编写 API 测试
7. 集成所有组件

6. 编写详细计划

统一模板（所有任务共用）：

markdown
### 任务 N: <任务名称>

**文件**: `<确切文件路径>`

**动作**: <一句话描述要做什么>

**详情**: <按任务类型填写，见下方分层要求>

**验证**: <如何确认完成>

**依赖**: <前置任务编号，无则留空>

按任务类型区分的详细度要求：

| 任务类型 | 详情字段要求 | 原因 | |----------|-------------|------| | 创建新文件 | 写完整代码或核心结构 | 实现者需要知道创建什么 | | 修改现有文件 | 写变更描述 + 关键逻辑/函数签名 | 实现者根据描述在现有代码中定位并修改 | | 编写测试 | 写测试场景列表（覆盖什么 case） | 测试代码由实现者按场景编写，避免计划阶段写大量测试代码 |

任务配对示例：

任务 1: 创建 User 模型类（创建）
任务 2: 编写 User 模型测试（测试）← 依赖任务 1
任务 3: 实现登录函数（修改）← 依赖任务 1
任务 4: 编写登录函数测试（测试）← 依赖任务 3

7. 深度自检

编写完计划后，执行以下整合自检清单。逐项确认，发现问题则修复后重新自检。

自检清单：

| # | 检查项 | 通过标准 | |---|--------|----------| | 1 | 完整性 | 无待办事项、无占位符（如 "TODO: 补充"、"后续再定"）、无空任务描述 | | 2 | 规范对齐 | 计划中每个规范需求都有对应任务，无重大范围蔓延或遗漏 | | 3 | 任务分解 | 每个任务边界清晰，能在 10 分钟以内完成 | | 4 | 可构建性 | 工程师能按此计划执行而不卡住（文件路径明确、详情足够判断如何实现） | | 5 | 验收标准覆盖 | technical-spec 中的每条验收标准都有对应的验证任务或测试任务 | | 6 | 明确性 | 每个任务有确切的文件路径、足够的详情（创建写代码、修改写描述、测试写场景）、清晰的验证步骤 | | 7 | 可验证性 | 每个任务的验证步骤可执行、可判断通过或失败 | | 8 | 顺序合理性 | 依赖关系正确，实现+测试成对相邻，基础组件优先 |

执行方式：

• Agent 自身对照清单逐项检查，无需启动 Subagent。
• 发现任何问题 → 修复计划 → 重新运行本自检清单。
• 全部通过后，展示计划摘要并自动保存。

8. 展示计划摘要

深度自检通过后，向用户展示计划摘要，然后自动保存并推进：

> "working-plan 已编写完成。计划包含 N 个任务： > - 任务 1–3: 数据模型和测试 > - 任务 4–6: 业务逻辑和测试 > - 任务 7–9: API 和集成测试 > > 预计总时间：X 分钟。 > > 现在自动保存计划文件并进入实现阶段。"

自动推进：展示摘要后自动保存文件并调用 sw-subagent-development，无需等待用户回复。用户如有修改需求可随时打断。

根本性异议回退：如果用户对计划方向有根本性异议（如"这个方案完全不行"、"规范本身有问题"、"需要重新设计"），不要在本计划中反复修改。立即回退到：

• spec 缺陷 → 回到 sw-technical-spec，重新审查或修改 technical-spec
• 设计方向错误 → 回到 sw-requirements-clarification，重新提出方案

9. 保存计划

保存到 docs/sw-agiledevelopment/plans/YYYY-MM-DD--<feature>-plan.md

Git 提交（铁律）： > 严禁一次性授权自动提交。每次 git commit 前都必须单独询问用户。

提交前询问模板： > "计划文件已保存到 docs/sw-agiledevelopment/plans/YYYY-MM-DD--<feature>-plan.md。 > 准备执行 git commit，变更摘要：新增 working-plan 文件。 > 是否允许提交？"

只有用户明确允许后才执行 git add 和 git commit。用户说"好的"、"可以"等模糊回应不算明确允许——必须追问："请明确回复'允许提交'或'不允许'。"

10. 进入实现阶段

唯一出口：调用 sw-subagent-development 技能执行计划。

上下文压缩（交接前）：

设计阶段已结束，所有关键信息已写入文件：

• 业务需求：docs/sw-agiledevelopment/business-specs/YYYY-MM-DD--<feature>.md
• 技术设计：docs/sw-agiledevelopment/technical-specs/YYYY-MM-DD--<feature>.md
• working-plan：docs/sw-agiledevelopment/plans/YYYY-MM-DD--<feature>-plan.md

执行时以文件内容为准，不依赖本会话的对话历史。

> 如平台支持，在调用 sw-subagent-development 前执行上下文压缩，释放需求澄清和计划阶段的对话历史 token。

交接内容：

• 计划文件路径：docs/sw-agiledevelopment/plans/YYYY-MM-DD--<feature>-plan.md
• 规范文件路径：docs/sw-agiledevelopment/technical-specs/YYYY-MM-DD--<feature>.md
• 任务总数和依赖关系摘要

大规模计划：如果任务数超过 20，建议分批调用 Subagent（每批 5–10 个无依赖或同层依赖的任务），避免单个 Subagent 上下文溢出。

失败回退：如果 Subagent 执行失败（如任务卡住、上下文不足），回到第 6 步（编写详细计划）重新调整任务粒度或分批策略，重新执行自检清单后再次交接。

任务模板

创建文件任务

markdown
### 任务 N: 创建 <文件名>

**文件**: `<文件路径>`

**动作**: 创建 <文件描述>

**详情**:

<完整代码或核心结构>

**验证**:
- [ ] 文件存在
- [ ] 语法正确
- [ ] 可导入/执行

修改文件任务

markdown
### 任务 N: 在 <文件名> 中 <做什么>

**文件**: `<文件路径>`

**动作**: <具体变更描述，如：在 UserService.login() 中添加密码过期检查>

**详情**: <关键逻辑或函数签名，可选>

若变更简单（如添加一个 if 判断），写关键逻辑即可

if password_expired: raise PasswordExpiredError()

**验证**:
- [ ] 修改符合预期
- [ ] 不破坏现有功能

编写测试任务

markdown
### 任务 N: 编写 <功能> 的测试

**文件**: `<测试文件路径>`

**动作**: 为 <功能> 编写单元测试

**详情**: <测试场景列表，不写完整测试代码>
- 场景 1: <正常情况>
- 场景 2: <边界情况>
- 场景 3: <错误情况>

**验证**:
- [ ] 测试可运行
- [ ] 测试先失败（RED）
- [ ] 实现后通过（GREEN）

红旗 - 停止并修正

| 想法 | 现实 | |------|------| | "这个任务 15 分钟也能做完" | 任务过大（超过 10 分钟）= 需要拆分。大任务难以估计和验证 | | "验证步骤可以省略" | 缺少验证步骤 = 不知道任务是否完成。每个任务必须有验证 | | "文件路径到时候再确定" | 文件路径不明确 = 实现者迷失。必须指定确切路径 | | "依赖关系差不多就行" | 依赖关系错误 = 阻塞或冲突。必须正确排序 | | "测试任务后面再加" | 遗漏测试任务 = 未验证的代码。测试必须包含在计划中 | | "任务顺序无所谓" | 任务顺序不合理 = 实现阻塞。必须按依赖关系排序 | | "跳过深度自检" | 自检清单捕获待办、占位符、遗漏、不可执行任务。跳过 = 有缺陷的计划 | | "自检清单遗漏验收标准覆盖" | 验收标准没对应验证任务 = spec 目标无法验证。必须逐条对照 | | "修复后未重新执行自检清单" | 修改可能引入新的占位符或矛盾。重新自检是铁律 | | "修改任务必须写完整代码上下文" | 变更描述 + 关键逻辑足够让实现者定位。不需要把计划变成代码 diff | | "设计不完整就开始写计划" | 不完整的设计可能方向错误。先确认入口检查 | | "计划文件直接提交 Git" | 每次提交前必须单独询问用户。不允许一次性授权 | | "用户会同意提交的，不用问" | 每次提交前必须单独询问。假设用户同意 = 违规 | | "计划里不写完整代码，实现时会出错" | 创建任务写代码，修改/测试写描述+场景，足够指导实现。完整代码在实现阶段写 | | "TDD 只是建议，实现完再补测试也行" | 测试后置 = 测试被跳过或质量差。计划中必须实现+测试成对出现 |

常见借口与真相

| 借口 | 真相 | |------|------| | "任务拆分太细太繁琐" | 细粒度任务提高可预测性和可验证性。大任务容易遗漏步骤 | | "验证步骤到时候再想" | 没有验证步骤 = 无法确认任务完成。计划时必须定义 | | "文件路径实现时再定" | 模糊的文件路径导致实现者做不必要的决策 | | "测试可以单独一个阶段" | 测试紧随实现是 TDD 原则。分离测试 = 可能跳过 | | "依赖关系很复杂，简化一下" | 错误的依赖关系导致实现阻塞。复杂依赖需要仔细分析 | | "入口检查太麻烦，直接读规范" | 没有规范或设计不完整就写计划 = 方向错误 + 浪费轮次。检查不可跳过 | | "自检清单太繁琐，快速过一下就行" | 整合清单同时覆盖结构缺陷（待办/占位符）和逻辑缺陷（验收标准遗漏）。跳过 = 有漏洞 | | "用户会同意提交的，不用问" | 每次提交前必须单独询问。假设用户同意 = 违规 | | "计划里不写完整代码，实现时会出错" | 创建任务写代码，修改/测试写描述+场景，足够指导实现。完整代码在实现阶段写 |

YAGNI 原则

计划中只包含 technical-spec 明确要求的内容：

• 不要添加 technical-spec 未要求的功能
• 不要过度设计
• 不要假设未来需求

示例

输入规范（简化）

markdown
## 用户认证

### 组件
- User 类：username, password_hash
- 登录函数：验证用户名密码

### 接口

class User: def __init__(self, username: str, password: str) def verify_password(self, password: str) -> bool

def login(username: str, password: str) -> User | None

输出 working-plan

markdown
## 用户认证 working-plan

### 任务 1: 创建 User 模型类

**目标**: 创建 User 类，包含用户名和密码哈希
**文件**: `dev/auth/models.py`
**内容**: `class User` 含 `__init__`, `_hash_password`, `verify_password`
**验证**: 文件可导入 / User 类可实例化 / 密码哈希正确生成

### 任务 2: 编写 User 模型测试 ← 依赖任务 1

**目标**: 为 User 类编写单元测试
**文件**: `dev/auth/test_models.py`
**内容**: `test_user_creation`, `test_password_verification_success`, `test_password_verification_failure`
**验证**: 测试可运行 / 先失败（RED）/ 实现后通过（GREEN）

### 任务 3: 实现登录函数 ← 依赖任务 1

**目标**: 实现登录验证逻辑
**文件**: `dev/auth/service.py`
**内容**: `def login` 调用 `get_user_from_db`，验证密码后返回 User 或 None
**验证**: 函数可调用 / 正确用户返回 User / 错误密码返回 None

### 任务 4: 编写登录函数测试 ← 依赖任务 3

**目标**: 为登录函数编写测试
**文件**: `dev/auth/test_service.py`
**内容**: `test_login_success`, `test_login_wrong_password`, `test_login_user_not_found`（mock 数据库）
**验证**: 所有场景覆盖 / 先失败（RED）/ 实现后通过（GREEN）

与其他技能的集成

前置 Skill: sw-technical-spec（提供完整的 technical-spec）

后续 Skill: sw-subagent-development（执行计划）

相关 Skill:

• sw-test-driven-dev — 确保每个任务遵循 TDD

输出示例

计划文件: docs/sw-agiledevelopment/plans/2026-04-08--auth-plan.md

返回摘要格式：

markdown
## working-plan 完成

**计划文件**: `docs/sw-agiledevelopment/plans/2026-04-08--auth-plan.md`
**任务数**: 8
**预计时间**: 40 分钟

### 任务概览
| 编号 | 任务 | 文件 | 依赖 |
|------|------|------|------|
| 1 | 创建 User 模型 | `dev/auth/models.py` | - |
| 2 | 编写模型测试 | `dev/auth/test_models.py` | 1 |
| 3 | 实现登录函数 | `dev/auth/service.py` | 1 |
| 4 | 编写登录测试 | `dev/auth/test_service.py` | 3 |

**下一步**: 调用 sw-subagent-development 执行计划