dev-workflow-planning

开发工作流规划

使用此技能将模糊或高风险的工程工作转化为范围明确的执行计划，涵盖范围、顺序、检查点、验证和交接。此技能负责规划深度、执行方式和多 Agent 防护措施，不负责系统设计、PRD 编写或分支策略决策。

快速参考

任务	使用
规划结构和产物	references/planning-templates.md、assets/template-work-item-ticket.md、assets/template-milestone-checkpoint.md、../product-management/assets/ops/template-dor-dod.md
特定平台的工作流映射	references/platform-workflows.md、../ai-agents/references/agent-delivery-methods.md
多会话规划状态	references/long-horizon-journaling.md
并行、会话和恢复的防护措施	references/operational-checklists.md、references/session-patterns.md、references/session-scope-budgeting.md、../ai-agents/references/context-rotation-and-state.md
规范驱动工具全景（GitHub Spec Kit、Kiro、BMAD）	references/spec-driven-dev-landscape.md
测试上下文规划	../qa-agent-testing/references/coding-agent-regression-testing.md
量化不确定的交付成本	references/uncertain-work-cost.md
混合变更、无法进行红灯测试、按风险确定流程深度	references/change-classes.md
来源映射	data/sources.json

适用场景

• 将功能、迁移、重构或高风险缺陷修复拆解为经过验证的步骤。
• 判断工作应按顺序执行，还是分为范围明确的并行波次。
• 将需求或 RFC 转化为包含成功标准和回滚考量的计划契约。
• 将长期运行的 Agent 工作限制在持久化产物和范围限制内。

转至其他技能

• 系统设计、服务边界或 ADR：使用 software-architecture-design。
• 规划前的 PRD 或 RFC 编写：使用 docs-ai-prd。
• 仓库成熟度、上下文层或指令推广：使用 dev-context-engineering。
• 分支和 PR 工作流策略：使用 dev-git-workflow。
• 测试策略归属或调试正在发生的故障：使用 qa-testing-strategy 或 qa-debugging。

默认做法

• 在拆解工作前，先明确预期结果和成功标准。
• 选择适合任务的最小持久化规划产物。
• 根据实际风险和范围调整规划深度。
• 接口仍在变动或文件存在重叠时，优先按顺序执行。
• 为每位并行工作者提供独立完整的任务说明和明确的文件归属；记录其是从全新状态开始，还是基于父级历史分叉。
• 针对受影响的代码提供有针对性的测试上下文，而非笼统地要求“先编写测试”。

工作流

1. 确认目标、范围边界、成功标准以及缺少的输入。
2. 将变更归类为修复、变更、重构或新增，并采取对应的第一步（变更类别）。然后根据出错的代价选择规划深度：琐碎、轻量、完整计划约定或规范驱动。
3. 安排第一步，以排除风险最高的假设；并指出什么观察结果会使计划失效（例如，调用点超出预估，或范围外的测试失败）。出现这种情况时，停止并重新规划，不要继续执行。
4. 锁定计划约定：目标、范围、依赖项、执行顺序、验证和回滚。
5. 选择执行方式：顺序执行，或按依赖关系分波次执行。
6. 分批执行，每个波次之间进行验证，并将检查点状态记录在持久化工件中。
7. 最后进行交接，说明已完成的事项、未完成的事项、已检查的内容，以及下一步有限范围的操作。

核心决策

规划深度

复杂度	深度	工件	触发条件
单文件，结果明确	琐碎	无或一句话	直接执行
多步，范围明确	低	目标 + 步骤 + 验证	2-5 个文件，无共享接口
多文件，接口重叠	中	包含文件归属的完整计划约定	3 个以上文件，涉及架构或 API 变更
多 Agent、长周期或需要规范	高	规范 → 设计 → 任务 → 实现	影响生产环境，依赖项未知

变更类别与第一步

根据可观察行为的变化进行分类。每个步骤只归入一个类别；混合请求应拆分。

类别	行为	第一步	测试优先规则
修复	当前行为不符合已达成一致的规范	编写一个能复现 bug 的测试	新测试因报告的问题而在当前代码上失败，随后通过；并保留为回归测试
变更	当前行为正确，但预期行为发生变化	找出断言旧行为的测试，并修改它们以表达新行为	修改后的测试在代码变更前失败；计划要列出每一处被修改的断言
重构	行为必须完全不变	先让现有测试套件全部通过；如果覆盖不足，则添加用于固定当前行为的特征测试	不修改断言，也不添加行为测试；同一测试套件在重构前后均通过
新增	新增行为；现有行为不变	编写验收标准和接口，并检查是否有可复用代码	实现前，为每条标准编写会失败的新测试；现有测试保持原样并通过

