项目规划

项目计划产出工具，帮助你将想法转化为可执行的开发计划。

核心流程

1. 判断需求清晰度
   ├─ 需求不明确 → Brainstorming 模式 → 设计文档
   └─ 需求明确   → Writing Plans 模式 → 实现计划

2. 保存计划文档到 docs/plans/

3. 提供执行选项
   ├─ 使用 project-workflow 执行计划
   ├─ 使用 feature-dev 自动执行
   └─ 手动执行

Phase 1: 判断需求清晰度

在开始前自动判断。

1.1 评估需求清晰度

通过以下问题评估：

需求明确的标志：

• 用户清楚描述了功能边界和验收标准
• 技术方案已确定（使用什么技术栈、库、框架）
• 有明确的输入输出和数据流
• 可以直接开始编写实现步骤

需求不明确的标志：

• 用户只有模糊的想法或目标
• 不确定技术方案或有多种选择
• 需要探索现有代码库的实现方式
• 需要讨论架构设计和权衡

1.2 路由逻辑

if 需求明确:
    → Phase 2: Writing Plans 模式
else:
    → Phase 3: Brainstorming 模式

1.3 询问用户确认（可选）

如果不确定，可以询问用户：

"我注意到你的需求 [明确/不太明确]。

建议使用：
- Brainstorming 模式：通过多轮问答澄清需求和设计方案
- Writing Plans 模式：直接编写详细的 TDD 实现计划

你希望使用哪种模式？"

Phase 2: Writing Plans 模式

适用于需求明确的场景。

2.1 核心原则

编写详细的实现计划，假设工程师：

• 是熟练的开发者
• 对我们的代码逻辑和工具链几乎零了解
• 测试设计能力一般

计划特点：

• 每个步骤是一个小动作（2-5 分钟）
• 遵循 TDD：写测试 → 运行失败 → 实现 → 运行通过 → 提交
• 包含完整的代码示例和命令
• DRY、YAGNI、频繁提交

2.2 计划文档结构

文件路径： docs/plans/001-feature-name.md（使用3位数字编号）

模板文件： ./plan-templates/combined-plan-template.md

必需的文档头部：

# [功能名称] 实施计划

> **给 Claude：** 必需的子技能：使用 project-workflow 逐任务实施此计划。

**创建时间：** YYYY-MM-DD
**状态：** 草稿 / 已批准 / 进行中 / 已完成
**负责人：** [负责人名称]

**目标：** [一句话描述要构建什么]

**架构：** [2-3 句话描述实现方法]

**技术栈：** [关键技术/库]

---

状态管理要求：

• 必须包含：整体进度、任务状态总览、执行记录
• 每个任务必须填写：状态、负责人、开始时间、完成时间、阻塞原因
• 初始状态统一为：待开始

2.3 任务结构模板

每个任务按以下结构编写：

### 任务 N：[组件名称]

**状态:** 待开始 / 进行中 / 阻塞 / 已完成 / 已取消
**负责人:** [负责人名称]
**开始时间:** YYYY-MM-DD
**完成时间:** YYYY-MM-DD
**阻塞原因:** [如适用]

**文件：**

- 创建：`exact/path/to/file.py`
- 修改：`exact/path/to/existing.py:123-145`
- 测试：`tests/exact/path/to/test.py`

**步骤 1：编写失败的测试**

