Ac Plan

Plan - 主线程规划 + Subagents 辅助调研

$ARGUMENTS

核心协议

• 语言协议：与工具交互用英语，与用户交互用中文
• 规划主权：最终方案选择、计划内容整合、.claude/plan/*.md 写入都由 Claude 主线程完成
• 按需使用 subagents：仅在任务跨模块、检索范围不清、可拆为多个独立调研子任务时，使用 Agent 工具启动 subagents 辅助调研或方案分析
• 只读协作：subagents 仅做检索、阅读、分析，不修改产品代码，不写计划文件
• 止损机制：当前阶段输出通过校验前，不进入下一阶段
• 仅规划：本命令允许读取上下文与写入 .claude/plan/* 计划文件，但禁止修改产品代码

规划约束

工作目录：

• {{WORKDIR}}：使用当前工作目录的绝对路径作为检索与计划输出根目录
• 如果用户通过 /add-dir 添加了多个工作区，先用 Glob/Grep 确定任务相关的工作区
• 如果无法确定，用 AskUserQuestion 询问用户选择目标工作区

subagents 使用条件：

• 适用：开放式代码库搜索、跨目录/跨模块摸排、需要并行比较多个实现路径
• 优先：Explore 用于只读检索与结构摸排，Plan 用于方案拆解与实施路线分析
• 不适用：已知文件路径、单文件小改动、上下文非常明确的简单任务

重要：

• 只允许生成和更新 .claude/plan/*.md 计划文件
• 不允许描述或执行任何第三方工具调用语法
• 不调用外部模型、后台任务、会话复用或额外 Bash 编排
• 已委托给 subagents 的检索或分析内容，主线程不要重复执行
• 最终计划必须由主线程统一收口，禁止直接转发子任务原始输出给用户

执行工作流

规划任务：$ARGUMENTS

🔍 Phase 1：需求增强与范围收敛

[模式：准备]

1. 分析 $ARGUMENTS 的意图、缺失信息、隐含假设
2. 补全为结构化需求：目标、技术约束、范围边界、验收标准
3. 用增强后的需求替代原始 $ARGUMENTS，作为后续阶段输入
4. 若需求仍有模糊空间，必须向用户提问澄清后再继续

🔎 Phase 2：上下文检索

[模式：研究]

2.1 直接检索（简单场景）

• 已知关键文件、符号或入口时，主线程直接读取相关文件
• 优先输出：入口文件 + 行号 + 关键符号名

2.2 subagents 并行调研（复杂场景按需启用）

当任务跨多个模块、搜索范围不明确或预计需要多轮检索时：

1. 使用 Agent 工具在同一轮并行启动多个 subagents
2. 典型拆分方式：
   • 代码路径调研：定位入口、核心调用链、关键文件
   • 依赖与影响面调研：识别上下游模块、配置、类型、接口边界
   • 方案分析：评估 2-3 种可行实现路径及其取舍
3. subagents 仅返回结论、证据和定位信息
4. 主线程收集结果后再进入下一阶段

2.3 完整性检查

• 必须获取相关类、函数、变量的必要定义与签名
• 若上下文不足，继续补充检索直到边界清晰
• 禁止基于假设直接输出计划

💡 Phase 3：主线程分析与生成计划

[模式：分析]

1. 合并主线程与 subagents 的检索结果
2. 优先选择最简单、改动最小、依赖最少的可行方案
3. 明确：实施步骤、关键文件、风险点、验证方式
4. 生成并写入 .claude/plan/<功能名>.md 实施计划：

## 📋 实施计划：<任务名称>

### 任务类型
- [ ] 前端
- [ ] 后端
- [ ] 全栈

### 技术方案
<主线程最终选定的方案>

### 实施步骤
1. <步骤 1> - 预期产物
2. <步骤 2> - 预期产物
...

### 关键文件
| 文件 | 操作 | 说明 |
|------|------|------|
| path/to/file.ts:L10-L50 | 修改 | 描述 |

### 风险与缓解
| 风险 | 缓解措施 |
|------|----------|

⛔ Phase 3 结束：计划交付（非执行）

/ac-plan 的职责到此结束，必须执行以下动作：

1. 创建并写入 .claude/plan/<功能名>.md

2. 向用户展示完整实施计划

3. 以加粗文本输出提示（必须使用实际保存的文件路径）：

   ---

   📋 计划已生成并保存至 .claude/plan/实际功能名.md

   请审查上述计划，您可以：

   • 🔧 修改计划：告诉我需要调整的部分，我会更新计划
   • ▶️ 执行计划：复制以下命令到新会话执行

   /ac-execute .claude/plan/实际功能名.md
   

   ---

   ⚠️ 注意：上面的 实际功能名.md 必须替换为你实际保存的文件名！**

4. 立即终止当前回复（Stop here. No more tool calls.）

⚠️ 绝对禁止：

• ❌ 问用户 "Y/N" 然后自动执行（执行是 /ac-execute 的职责）
• ❌ 对产品代码进行任何写操作
• ❌ 自动调用 /ac-execute 或任何实施动作
• ❌ 在用户未明确要求修改时继续触发实施类动作

计划保存

规划完成后，将计划保存至：

• 首次规划：.claude/plan/<功能名>.md
• 迭代版本：.claude/plan/<功能名>-v2.md、.claude/plan/<功能名>-v3.md...

计划文件写入应在向用户展示计划前完成。

计划修改流程

如果用户要求修改计划：

1. 根据用户反馈调整计划内容
2. 更新 .claude/plan/<功能名>.md 文件
3. 重新展示修改后的计划
4. 再次提示用户审查或执行

后续步骤

用户审查满意后，手动执行：

/ac-execute .claude/plan/<功能名>.md

关键规则

1. 仅规划不实施 – 本命令不执行任何代码变更
2. 主线程写计划 – 产物仅限主线程生成的 .claude/plan/*.md 计划文件
3. subagents 只做辅助调研 – 按需使用，不默认开启，不直接输出最终计划
4. 不问 Y/N – 只展示计划，让用户决定下一步
5. 禁止会话交接 – 计划中不得包含任何外部会话标识或要求会话交接的内容