类别决定第一步；风险决定相应的规划深度。只有当流程的结果可能改变计划时，才投入相应流程；不可逆的损害应视为一道关卡（决策步骤和各类别的规划尺度，摘自 foundations-decision-theory）。

计划就绪关卡

中等或高深度计划必须在实现开始前通过以下检查：

1. 歧义关卡。 如果交付内容、成功标准或技术方案存在多种合理解释，就停止并询问。不要基于猜测制定计划。
2. 模式依据。 对命名、错误处理、日志记录、数据访问和测试，在受影响的范围内引用一个现有示例，格式为 path:line。如果没有示例，就明确说明；不要凭空编造惯例。
3. 冷读者测试。 不熟悉代码库的人仅凭计划就能执行每一步，无需进一步搜索或提问。如果做不到，就补充缺失的路径、导入和命令。
4. 偏差日志。 实现过程中，记录每一处偏离计划的情况及其原因，并在交接时一并附上。

何时采用规范驱动，何时优先原型

选择规范驱动	选择原型优先
Agent 执行前必须先有规范（Kiro、Spec Kit 工作流）	一次性脚手架、演示，或用于探索未知问题的快速验证
多 Agent 交接，且有验收标准	单次会话、单个开发者，无需交接
需求必须经受上下文重置	目标会在同一会话中发生变化
下游 AI Agent 会重新解析契约	人类以交互方式主导所有决策

根据能够消除不确定性的方式选择深入程度。如果有界的快速验证或只读探索能比完整计划更快地解答问题，就先执行，并暂时保留计划。

分支分类与操作手册遵循度

• 行动前，先对每个“选择哪种方案？”分支进行分类：可观察型（低成本地分别制作两种原型并进行比较）或偏好型（询问人类）。可观察型分支不要提问；偏好型分支不要制作原型。
• 选定工作流或操作手册后，将其中的步骤原样复制到待办列表；不执行的步骤应标记为 skip: <reason>，而不是直接删除。
• 爬山式优化循环（每次测量只做一次更改、冻结敏感测试框架、明确目标和最少尝试次数、记录决策）由 agents-swarm-orchestration 负责，而非本技能。

AI 编码时代的估算

AI 编码 Agent 将瓶颈从打字速度转移到了决策质量、审查带宽和验证成本。按故事点或人类打字速度校准的工时进行估算，会低估工作量：

• 估算应以审查和验证负担为基准，而非生成时间。跨三个文件的 200 行 AI 生成差异，接口稳定时只需几分钟生成，却可能需要数小时才能安全审查——真正受限的资源是审查时间，而不是生成时间。
• 对于模糊的工作，编写规范和澄清需求所需的时间如今占主导。规范不足的提示词造成的返工周期，代价高于 AI 辅助执行最初节省的时间；应为访谈和澄清阶段明确预留时间（参见循环前设置阶段），不要将其并入“实现”。
• 不要因 AI 看似快速的生成速度而缩减不可逆或影响范围大的工作（架构迁移、身份验证、计费、公共 API）的估算。生成很快，但安全发布和验证流程并不快；仅按生成速度估算会导致计划范围不足。
• 看似合理的 AI 生成差异并不能证明代码正确。对 AI 生成代码，应根据其风险等级，采用与人工编写代码同等严格的验证标准——干净的差异会带来虚假的信心，而不是减少审查时间。
• 将 AI Agent 出现之前的历史速度或吞吐量基线视为不可靠的估算依据。应根据团队当前的 AI 辅助工作吞吐量重新校准，而不是沿用去年的单故事平均值。

当不确定的审查、返工或工作项数量可能改变预算决策时，请使用不确定工作量估算方法。进度安排应保留在依赖关系计划中；成本模拟无法确定关键路径。

计划模式（Claude Code）

• 对于模糊或高风险的更改，如果在编辑前审查计划会有所帮助，请使用 /plan。Claude Code 命令和权限文档可用于查询当前入口和命令限制。

执行模型

