name: deepen-plan description: 通过并行研究代理增强计划，为每个部分添加深度、最佳实践和实现细节

参数

[计划文件路径]

深化计划 - 强力增强模式

介绍

注意：当前年份是2026年。 在搜索最新文档和最佳实践时使用此信息。

此命令接收一个现有计划（来自 /workflows:plan）并使用并行研究代理增强每个部分。每个主要元素都有其专用的研究子代理来查找：

最佳实践和行业模式
性能优化
UI/UX改进（如果适用）
质量增强和边缘案例
实际实现示例

结果是深度接地、生产就绪的计划，具有具体实现细节。

计划文件

<plan_path> #$ARGUMENTS </plan_path>

如果上面的计划路径为空：

检查最近计划：ls -la docs/plans/
询问用户：“您想深化哪个计划？请提供路径（例如 docs/plans/2026-01-15-feat-my-feature-plan.md）。"

在获得有效计划文件路径之前不要继续。

主要任务

1. 解析和分析计划结构

<thinking> 首先，读取并解析计划以识别每个可以通过研究增强的主要部分。 </thinking>

读取计划文件并提取：

[ ] 概述/问题陈述
[ ] 建议解决方案部分
[ ] 技术方法/架构
[ ] 实现阶段/步骤
[ ] 代码示例和文件引用
[ ] 验收标准
[ ] 任何提到的UI/UX组件
[ ] 提到的技术/框架（Rails、React、Python、TypeScript等）
[ ] 领域区域（数据模型、API、UI、安全、性能等）

创建部分清单：

部分 1: [标题] - [研究内容的简要描述]
部分 2: [标题] - [研究内容的简要描述]
...

2. 发现并应用可用技能

<thinking> 动态发现所有可用技能并将其与计划部分匹配。不要假设技能存在 - 在运行时发现。 </thinking>

步骤1：从所有来源发现所有可用技能

# 1. 项目本地技能（最高优先级 - 项目特定）
ls .claude/skills/

# 2. 用户全局技能（~/.claude/）
ls ~/.claude/skills/

# 3. compound-engineering 插件技能
ls ~/.claude/plugins/cache/*/compound-engineering/*/skills/

# 4. 所有其他已安装插件 - 检查每个插件的技能
find ~/.claude/plugins/cache -type d -name "skills" 2>/dev/null

# 5. 同时检查 installed_plugins.json 获取所有插件位置
cat ~/.claude/plugins/installed_plugins.json

重要： 检查每个来源。不要假设 compound-engineering 是唯一插件。使用任何相关已安装插件的技能。

步骤2：对于每个发现的技能，读取其 SKILL.md 以了解功能

# 对于每个找到的技能目录，读取其文档
cat [skill-path]/SKILL.md

步骤3：将技能与计划内容匹配

对于每个发现的技能：

读取其 SKILL.md 描述
检查是否有计划部分匹配技能的领域
如果有匹配，生成子代理以应用该技能的知识

步骤4：为每个匹配技能生成子代理

关键：对于每个匹配的技能，生成单独的子代理并指示其使用该技能。

对于每个匹配技能：

任务 general-purpose: “您拥有位于 [skill-path] 的 [skill-name] 技能。

您的任务：将此技能应用于计划。

1. 读取技能：cat [skill-path]/SKILL.md
2. 完全遵循技能的指示
3. 将此技能应用于此内容：

[相关计划部分或完整计划]

4. 返回技能的完整输出

技能告诉您做什么 - 遵循它。完全执行技能。”

并行生成所有技能子代理：

每个匹配技能一个子代理
每个子代理读取并使用其分配的技能
所有同时运行
10、20、30个技能子代理没问题

每个子代理：

读取其技能的 SKILL.md
遵循技能的工作流程/指示
将技能应用于计划
返回技能产生的任何内容（代码、建议、模式、审查等）

示例生成：

任务 general-purpose: “使用位于 ~/.claude/plugins/.../dhh-rails-style 的 dhh-rails-style 技能。读取 SKILL.md 并将其应用于：[计划的Rails部分]”

