项目规划（分析 + 计划一体化）

本技能用于在开发前产出可执行的“分析计划文件”，既完成需求分析，也完成实施任务编排。

何时使用

• 你要规划一个新功能、模块改造或缺陷修复
• 你希望先澄清需求，再得到可落地的开发任务
• 你需要一份可追踪状态的计划文档，供后续 project-workflow 执行

不适用：仅需直接编码、不需要分析与计划沉淀的超小改动。

核心产出契约（必须遵守）

1. 输出文件：docs/plans/001-feature-name.md（3 位编号 + kebab-case 名称）。
2. 模板来源：./plan-templates/combined-plan-template.md。
3. 文档必须同时包含：

- 需求分析（目标、边界、风险、隐含需求、验收标准） - 代码影响分析（适用时记录图谱状态、受影响模块、公共契约、持久化/配置影响和验证矩阵） - 执行编排（subagent 适用性、串并行关系、写入边界、阶段门禁） - 实施计划（任务拆解、依赖关系、TDD 执行步骤） - 状态管理（整体进度、任务状态总览、执行记录）

1. 每个任务必须可追踪：任务ID、状态、负责人、执行模式、依赖任务、开始时间、完成时间、阻塞原因。
2. 初始状态统一为：待开始。

工作模式

模式 A：分析驱动（需求不清晰）

触发信号：需求边界模糊、方案分歧明显、验收标准不完整。

执行方式：

• 一次只问一个问题，优先多选题
• 每轮给出 2-3 个方案（含推荐与权衡）
• 分段确认后再进入任务拆解

模式 B：直写计划（需求清晰）

触发信号：目标、范围、验收标准、技术约束都已明确。

执行方式：

• 快速复述需求并确认边界
• 直接输出分析结论与实施计划

执行流程

Step 0：读取上下文

