name: 计划实施 description: 在编码前创建结构化的实现计划。用于分解复杂功能、重构或系统更改时。验证需求，分析代码库影响，并生成具有已识别依赖和风险的可执行任务分解。

计划实施

何时使用

在实施前创建结构化方法
将复杂工作分解为步骤
为新功能设计架构
规划重构或系统更改
在重大更改前分析影响

核心步骤

1. 澄清需求（如果模糊）

提出发现性问题（最多5-7个）：

快乐路径： 逐步描述成功场景
边缘情况： 空状态、无效输入、错误、大型数据集？
范围边界： 明确哪些不在范围内？
性能： 即时（<100毫秒）、快速（<1秒）或最终（加载中）？
集成： 与现有功能、API、认证的交互？

功能特定问题：

认证： 凭证方法、会话持续时间、失败处理？
CRUD： 验证规则、并发编辑、删除行为？
搜索： 范围、匹配类型、时机（实时/提交）？
实时： 更新机制（轮询/WebSocket）、频率、离线？

生成带有置信水平的推断：

[INFER-HIGH]: JWT在httpOnly cookies中（安全最佳实践）
[INFER-MEDIUM]: 去抖动搜索300毫秒（平衡用户体验和性能）
[INFER-LOW]: 每页最多100个结果（防止UI过载）

如果需求不明确，在继续前获得批准。

2. 调查阶段（关键）

首先阅读项目文档：

docs/product-requirements.md - 项目目标、现有功能（F-##）
docs/feature-spec/F-##-*.md - 技术细节
docs/system-design.md - 架构模式
docs/api-contracts.yaml - API标准
docs/design-spec.md - UI模式

调查清单：

[ ] 识别所有受影响文件（完成影响分析）
[ ] 理解当前系统架构
[ ] 映射所有依赖和集成点
[ ] 记录现有模式和约定
[ ] 审查数据模型和模式
[ ] 追踪当前数据流
[ ] 找到所有调用站点（特别是重构时）
[ ] 评估测试影响
[ ] 识别破坏性更改

调查方法（根据范围选择）：

小/包含功能： 使用直接工具（Grep、Glob、Read）进行聚焦分析。

大/复杂更改或重构： 委托给Explore代理进行并行全面影响分析：

在代码库中找到所有受影响文件
识别每个使用、调用站点和依赖
映射集成点和数据流
发现要遵循的现有模式
识别破坏性更改和连锁效应

并行调查模式：

模式1：全栈功能/重构

代理1：后端分析（服务、API、模型、调用站点、集成）
代理2：前端分析（组件、状态、API客户端、依赖）
代理3：数据层（模式、查询、迁移、完整性）

模式2：架构 + 集成

代理1：当前系统（组织、堆栈、模式、边界）
代理2：集成需求（外部API、认证、数据库、库）

模式3：单一域（包含功能）

代理1：完整域分析（所有文件、调用站点、依赖、导入、测试、配置）

3. 创建实施计划

将计划写入 docs/plans/[feature-slug]/plan.md

使用模板结构：

小：~/.claude/file-templates/plan.quick.template.md
中：~/.claude/file-templates/plan.template.md
大：~/.claude/file-templates/plan.comprehensive.template.md

计划模板结构：

# 实施计划：[功能名称]

## 概述
[简要描述我们正在构建什么以及为什么]

## 需求摘要
[澄清阶段的关键需求]

## 调查工件
[链接代理响应或总结发现]

## 任务

### 任务1：[名称]
**什么：** [需要做什么]
**文件：** [要创建/修改的文件]
**依赖：** 无 / 需要任务X

### 任务2：[名称]
**什么：** [需要做什么]
**文件：** [要创建/修改的文件]
**依赖：** 需要任务1

## 并行机会
[识别独立任务组]

## 集成点
- [外部系统或API]
- [交互的现有功能]

## 测试策略
- [关键测试场景]
- [覆盖要求]