\`\`\`python
def test_specific_behavior():
result = function(input)
assert result == expected
\`\`\`

**步骤 2：运行测试验证失败**

运行：`pytest tests/path/test.py::test_name -v`
预期：FAIL with "function not defined"

**步骤 3：编写最小实现**

\`\`\`python
def function(input):
return expected
\`\`\`

**步骤 4：运行测试验证通过**

运行：`pytest tests/path/test.py::test_name -v`
预期：PASS

**步骤 5：提交**

\`\`\`bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
\`\`\`

2.4 编写流程

Step 1: 理解项目上下文

1. 检查项目文档（docs/README.md, PRD.md, SAD.md）
2. 查看相关代码文件
3. 了解现有的测试模式和代码风格
4. 检查 AGENTS.md 中的约定和反模式

Step 2: 分解任务

1. 将功能分解为独立的组件或模块
2. 每个组件进一步分解为 TDD 步骤
3. 确定任务之间的依赖关系
4. 按依赖顺序排列任务

Step 3: 编写详细步骤

对于每个任务：
  1. 指定精确的文件路径
  2. 编写完整的测试代码
  3. 提供运行命令和预期输出
  4. 编写最小化的实现代码
  5. 提供提交命令和消息

Step 4: 添加参考信息

- 引用相关的 skill（使用 @ 语法）
- 链接相关文档
- 注明技术决策的原因

2.5 保存和交付

1. 保存计划到 docs/plans/001-feature-name.md
2. 提供执行选项（见 Phase 4）

Phase 3: Brainstorming 模式

适用于需求不明确的场景。

3.1 核心原则

通过自然的协作对话，将想法转化为完整的设计和规格说明。

关键原则：

• 一次一个问题 – 不要用多个问题压倒用户
• 优先多选题 – 比开放式问题更容易回答
• YAGNI 原则 – 从所有设计中移除不必要的功能
• 探索替代方案 – 在确定方案前总是提出 2-3 种方法
• 增量验证 – 分段展示设计，逐段验证
• 保持灵活 – 当某些内容不清楚时，回退并澄清

3.2 理解想法阶段

Step 1: 检查项目上下文

1. 查看项目文件和目录结构
2. 阅读项目文档（docs/）
3. 检查最近的提交记录
4. 了解现有的架构和技术栈

Step 2: 逐个问题澄清

一次只问一个问题来细化想法：
  - 优先使用多选题（提供 2-4 个选项）
  - 开放式问题也可以，但要明确具体
  - 如果一个主题需要更多探索，分解为多个问题
  - 专注理解：目的、约束、成功标准

问题示例：

多选题：
"这个功能的主要目标是什么？
a) 提升用户体验
b) 提高系统性能
c) 增加新功能
d) 修复现有问题"

开放式：
"这个功能的验收标准是什么？怎样算完成？"

探索性：
"你提到需要缓存，是因为性能问题还是为了离线支持？"

3.3 探索方案阶段

提出 2-3 种不同的方法，包含权衡分析。

方案展示格式：

我看到几种可能的实现方法：

**方案 A：[名称]（推荐）**

- 优点：[列出优点]
- 缺点：[列出缺点]
- 适用场景：[什么情况下最合适]

**方案 B：[名称]**

- 优点：[列出优点]
- 缺点：[列出缺点]
- 适用场景：[什么情况下最合适]

**方案 C：[名称]**

- 优点：[列出优点]
- 缺点：[列出缺点]
- 适用场景：[什么情况下最合适]

**我的推荐：** 方案 A，因为 [解释原因]

你倾向于哪种方案？或者有其他想法？

3.4 展示设计阶段

一旦理解了要构建什么，开始展示设计。

展示原则：

• 将设计分解为小段（200-300 字）
• 每段后询问是否正确
• 准备好在不清楚时回退和澄清

设计内容覆盖：

1. 架构概览
2. 核心组件和职责
3. 数据流和交互
4. 错误处理策略
5. 测试策略

展示格式：

## 架构设计

### 整体架构

[200-300 字描述整体架构]

这个方向看起来对吗？

---

### 核心组件

[200-300 字描述核心组件]

这些组件的划分合理吗？

---

[继续其他部分...]

3.5 保存设计文档

文件路径： docs/plans/001-feature-name.md（使用3位数字编号）

模板文件： ./plan-templates/combined-plan-template.md

**文档结构：**严格按模板文件生成，不要手写结构（必须包含状态管理模块）。

状态管理要求：

• 必须包含：整体进度、任务状态总览、执行记录
• 每个任务必须填写：状态、负责人、开始时间、完成时间、阻塞原因
• 初始状态统一为：待开始

3.6 后续步骤

设计文档验证完成后：

1. 使用 git 提交设计文档
2. 询问用户："准备好进入实现阶段了吗？"
3. 提供执行选项（见 Phase 4）

Phase 4: 提供执行选项

计划文档完成后，提供执行选择。

4.1 执行选项

计划已完成并保存到 `docs/plans/<filename>.md`。

你可以选择以下执行方式：

**选项 1：使用 project-workflow 执行**

- 适合：按计划逐步执行，需要人工审查
- 命令：`/project-workflow` 或告诉我"执行计划 <filename>"

**选项 2：使用 feature-dev 自动执行**

- 适合：复杂功能，需要自动探索和架构设计
- 命令：`/feature-dev` 或告诉我"使用 feature-dev 实现"

**选项 3：手动执行**

- 适合：你想自己实现，我可以在需要时提供帮助
- 随时告诉我你需要什么帮助

你希望如何执行？

4.2 与其他 skill 的集成

与 project-workflow 集成：

project-planning 产出计划 → project-workflow 执行计划

与 feature-dev 集成：

project-planning 产出设计 → feature-dev 自动实现

附录

A. 计划文件命名规范

docs/plans/
├── 001-user-authentication.md           # 用户认证功能（包含设计+实施）
├── 002-api-rate-limiting.md             # API 限流功能（包含设计+实施）
├── 003-payment-integration.md           # 支付集成（包含设计+实施）
└── 004-data-export.md                   # 数据导出（简单功能，只有实施步骤）

命名规则：

• 格式：001-feature-name.md（3位数字编号 + 功能名称）
• 编号从 001 开始，递增
• 功能名称使用小写字母和连字符
• 文件内包含创建日期元数据

文件内容根据复杂度：

• 复杂功能：包含完整的设计部分（需求、架构、方案对比）+ 详细实施步骤
• 简单功能：直接包含实施步骤（TDD 格式）

B. 何时使用哪种模式

使用 Brainstorming 模式：

• “我想添加一个功能，但不确定怎么做”
• “帮我设计 XXX 模块”
• “我有个想法，想和你讨论一下”
• 需求模糊，需要探索

使用 Writing Plans 模式：

• “为 XXX 功能编写实现计划”
• “我要实现 [具体需求]，帮我写详细步骤”
• 需求明确，技术方案已定
• 只需要详细的执行步骤

C. 最佳实践

Brainstorming 模式：

• 不要急于给出方案，先充分理解需求
• 总是提供多个方案供选择
• 使用图表和示例帮助理解
• 保持对话自然，不要太正式

Writing Plans 模式：

• 每个步骤必须可独立执行
• 提供完整的代码，不要用”添加验证”这种模糊描述
• 包含精确的命令和预期输出
• 遵循项目的代码风格和约定

通用原则：

• DRY（Don’t Repeat Yourself）
• YAGNI（You Aren’t Gonna Need It）
• TDD（Test-Driven Development）
• 频繁提交，小步前进