• 当风险较高或存在重叠时，默认按顺序执行
• 仅当任务确实相互独立时，才采用分波并行
• 明确指定 depends_on、共享接口定义，以及每波之间的一次验证
• 一旦出现接口频繁变动或文件重叠，就停止并行
• 对于架构或 API 迁移，将扩展 → 迁移读写方 → 收缩规划为独立里程碑，每个里程碑都可独立部署和回退；绝不能规划同时更改生产者和所有消费者的步骤

对于包含并行工作的计划，应明确建模依赖关系，而不是依赖列表顺序。每个工作项都应注明前置条件、产出的制品或状态、负责人、验证证据，以及由此解锁的下游工作项。只有观察到前置条件时，才将工作项标记为 ready；存在尚未解决的具名依赖时，标记为 blocked；只有证据确实存在时，才标记为 done。

识别当前关键路径，以及并行分支汇合的集成点。范围或证据发生变化时，重新计算关键路径；给非关键任务增加工作者并不会缩短计划。只有通过集成检查，里程碑才算完成，即使所有参与任务单独报告已完成也是如此。

下一个符合条件的里程碑

当 PRD 或计划包含 交付里程碑表 时，应从表中选择下一项工作，而不是凭记忆选择：

1. 检查该表是否为 DAG：每个 depends-on id 都存在，且没有环。只有不存在有向环时，才存在拓扑排序；如果存在环，应指出并重新划分里程碑，而不是选择顺序（foundations-graph-theory，快速参考）。
2. 符合条件意味着状态为 pending，且所有依赖项均为 done；done 意味着其验收检查已通过。
3. 出现并列时，选择下游待处理里程碑最多的里程碑，无论是直接还是间接下游。此并列决胜规则是规划启发式方法，并非图论定理。若仍并列，则选择能消除风险最高假设的里程碑（工作流步骤 3）。
4. 开始前将其设为 in-progress。有并行工作者时，按 agents-swarm-orchestration 中的说明认领。只有具备检查通过的证据时，才将其设为 done。

无效顺序或受约束选择的基础方法

• 当列表顺序掩盖了依赖状态的前置条件、不可逆影响或可能导致执行失效的其他顺序时，使用 planning/search。返回初始状态证据、操作前置条件／影响、重放后有效的顺序或首个未满足的前置条件，以及重新规划触发条件。未知的前置条件仍未解决；抽象顺序有效并不能证明实现成功。对于常规检查清单，或前置条件已明确列出且可直接检查的依赖 DAG，跳过此模型。
• 当不可拆分的工作选择会争夺量化容量、预算或其他硬性约束，且贪心排序可能遗漏可行组合时，使用 mathematical optimization。返回变量／取值域、目标及系数的来源、约束、可行选择，以及方法／界／差距状态。保持工作不可拆分；连续松弛只是一个界限，并非可执行的分配方案。对于普通的定性优先级排序，或输入不足以支持建模时，跳过此方法；改为记录尚未解决的权衡。此技能仍负责执行、所有权、验证和检查点。

上下文与会话规范

• 为每个工作者提供自包含的简报，并记录它是从头开始，还是基于父级历史分支；仅标注“工作者”并不能保证上下文窗口是全新或完整的（agents-swarm-orchestration 中也是如此）
• 将计划、进度和决策持久化到文件或稳定的任务产物中
• 尽可能让每个会话只负责一个范围明确的成果
• 如果出现反复重试或重新阅读，应重新界定范围，而不是一味蛮干

范围蔓延检测

范围蔓延越早发现，越容易处理。请在每个检查点留意以下信号：

• 任务现在涉及原计划约定中未提及的文件或系统，而且没人有意决定这样做。
• 实施过程中出现了原始成功标准中未包含的新验收标准（“既然我们已经在这里，不如顺便……”）。
• “快速修复”步骤膨胀成重构，因为 Agent（或人）发现了相邻的糟糕代码。
• 验证计划不断扩大，覆盖了原始范围从未承诺的内容。
• 多个检查点都反复将预计剩余工作重置为“快完成了”，但没有取得实质进展。

应对方式：不要默默将新增内容纳入当前会话。明确指出新增内容，然后选择以下做法之一：(a) 重新界定计划约定，并告知人类发生了什么变化以及原因；或 (b) 将其拆分为后续里程碑，同时保持当前会话的原始成功标准不变。未经重新协商约定就吸纳新范围，会让有界任务变成无界任务。