任务 general-purpose: “使用位于 ~/.claude/plugins/.../frontend-design 的 frontend-design 技能。读取 SKILL.md 并将其应用于：[计划的UI部分]”

任务 general-purpose: “使用位于 ~/.claude/plugins/.../agent-native-architecture 的 agent-native-architecture 技能。读取 SKILL.md 并将其应用于：[计划的代理/工具部分]”

任务 general-purpose: “使用位于 ~/.claude/skills/security-patterns 的 security-patterns 技能。读取 SKILL.md 并将其应用于：[完整计划]”

技能子代理无限制。为每个可能相关的技能生成一个。

3. 发现并应用学习/解决方案

<thinking> 检查来自 /workflows:compound 的文档化学习。这些是存储为Markdown文件的已解决问题。为每个学习生成子代理以检查是否相关。 </thinking>

学习位置 - 检查这些确切文件夹：

docs/solutions/           <-- 主要：项目级学习（由 /workflows:compound 创建）
├── performance-issues/
│   └── *.md
├── debugging-patterns/
│   └── *.md
├── configuration-fixes/
│   └── *.md
├── integration-issues/
│   └── *.md
├── deployment-issues/
│   └── *.md
└── [other-categories]/
    └── *.md

步骤1：找到所有学习Markdown文件

运行这些命令获取每个学习文件：

# 主要位置 - 项目学习
find docs/solutions -name "*.md" -type f 2>/dev/null

# 如果 docs/solutions 不存在，检查备用位置：
find .claude/docs -name "*.md" -type f 2>/dev/null
find ~/.claude/docs -name "*.md" -type f 2>/dev/null

步骤2：读取每个学习的前言以过滤

每个学习文件都有YAML前言和元数据。读取每个文件的前约20行以获取：

---
title: “Briefs的N+1查询修复”
category: performance-issues
tags: [activerecord, n-plus-one, includes, eager-loading]
module: Briefs
symptom: “页面加载慢，日志中多个查询”
root_cause: “关联上缺少includes”
---

对于每个 .md 文件，快速扫描其前言：

# 读取每个学习的前20行（前言 + 摘要）
head -20 docs/solutions/**/*.md

步骤3：过滤 - 仅为可能相关的学习生成子代理

将每个学习的前言与计划比较：

tags: - 是否有标签匹配计划中的技术/模式？
category: - 此类别相关吗？（例如，如果计划仅为UI，跳过部署问题）
module: - 计划涉及此模块吗？
symptom: / root_cause: - 此问题可能发生在计划中吗？

跳过明显不适用的学习：

计划仅为前端 → 跳过 database-migrations/ 学习
计划为Python → 跳过 rails-specific/ 学习
计划无认证 → 跳过 authentication-issues/ 学习

为可能应用的学习生成子代理：

任何标签与计划技术重叠
与计划领域相同类别
相似模式或关注点

步骤4：为过滤后的学习生成子代理

对于每个通过过滤的学习：

任务 general-purpose: “
学习文件：[.md 文件的完整路径]

1. 完全读取此学习文件
2. 此学习文档化了一个先前解决的问题

检查此学习是否适用于此计划：

---
[完整计划内容]
---

如果相关：
- 具体解释如何应用
- 引用关键见解或解决方案
- 建议在哪里/如何纳入

如果深入分析后不相关：
- 说‘不适用：[原因]’
”

示例过滤：

# 找到15个学习文件，计划关于“Rails API缓存”

# 生成（可能相关）：
docs/solutions/performance-issues/n-plus-one-queries.md      # tags: [activerecord] ✓
docs/solutions/performance-issues/redis-cache-stampede.md    # tags: [caching, redis] ✓
docs/solutions/configuration-fixes/redis-connection-pool.md  # tags: [redis] ✓

# 跳过（明显不适用）：
docs/solutions/deployment-issues/heroku-memory-quota.md      # 不关于缓存
docs/solutions/frontend-issues/stimulus-race-condition.md    # 计划为API，非前端
docs/solutions/authentication-issues/jwt-expiry.md           # 计划无认证

为所有过滤后的学习并行生成子代理。