## 风险
- [潜在问题或未知]
- [破坏性更改]

## 关键决策
- [重要技术决策及推理]

计划大小：3-6个主要任务（将复杂工作分解为可管理块）

识别并行化：

## 批次1（并行 - 无共享依赖）
- 任务1：后端API端点
- 任务2：前端组件
- 任务3：数据库迁移

## 批次2（顺序 - 依赖批次1）
- 任务4：集成层
- 任务5：测试

除非有明显好处，否则默认顺序执行。

4. 链接计划到项目文档（如果适用）

使用可用命令更新项目文档：

实施前：

验证当前文档状态
如果计划引入新功能，则添加（创建F-## ID、条目）
如果计划更改范围、指标或风险，则更新需求

实施后：

添加链接到功能的用户故事
添加新API端点
如果添加了UI组件或模式，则更新设计

文档范围：

docs/product-requirements.yaml
docs/feature-specs/F-##-[slug].yaml
docs/user-stories/US-###-[slug].yaml
docs/api-contracts.yaml
docs/system-design.yaml
docs/data-plan.yaml
docs/design-spec.yaml

5. 呈现计划以获得批准

关键任务（3-6项）
主要集成点
任何破坏性更改
并行机会

在实施前获得明确批准。

按类别调查清单

对于新功能：

[ ] 阅读现有功能规范以了解模式
[ ] 检查系统设计以获取架构指导
[ ] 审查API合同以了解命名约定
[ ] 检查代码库中的类似功能
[ ] 识别所有受影响域

对于重构：

[ ] 找到所有导入/使用代码的文件
[ ] 识别所有调用站点（不仅仅是明显的）
[ ] 定位所有测试
[ ] 检查配置文件
[ ] 找到文档引用
[ ] 识别连锁效应

对于集成：

[ ] 审查现有集成模式
[ ] 检查认证/授权方法
[ ] 理解错误处理约定
[ ] 识别共享实用程序
[ ] 映射外部API依赖

常见模式

快速计划（小更改）

# 计划：[功能名称]

## 目标
[我们正在构建什么以及为什么]

## 任务
1. [任务] - [文件] - [依赖]
2. [任务] - [文件] - [依赖]
3. [任务] - [文件] - [依赖]

## 关键决策
- [重要技术决策及推理]

## 风险
- [潜在问题]

调查工具

直接调查：

Read - 检查现有代码和文档
Grep - 查找所有使用、导入、调用站点
Glob - 按模式查找文件

全面调查（重构、大功能）：

# 查找所有导入
grep -r "import.*ComponentName" --include="*.tsx"

# 查找所有使用
grep -r "ComponentName" --include="*.ts"

# 查找测试
grep -r "describe.*ComponentName" --include="*.test.ts"

对于并行分析：

委托Explore代理进行模式发现
从agent-responses/目录监控代理响应
在最终计划中链接调查工件

示例：计划新API功能

步骤1：澄清

快乐路径：用户创建X，接收Y响应
边缘情况：无效输入、重复键、并发请求
性能：响应时间<200毫秒
集成：需要认证、更新缓存

步骤2：调查

阅读docs/api-contracts.yaml以了解命名/结构模式
搜索类似端点（例如，CRUD模式）
找到认证中间件使用
检查缓存失效模式
识别所有受影响服务

步骤3：计划

任务1：将API模式添加到合同
任务2：实现控制器/处理程序
任务3：添加服务层逻辑
任务4：实现持久化
任务5：添加缓存失效
任务6：编写测试

步骤4：批准

与利益相关者分享计划，获得签署。

步骤5：移交

将计划+调查结果传递给实施代理。

关键原则

不留任何假设。 彻底调查是强制性的。
默认基于代理的影响分析 用于重构和跨切割更改。
使用直接工具处理小、包含功能 以保持高效。
破坏性更改必须早期识别 并清晰沟通。
计划启用并行执行 当依赖清晰时。
批准门防止返工。 在实施前始终获得签署。