• 读取 docs/README.md
• 读取相关规范（如存在）：docs/specs/PRD.md、docs/specs/SAD.md
• 读取相关模块文档（如存在）：docs/modules/*.md
• 检查既有计划：docs/plans/

Step 0.5：Code Review Graph 影响预检

对非微小代码修改、缺陷修复、代码审查、重构、公共契约变更或重要界面流程变更执行本步骤。纯文档、微小文案或不影响行为的小修正可说明理由后跳过。

1. 使用 git rev-parse --show-toplevel 获取准确仓库根目录，后续每次查询都传入该路径或已验证的唯一 alias。
2. CLI 是基础路径：

- uvx code-review-graph repos - uvx code-review-graph status --repo "$ROOT" - 图谱落后于当前 HEAD、未覆盖工作树、刚经历 rebase 或大批量变更时，运行 uvx code-review-graph update --repo "$ROOT" --base HEAD --brief。

1. 不得把“配置文件存在”当作 MCP 可用。只有工具已实际暴露且调用成功时，才优先使用 impact-radius；跨模块行为增加 affected-flow，并使用 minimal-context 或 review-context 收敛源码范围。工具名称以当前环境实际暴露为准，常见名称为 getimpactradiustool、getaffectedflowstool、getminimalcontexttool 和 getreviewcontexttool。
2. 仓库未注册时不得静默注册。向用户提供：

ROOT="$(git rev-parse --show-toplevel)"
uvx code-review-graph register "$ROOT" --alias "<unique-project-alias>"

1. 若 MCP 不可用、仓库未注册、图谱为空/陈旧且无法刷新，或查询不受支持，只记录一次限制，立即降级为 rg 调用点、测试、包边界、schema、配置和仓库 harness 分析。
2. 空图、陈旧图或失败查询的低风险/token-savings 输出不得作为计划证据。图谱结论必须与源码和测试交叉验证。

计划中的影响分析至少记录：图谱状态与证据来源、受影响模块、公共契约、持久化影响、配置影响、受影响流程、风险等级、验证矩阵和降级说明。

Step 1：需求澄清与边界确认

至少明确以下内容：

• 业务目标（为什么做）
• 范围内 / 范围外（做什么 / 不做什么）
• 成功标准（如何判定完成）
• 关键约束（技术、时间、依赖）

Step 2：产出需求分析

在计划文档中输出：

• 需求摘要
• 用户路径 / 核心交互
• 验收标准（AC）草案：改写为可测试条目
• 风险与假设
• Code Review Graph 影响分析（适用时）
• 隐含需求清单（权限、空状态、错误状态、性能、兼容性、可观测性）

Step 3：产出实施计划

任务拆解要求：

• 单任务粒度 2-5 分钟
• 明确依赖与执行顺序
• 判断是否适合使用 subagent；适合时写清预计 subagent、职责、输入、输出与验收方式
• 明确哪些任务必须串行、哪些任务可并行、并行任务的合并点是什么
• 明确每个任务允许写入、允许新增、只读参考、禁止修改的文件或模块
• 明确阶段门禁：哪些条件满足后才能进入下一阶段
• 将高影响或高概率风险转化为前置探针任务或门禁条件
• 每个任务包含 TDD 最小闭环：

- RED：先写失败测试并验证失败 - GREEN：最小实现并验证通过 - REFACTOR：重构并回归验证

• 每个任务写清：文件路径、命令、预期结果、完成证据

subagent 编排规则：

• 只有当任务可独立验证、写入边界清晰且依赖关系明确时，才建议使用 subagent
• 并行 subagent 不得写入同一文件；如必须共享核心文件，改为串行任务
• 主 agent 负责最终集成、冲突处理、验收判断和计划状态更新
• 计划必须说明 subagent 的预计类型或角色；无法确定时写 不建议使用 subagent 并说明原因
• subagent 不得越过计划中的写入边界；新增边界必须先更新计划并经过确认

Step 4：初始化状态管理

计划落地时必须初始化：

• 整体进度（按阶段）
• 任务状态总览表（全部任务默认 待开始）
• 执行记录（写入第一条记录）

Step 5：质量校验（写入前自检）

• KISS：任务描述不绕弯、可直接执行
• YAGNI：删除“可能以后要做”的内容
• DRY：避免重复任务；相同模式合并
• SOLID：任务职责单一、依赖方向清晰
• 可验证：每条 AC 都能映射到测试或验证动作
• 可编排：串并行关系、写入边界、阶段门禁清晰，无隐式共享写入
• 可审查：风险前置处理、subagent 使用理由、合并点和验收证据可被独立检查
• 影响可追踪：图谱/降级证据、源码交叉验证和验证矩阵完整，且未用图谱替代测试、CI、类型检查、安全检查或项目 harness

Step 6：交付与下一步

完成后明确提示：

• 计划文件位置
• 推荐使用 project-workflow 执行
• 如有未决问题，列出“阻塞项 + 建议决策”

对话与澄清规范

• 每次只推进一个关键问题
• 优先多选题，减少沟通成本
• 回答后立即更新分析结论，避免信息漂移
• 当信息不足时，明确标注“假设”而不是臆测

任务编写规则（强约束）

1. 每个任务必须有唯一 任务ID（如 T01、T02）。
2. 每个任务必须标注 依赖任务（无依赖写 无）。
3. 每个任务必须列出：

- 创建文件 - 修改文件 - 测试文件 - 只读参考 - 禁止修改

1. 每个任务必须标注 执行模式：串行 / 可并行 / 合并门禁。
2. 每个可并行任务必须标注 并行组 和 合并点。
3. 每个任务必须具备可执行命令与预期输出。
4. 未通过 RED/GREEN/REFACTOR 任一环节，不得标记为 已完成。
5. 阻塞型风险未处理前，不得规划进入依赖该风险的开发阶段。

与其他技能关系

• project-docs-setup：先补齐项目文档，再做计划。
• project-workflow：按本技能产出的计划执行开发。

建议链路：project-docs-setup → project-planning → project-workflow。