# Project Planning

> Use when 需要把一个功能从模糊想法推进到可执行开发计划，并在同一份计划文档中完成需求分析、任务拆解与状态追踪。

- Skill: `zhucl1006/project-planning` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add zhucl1006/project-planning`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhucl1006/project-planning/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zhucl1006 (https://skillmd.com/u/zhucl1006)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zhucl1006/project-planning

---


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

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

## 何时使用

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

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

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

1. 输出文件：`docs/plans/001-feature-name.md`（3 位编号 + kebab-case 名称）。
2. 模板来源：`./plan-templates/combined-plan-template.md`。
3. 文档必须同时包含：
   - 需求分析（目标、边界、风险、隐含需求、验收标准）
   - 代码影响分析（适用时记录图谱状态、受影响模块、公共契约、持久化/配置影响和验证矩阵）
   - 执行编排（subagent 适用性、串并行关系、写入边界、阶段门禁）
   - 实施计划（任务拆解、依赖关系、TDD 执行步骤）
   - 状态管理（整体进度、任务状态总览、执行记录）
4. 每个任务必须可追踪：`任务ID`、`状态`、`负责人`、`执行模式`、`依赖任务`、`开始时间`、`完成时间`、`阻塞原因`。
5. 初始状态统一为：`待开始`。

## 工作模式

### 模式 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`。
3. 不得把“配置文件存在”当作 MCP 可用。只有工具已实际暴露且调用成功时，才优先使用 impact-radius；跨模块行为增加 affected-flow，并使用 minimal-context 或 review-context 收敛源码范围。工具名称以当前环境实际暴露为准，常见名称为 `get_impact_radius_tool`、`get_affected_flows_tool`、`get_minimal_context_tool` 和 `get_review_context_tool`。
4. 仓库未注册时不得静默注册。向用户提供：

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

5. 若 MCP 不可用、仓库未注册、图谱为空/陈旧且无法刷新，或查询不受支持，只记录一次限制，立即降级为 `rg` 调用点、测试、包边界、schema、配置和仓库 harness 分析。
6. 空图、陈旧图或失败查询的低风险/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. 每个任务必须列出：
   - 创建文件
   - 修改文件
   - 测试文件
   - 只读参考
   - 禁止修改
4. 每个任务必须标注 `执行模式`：`串行` / `可并行` / `合并门禁`。
5. 每个可并行任务必须标注 `并行组` 和 `合并点`。
6. 每个任务必须具备可执行命令与预期输出。
7. 未通过 RED/GREEN/REFACTOR 任一环节，不得标记为 `已完成`。
8. 阻塞型风险未处理前，不得规划进入依赖该风险的开发阶段。

## 与其他技能关系

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

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