这些学习是机构知识 - 应用它们防止重复过去错误。

4. 启动每部分研究代理

<thinking> 对于计划中的每个主要部分，生成专用子代理以研究改进。使用Explore代理类型进行开放研究。 </thinking>

对于每个识别的部分，启动并行研究：

任务 Explore: “研究最佳实践、模式和实际示例：[部分主题]。
查找：
- 行业标准和约定
- 性能考虑
- 常见陷阱及如何避免
- 文档和教程
返回具体、可操作的建议。”

同时使用Context7 MCP获取框架文档：

对于计划中提到的任何技术/框架，查询Context7：

mcp__plugin_compound-engineering_context7__resolve-library-id: 查找[框架]的库ID
mcp__plugin_compound-engineering_context7__query-docs: 查询特定模式的文档

使用WebSearch获取当前最佳实践：

搜索计划主题的最新（2024-2026）文章、博客和文档。

5. 发现并运行所有审查代理

<thinking> 动态发现每个可用代理并全部运行对抗计划。不过滤、不跳过、不假设相关性。40+并行代理没问题。使用所有可用。 </thinking>

步骤1：从所有来源发现所有可用代理

# 1. 项目本地代理（最高优先级 - 项目特定）
find .claude/agents -name "*.md" 2>/dev/null

# 2. 用户全局代理（~/.claude/）
find ~/.claude/agents -name "*.md" 2>/dev/null

# 3. compound-engineering 插件代理（所有子目录）
find ~/.claude/plugins/cache/*/compound-engineering/*/agents -name "*.md" 2>/dev/null

# 4. 所有其他已安装插件 - 检查每个插件的代理
find ~/.claude/plugins/cache -path "*/agents/*.md" 2>/dev/null

# 5. 检查 installed_plugins.json 查找所有插件位置
cat ~/.claude/plugins/installed_plugins.json

# 6. 对于本地插件（isLocal: true），检查其源目录
# 解析 installed_plugins.json 并查找本地插件路径

重要： 检查每个来源。包括来自：

项目 .claude/agents/
用户的 ~/.claude/agents/
compound-engineering 插件（但跳过 workflow/ 代理 - 仅使用 review/, research/, design/, docs/）
所有其他已安装插件（agent-sdk-dev, frontend-design等）
任何本地插件

对于 compound-engineering 插件具体：