计划文档的输出格式

在版本控制的计划中，让验收标准保持可解析。选择文档格式时，请使用 docs-ai-prd。

测试上下文与验证

• 包含受影响区域的 source -> tests 上下文
• 如果无法获取完整依赖关系图，请采用当前可用的最佳近似方案
• 在交接内容中提供确切的验证命令或审查证据
• 实施错误修复或新增行为前，应用相应类别的测试优先规则（变更类别）：记录当前代码中的失败或缺口，然后证明变更后问题已通过验证
• 对于保持行为不变的重构或安全变更，指出确保其安全的唯一事实，并通过运行实际代码路径证明这一点，而不是只阅读差异；运行相关的现有检查，分别建立变更前后的回归基线，并针对这些检查未覆盖的风险添加专项检查或审查
• 如果无法进行规范或约定验证，请如实说明，不要声称验证已通过

多会话规划状态

对于会跨越多个会话的工作，请选择最小的现有持久化产物，以保留目标、决策、已验证的进展和下一项范围明确的行动。多会话规划状态 提供了两种可选布局，分别适用于探索性工作和有界实施工作。使用 ai-coding-agents-state 处理自主循环终止，使用 agents-swarm-orchestration 进行多波次任务分派。

常见陷阱

• 制定了拆解工作的计划，却没有说明决策边界、成功标准或明确的停止条件。

• 由于任务清单表面上看似互相独立，便让多个并行工作者处理重叠文件或不稳定接口。

• 任务实际需要具体命令、数据集或人工审核节点，却把“需要测试”当作充分的验证计划。

• 持久化的状态太少，导致后续会话不得不从聊天记录而非持久化产物中还原意图和进度。

• 反复重试、陷入混乱后仍维持原有范围，而不是缩小目标，直至结果仍可验证。

• 未对照一手网络来源核实，就把已知错误、回归问题或框架／编译器／运行时陷阱当作当前事实；特定版本的崩溃或变通方案很快就会过时。

• 未对照 Claude Code、Codex、GitHub 或相关工作流工具的官方文档进行核实，就断言平台特定的工作流规则、规划功能或产品限制仍是当前行为。

常见反模式

• 对本应直接执行的低风险工作，安排完整规格的规划开销。
• 将工作拆成许多微小任务，却没有明确负责人、依赖关系或回滚逻辑。
• 把完整的对话历史交给工作者，而不是提供范围明确的任务包和清晰的验收标准。
• 在计划中的验证关卡实际运行前，就宣称一个工作阶段已完成。
• 把最终交接写成叙述性总结，而不是准确说明哪些内容发生了变化、检查了什么，以及还有什么未完成。

导航

仅针对明确的决策缺口加载基础资料。检查其适用／跳过条件；若不适用，则继续已应用的工作流，或仅在确实需要时转交负责人处理。

• 规划和平台参考资料：references/planning-templates.md、references/platform-workflows.md、../ai-agents/references/agent-delivery-methods.md
• 并行处理和恢复：references/operational-checklists.md、references/session-patterns.md、references/session-scope-budgeting.md、references/flow-metrics.md、../ai-agents/references/context-rotation-and-state.md
• 支持性工作流参考资料：../product-management/references/agile-ceremony-patterns.md、../product-management/references/remote-async-workflows.md、../product-management/references/technical-debt-management.md、../qa-agent-testing/references/coding-agent-regression-testing.md、data/sources.json
• 规格驱动工具和工作流：references/spec-driven-dev-landscape.md
• 基础理论：../foundations-theory-of-constraints/SKILL.md — 瓶颈识别、WIP 限制和 T/CU 吞吐量核算；这些是 flow-metrics.md 和 product-management technical-debt-management.md 的理论基础
• 模板：../product-management/assets/ops/template-dor-dod.md、assets/template-work-item-ticket.md、assets/template-milestone-checkpoint.md、assets/example-medium-plan-contract.md（中等规模计划契约示例，含完整演示）

经验循环

如果之前的决策或注意事项与当前任务相关，请查阅 learnings.consolidated.md（如果存在）；仅在需要查看历史记录或没有其他文件可用时，才查阅 learnings.md。否则，请跳过这两个文件。

应用相关经验后，如果你遇到了值得记住的模式、值得避免的错误，或令人意外的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条带日期的条目。不要修改 SKILL.md 本身。