Appearance
Compound 详细指南
概述
Compound 是 Spec-First 工作流的第五步，目标是提取可复用知识。
输入： 评审通过的产物 输出： 知识文档（docs/solutions/<category>/<filename>.md）+ 资产迁移
通过这个阶段，你将把解决问题的经验沉淀为可复用的知识，避免重复踩坑。
操作步骤
步骤 1: 启动 Compound
在项目目录中运行：
bash
/spec:compoundAI 会启动并行研究，提取知识。
步骤 2: 并行研究（Phase 1）
Compound 启动三个子代理并行工作：
| 子代理 | 职责 |
|---|---|
| Context Analyzer | 分类问题类型、生成 YAML 元数据 |
| Solution Extractor | 提取根因、解决方案、预防策略 |
| Related Docs Finder | 搜索相关文档、评估重叠度 |
步骤 3: 提取问题根因
回顾整个过程，总结：
- 遇到了什么问题
- 问题的根本原因是什么
- 为什么会出现这个问题
步骤 4: 记录解决方案
记录如何解决问题：
- 采用了什么方案
- 为什么选择这个方案
- 方案的优缺点
步骤 5: 提炼最佳实践
从经验中提炼：
- 哪些做法值得推广
- 哪些错误应该避免
- 有哪些可复用的模式
步骤 6: 迁移可复用资产
将可复用的内容迁移到项目知识库：
- 代码模板
- 配置示例
- 检查清单
步骤 7: 组装文档（Phase 2）
三个子代理的结果汇总后，组装成最终的解决方案文档，写入 docs/solutions/<category>/。
最佳实践
- ✅ 聚焦根因 - 深挖问题本质，而非表面现象
- ✅ 具体可操作 - 提供可直接使用的模板和示例
- ✅ 简洁明了 - 用最少的文字表达核心要点
- ✅ 场景化 - 说明在什么情况下适用
- ✅ 持续更新 - 随着理解加深不断完善
常见错误
- ❌ 流水账记录 → ✅ 提炼核心经验和教训
- ❌ 过于抽象 → ✅ 提供具体示例和模板
- ❌ 只记录成功 → ✅ 失败经验同样宝贵
- ❌ 不分类整理 → ✅ 按主题组织知识
- ❌ 写完就忘 → ✅ 定期回顾和更新
示例
示例 1: OAuth 登录知识沉淀
问题： OAuth 回调 URL 配置错误导致登录失败
根因： 开发环境和生产环境的域名不同，但使用了硬编码的回调 URL
解决方案： 使用环境变量配置回调 URL
javascript
// ✅ 正确做法
callbackURL: process.env.OAUTH_CALLBACK_URL
// ❌ 错误做法
callbackURL: 'http://localhost:3000/auth/callback'最佳实践：
- 所有环境相关配置使用环境变量
- 在 README 中说明必需的环境变量
- 提供
.env.example模板
模板
markdown
# 知识文档：[主题]
## 问题
[遇到了什么问题]
## 根因
[问题的根本原因]
## 解决方案
[如何解决]
## 最佳实践
- [推荐做法]
## 可复用资产
[代码模板、配置示例等]
## 适用场景
[什么情况下可以使用]判定标准
完成 Compound 后，检查以下条件：
- [ ] 问题根因已分析
- [ ] 解决方案已记录
- [ ] 最佳实践已提炼
- [ ] 可复用资产已迁移
- [ ] 知识文档已生成
全部满足后，本次工作流结束。
Compound Refresh — 知识维护
已沉淀的知识需要定期维护。使用 /spec:compound-refresh 处理过时的文档。
bash
/spec:compound-refresh "搜索范围"维护动作
| 结果 | 含义 | 动作 |
|---|---|---|
| Keep | 仍然准确有用 | 报告已审查，不修改 |
| Update | 核心方案正确但引用过时 | 原地更新 |
| Consolidate | 多个文档重叠严重 | 合并为规范文档 |
| Replace | 有更好的替代方案 | 创建替代文档 |
| Delete | 不再适用或有用 | 删除（git 保留历史） |
触发场景
- 重大重构后，相关文档可能过时
- 依赖升级后，解决方案可能不再适用
- 多个文档描述同一问题，需要合并
- 检索到的文档感觉与当前代码不匹配
两种模式
| 模式 | 行为 |
|---|---|
| Interactive（默认） | 遇到歧义时询问用户 |
| Autofix | 无交互，自动处理明确的维护动作 |
Compact-Safe 模式
当上下文空间紧张时，Compound 自动切换为紧凑模式：
- 跳过并行子代理 — 主代理一次性完成所有工作
- 生成精简文档 — 包含必要但较少的内容
- 跳过专门代理审查 — 不触发 Phase 3 增强
下一步
回到 工作流概览 开始下一个迭代。