使用：agents/review/*（所有审查者）
使用：agents/research/*（所有研究者）
使用：agents/design/*（设计代理）
使用：agents/docs/*（文档代理）
跳过：agents/workflow/*（这些是工作流程协调器，非审查者）

步骤2：对于每个发现的代理，读取其描述

读取每个代理文件的前几行以了解其审查/分析内容。

步骤3：并行启动所有代理

对于每个发现的代理，并行启动一个任务：

任务 [agent-name]: “使用您的专业知识审查此计划。应用所有检查和模式。计划内容：[完整计划内容]”

关键规则：

不要按“相关性”过滤代理 - 全部运行
不要因为“可能不适用”而跳过代理 - 让它们决定
在单个消息中启动所有代理，使用多个任务工具调用
20、30、40个并行代理没问题 - 使用所有
每个代理可能捕捉到其他代理遗漏的内容
目标是最大覆盖，非效率

步骤4：同时发现并运行研究代理

研究代理（如 best-practices-researcher, framework-docs-researcher, git-history-analyzer, repo-research-analyst）也应针对相关计划部分运行。

6. 等待所有代理并综合一切

<thinking> 等待所有并行代理完成 - 技能、研究代理、审查代理、一切。然后将所有发现综合成一个全面的增强。 </thinking>

收集所有来源的输出：

基于技能的子代理 - 每个技能的完整输出（代码示例、模式、建议）
学习/解决方案子代理 - 来自 /workflows:compound 的相关文档化学习
研究代理 - 最佳实践、文档、实际示例
审查代理 - 来自每个审查者的所有反馈（架构、安全、性能、简洁性等）
Context7查询 - 框架文档和模式
网络搜索 - 当前最佳实践和文章

对于每个代理的发现，提取：

[ ] 具体建议（可操作项）
[ ] 代码模式和示例（复制粘贴就绪）
[ ] 要避免的反模式（警告）
[ ] 性能考虑（指标、基准）
[ ] 安全考虑（漏洞、缓解）
[ ] 发现的边缘案例（处理策略）
[ ] 文档链接（参考）
[ ] 技能特定模式（来自匹配技能）
[ ] 相关学习（适用的过去解决方案 - 防止重复错误）

去重和优先排序：

合并来自多个代理的相似建议
按影响优先排序（高价值改进优先）
标记冲突建议供人工审查
按计划部分分组

7. 增强计划部分

<thinking> 将研究发现合并回计划，在不更改原始结构的情况下添加深度。 </thinking>

每个部分的增强格式：

## [原始部分标题]

[原始内容保留]

### 研究洞察

**最佳实践：**
- [具体建议 1]
- [具体建议 2]

**性能考虑：**
- [优化机会]
- [目标基准或指标]

**实现细节：**
```[语言]
// 来自研究的具体代码示例

边缘案例：

[边缘案例 1 及处理方法]
[边缘案例 2 及处理方法]

参考：

[文档URL 1]
[文档URL 2]


### 8. 添加增强摘要

在计划顶部添加摘要部分：

```markdown
## 增强摘要

**深化于：** [日期]
**增强部分：** [数量]
**使用的研究代理：** [列表]

### 关键改进
1. [主要改进 1]
2. [主要改进 2]
3. [主要改进 3]

### 发现的新考虑
- [重要发现 1]
- [重要发现 2]

9. 更新计划文件

写入增强计划：

保留原始文件名
如果用户偏好新文件，添加 -deepened 后缀
更新任何时间戳或元数据

输出格式

更新计划文件在原位（或如果用户请求单独文件，在 -plan 后附加 -deepened，例如 2026-01-15-feat-auth-plan-deepened.md）。

质量检查

最终确定前：

[ ] 所有原始内容保留
[ ] 研究洞察清晰标记和归因
[ ] 代码示例语法正确
[ ] 链接有效且相关
[ ] 部分之间无矛盾
[ ] 增强摘要准确反映更改

增强后选项

写入增强计划后，使用 AskUserQuestion工具 呈现这些选项：

问题： “计划已在 [plan_path] 深化。您想接下来做什么？”

选项：

查看差异 - 显示添加/更改的内容
运行 /plan_review - 获取审查者对增强计划的反馈
开始 /workflows:work - 开始实现此增强计划
进一步深化 - 在特定部分运行另一轮研究
还原 - 恢复原始计划（如果备份存在）

基于选择：

查看差异 → 运行 git diff [plan_path] 或显示前/后
/plan_review → 使用计划文件路径调用 /plan_review 命令
/workflows:work → 使用计划文件路径调用 /workflows:work 命令
进一步深化 → 询问哪些部分需要更多研究，然后重新运行那些代理
还原 → 从git或备份恢复

示例增强

之前（来自 /workflows:plan）：

## 技术方法

使用React Query进行数据获取，带乐观更新。

之后（来自 /workflows:deepen-plan）：

## 技术方法

使用React Query进行数据获取，带乐观更新。

### 研究洞察

**最佳实践：**
- 基于数据新鲜度要求配置 `staleTime` 和 `cacheTime`
- 使用 `queryKey` 工厂以一致缓存失效
- 在查询依赖组件周围实现错误边界

**性能考虑：**
- 启用 `refetchOnWindowFocus: false` 以减少稳定数据的不必要请求
- 使用 `select` 选项在查询级别转换和记忆数据
- 考虑 `placeholderData` 以即时感知加载

**实现细节：**
```typescript
// 推荐查询配置
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000, // 5分钟
      retry: 2,
      refetchOnWindowFocus: false,
    },
  },
});

边缘案例：

使用 cancelQueries 处理组件卸载时的竞态条件
为瞬时网络故障实现重试逻辑
考虑使用 persistQueryClient 的离线支持

参考：


永远不编码！仅研究和增强计划。