场景化实践指南
AI Agent 实践指南 项目管理
针对不同项目类型的具体实践策略，包括一次性项目、旧项目迭代、多人协作项目的最佳实践
一次性项目的最佳实践
场景定义
一次性项目通常具有以下特征：
- 开发周期短（1-4 周）
- 交付后不需要长期维护
- 目的多为验证想法、制作原型或完成临时任务
- 示例：POC 验证、营销活动页面、数据迁移脚本
模式选择：Superpowers 为主
对于一次性项目，Superpowers 是更合适的选择。
理由：
- 学习成本敏感：短期项目无法分摊 CE 的学习投入
- 知识价值有限：项目结束后知识库无用武之地
- 速度优先：Superpowers 的上手速度更快
优化策略：为可能的延续做准备
虽然是”一次性”项目，但现实中很多”临时项目”最终会演变为长期项目。建议采取以下策略：
策略一：关键经验手动记录
即使使用 Superpowers，也可以在关键节点手动记录经验：
# project-notes.md
## 2026-03-29: API 集成踩坑记录
- 问题：第三方 API 的 rate limiting 比文档描述的更严格
- 解决：实现指数退避重试机制
- 代码：见 src/utils/api-retry.ts
## 2026-03-30: 性能优化
- 发现：列表页渲染 1000+ 条数据卡顿
- 解决：虚拟滚动 + 分页加载
- 参考：react-window 库好处：
- 如果项目延续，这些笔记可以快速迁移到 CE 的知识库
- 即使不延续，也能培养经验记录的习惯
策略二：模块化代码结构
使用 Superpowers 时，也要有意识地保持代码模块化：
src/
├── components/ # 可复用组件
├── hooks/ # 自定义 hooks
├── utils/ # 工具函数
├── services/ # API 服务层
└── features/ # 功能模块
├── auth/ # 认证功能
├── dashboard/ # 仪表盘功能
└── ...好处：
- 便于未来迁移到 CE 时进行模块化分析
- 每个模块可以成为独立的 learning 单元
策略三：文档前置
Superpowers 的 plan 阶段生成的文档，可以保留下来：
# 项目根目录
docs/
├── plans/ # 保存所有 plan
├── reviews/ # 保存关键 review 结果
└── decisions/ # 记录关键决策好处：
- 项目延续时，这些文档可以直接喂给 CE 的 research agents
- 形成项目历史知识的基础
决策树：何时从一次性转向长期维护
flowchart TD
A[一次性项目进行中] --> B{是否需要新增功能?}
B -->|否| C{是否发现重大问题?}
B -->|是| D[项目可能延续]
C -->|否| E[保持 Superpowers]
C -->|是| D
D --> F{预计还要维护多久?}
F -->|< 1 月| G[继续使用 Superpowers<br/>手动记录关键经验]
F -->|> 1 月| H[考虑迁移到 CE]
H --> I[评估迁移成本]
I --> J{迁移成本 < 收益?}
J -->|是| K[迁移到 CE<br/>将手动笔记转为知识库]
J -->|否| G旧项目迭代的最佳实践
场景定义
旧项目（Legacy Project）通常具有以下特征：
- 已有 6 个月以上历史
- 代码库较大（>10k 行）
- 存在技术债务和历史遗留问题
- 文档可能不完整或过时
- 需要持续迭代但不允许大规模重构
模式选择：Compound Engineering 显著优势
旧项目场景是 CE 的甜蜜点，Superpowers 在此场景下劣势明显。
CE 优势：
- 历史知识学习：CE 的 research agents 可以扫描 codebase，学习项目的历史模式和约束
- 避免重复踩坑：历史踩过的坑一旦被 compound，后续工作自动规避
- 渐进式改进：通过知识积累，逐步改善代码质量，无需大规模重构
实施路线图
第一阶段：知识库建设（第 1-2 周）
目标：建立初始知识库，覆盖项目的主要模式和技术栈
步骤：
-
项目结构分析
# 使用 CE 分析项目结构 /ce:plan "分析项目架构，生成项目结构文档" -
关键模式识别
- 识别项目中反复出现的 patterns
- 记录项目特有的 conventions
- 标记技术债务区域
-
历史问题整理
- 查看 git history 中的 bug fixes
- 整理经常出问题的模块
- 记录已知的 edge cases
输出：
docs/solutions/
├── 000-project-overview.md # 项目整体架构
├── 001-code-conventions.md # 代码规范
├── 002-common-patterns.md # 常见模式
├── 003-known-issues.md # 已知问题
└── 010-specific-feature-xxx.md # 具体功能的问题记录第二阶段：增量迭代（第 3-8 周）
目标：在日常迭代中积累知识，形成复利效应
工作流程：
flowchart TD
A[接收新需求] --> B[/ce:plan]
B --> C[Learnings Researcher<br/>搜索相关历史知识]
C --> D{发现相关 Learning?}
D -->|是| E[Plan 包含<br/>历史坑点提醒]
D -->|否| F[标准 Plan]
E --> G[/ce:work]
F --> G
G --> H[/ce:review]
H --> I{遇到问题?}
I -->|是| J[Debug 解决]
J --> K[/ce:compound]
K --> L[写入新知识<br/>供未来使用]
I -->|否| M[完成]
L --> M关键实践：
-
每次 bug fix 都 compound
- 即使是”小”bug，如果涉及项目特有的 edge case，都值得记录
- 示例：“React 18 StrictMode 下的 useEffect 双重执行问题”
-
定期 review 知识库
- 每周花 30 分钟 review 本周新增的文档
- 确保分类正确、标签完整
- 合并重复或相似的文档
-
更新过时知识
- 技术栈升级时，更新相关文档
- 标记 deprecated 的 patterns
- 添加迁移指南
第三阶段：知识库优化（第 9-12 周）
目标：优化知识库结构，提升检索效率
优化方向：
-
分类体系完善
docs/solutions/ ├── architecture/ # 架构决策 ├── patterns/ # 代码模式 ├── pitfalls/ # 常见坑点 ├── integrations/ # 第三方集成 ├── performance/ # 性能优化 └── security/ # 安全问题 -
标签体系标准化
--- category: performance tags: [react, rendering, optimization] components: [dashboard, data-table] severity: P2 status: active # active | deprecated | resolved related: - 015-react-memo - 023-virtual-list --- -
搜索优化
- 确保文档标题和正文包含关键词
- 使用标准化的术语
- 添加同义词映射
常见挑战与解决方案
挑战一：历史代码质量差，如何开始？
问题：旧项目可能缺乏测试、文档混乱、代码风格不一致。
解决方案：
flowchart LR
A[开始 CE] --> B[先做代码分析]
B --> C[识别关键模块]
C --> D[优先记录关键模块]
D --> E[逐步扩展覆盖范围]
style B fill:#f96
style C fill:#f96- 不必一次性覆盖全部：先聚焦最活跃、最容易出问题的模块
- 记录”坏”的例子：不仅记录正确的做法，也记录项目中存在的”坏实践”及其原因
- 渐进式改进：每次修改代码时，先 compound 当前状态，再写改进后的方案
挑战二：团队对知识库维护不积极
问题：开发者只关注写代码，不愿意花时间记录。
解决方案：
-
展示价值
- 每周分享”本周 CE 帮我们避免的坑”
- 量化节省时间：“本周通过 learnings-researcher 少踩了 3 个坑，节省约 2 小时”
-
降低门槛
- 提供文档模板
- 使用语音转文字快速记录
- 允许先记录要点，后续再完善
-
激励机制
- 将知识库贡献纳入绩效评估
- 设立”最佳 Learning”奖励
- 在团队会议上展示优秀的 compound 文档
挑战三：知识库过于庞大，检索困难
问题：使用数月后，docs/solutions/ 可能有数百篇文档，难以快速找到需要的信息。
解决方案：
-
实施 “compound janitor”
每天 end of day： 1. 扫描当天所有 session 的 git diff 2. AI 判断是否值得 compound 3. 筛选后批量执行 compound 4. 合并相似文档 5. 标记过时文档 -
增强搜索能力
- 添加更多标签和元数据
- 实现语义搜索（使用 embedding）
- 维护”热点问题”列表
-
分层知识库
docs/ ├── solutions/ # 具体问题解决方案 ├── patterns/ # 通用模式（更高抽象） ├── guides/ # 操作指南 └── references/ # 参考资料
多人协作项目的模式选择
场景定义
多人协作项目通常具有以下特征：
- 团队规模 3 人以上
- 需要代码审查和协作流程
- 知识需要在团队内共享
- 可能有多人同时处理相关功能
核心问题：知识孤岛
在传统开发中，多人协作面临的最大挑战是 知识孤岛：
flowchart TB
subgraph "开发者 A"
A1[解决问题 X] --> A2[经验在 A 脑中]
end
subgraph "开发者 B"
B1[遇到类似问题 X'] --> B2[不知道 A 的解法]
B2 --> B3[重新踩坑]
end
subgraph "开发者 C"
C1[遇到相关问题] --> C2[重复踩坑]
end
A2 -.->|知识未共享| B2
A2 -.->|知识未共享| C2
style B3 fill:#f96
style C2 fill:#f96传统解决方案的局限：
- 文档：更新不及时，容易被忽视
- Code Review：依赖 reviewer 的注意力，难以覆盖所有场景
- 站会分享：信息密度低，难以系统传递
CE 的解决方案：共享知识库
CE 通过 /ce:compound 创建的 docs/solutions/ 本质上是一个 团队的共享外接大脑：
flowchart TB
subgraph "共享知识库"
K[docs/solutions/]
end
subgraph "开发者 A"
A1[解决问题 X] --> A2[/ce:compound]
A2 --> K
end
subgraph "开发者 B"
B1[遇到类似问题] --> B2[/ce:plan]
B2 --> B3[Learnings Researcher]
B3 --> K
K --> B4[自动获得 A 的经验]
B4 --> B5[避免踩坑]
end
subgraph "开发者 C"
C1[遇到问题] --> C2[/ce:plan]
C2 --> C3[自动搜索知识库]
C3 --> K
K --> C4[获得 A 和 B 的经验]
end
style K fill:#9f6
style B5 fill:#9f6
style C4 fill:#9f6团队协作最佳实践
实践一：知识库作为团队标准
将 CE 知识库纳入团队工作流程：
-
Onboarding 流程
新成员加入： 1. 阅读 docs/solutions/README.md 2. 了解项目常见问题和模式 3. 了解如何编写和更新 learnings -
PR 检查清单
## PR 提交前检查 - [ ] 代码通过 /ce:review - [ ] 新增 learnings 已写入 docs/solutions/ - [ ] 相关文档已更新 -
定期知识 Review
每周团队会议： - 分享本周新增的重要 learnings - 讨论知识库的组织改进 - 识别需要进一步深化的主题
实践二：权限与质量控制
知识库的治理机制：
flowchart TD
A[提交 learning] --> B{自动检查}
B -->|格式正确| C[进入审核队列]
B -->|格式错误| D[返回修改]
C --> E[Senior Dev Review]
E -->|通过| F[合并到知识库]
E -->|需修改| G[反馈修改意见]
G --> D
F --> H[通知团队]
H --> I[更新索引]实施建议：
-
分级权限
- 所有人：提交 learnings
- Senior devs：审核和合并
- Tech lead：知识库结构调整
-
质量标准
# 必须包含 required_fields: - problem: "清晰的问题描述" - solution: "具体的解决方案" - tags: ["至少一个标签"] # 推荐包含 recommended_fields: - what_didnt_work: "避免后人重复尝试" - prevention: "如何预防" - components: "涉及的模块" -
自动化检查
# CI 流程中添加 - name: Validate Learnings run: | python scripts/validate_learnings.py # 检查 YAML frontmatter # 检查必填字段 # 检查链接有效性
实践三：知识库与代码库同步
避免知识过时：
- 版本关联
--- category: api-integration
tags: [stripe, payment] version: “2.1.0” # 关联代码版本 related_files: - src/services/stripe.ts - src/hooks/usePayment.ts
2. **代码变更触发审查**
```bash
# Git hook
pre-commit:
- 检查修改的文件是否有相关 learnings
- 提示是否需要更新知识库- 定期同步检查
每月任务： - 检查 learnings 中引用的代码是否仍然存在 - 标记或更新过时的文档 - 统计知识库覆盖率
团队规模适配
小团队（3-5 人）
特点：沟通相对容易，但知识传递仍可能遗漏
推荐策略：
- ✅ 使用 CE，建立共享知识库
- ✅ 宽松的审核流程（1 人审核即可）
- ✅ 鼓励所有人积极贡献 learnings
中型团队（6-15 人）
特点：开始出现信息孤岛，需要更规范的知识管理
推荐策略：
- ✅ 必须使用 CE，知识库是必需的
- ✅ 建立专门的文档审核 rotation
- ✅ 定期进行知识库清理和重构
- ✅ 考虑引入 “compound janitor” 自动化
大型团队（15+ 人）
特点：多子团队，知识管理复杂度显著增加
推荐策略：
- ✅ CE 配合更严格的知识治理
- ✅ 按子团队/模块划分子知识库
- ✅ 设立专门的 Developer Experience 角色
- ✅ 建立知识库 SLA（例如：新问题 24 小时内要有 learning）
- ✅ 定期举办 “Learning Share” 会议
混合模式策略
对于同时使用 Superpowers 和 CE 的团队：
flowchart TD
subgraph "策略框架"
A[项目/任务分类] --> B{项目类型}
B -->|探索性/短期| C[Superpowers<br/>快速灵活]
B -->|生产/长期| D[CE<br/>知识积累]
C --> E[个人工作区]
D --> F[团队协作区]
E --> G{产生有价值经验?}
G -->|是| H[迁移到 CE<br/>知识库]
G -->|否| I[结束]
F --> J[团队共享知识]
end实施建议：
-
明确边界
- Superpowers：用于探索、原型、个人实验
- CE：用于生产代码、团队协作、长期维护
-
知识迁移机制
- 每周 review Superpowers session，筛选有价值的经验
- 手动或通过脚本迁移到 CE 知识库
-
工具链统一
- 即使使用不同模式，也保持相同的代码规范和目录结构
- 便于未来统一迁移
混合模式实践：结合两种模式的优势
理论基础
实际上，Superpowers 和 CE 并不是非此即彼的关系，而是可以 互补使用。
flowchart TB
subgraph "Superpowers 优势领域"
S1[快速原型]
S2[探索性开发]
S3[个人任务]
S4[跨工具兼容]
end
subgraph "CE 优势领域"
C1[生产开发]
C2[团队协作]
C3[知识积累]
C4[质量保证]
end
subgraph "结合使用"
A[项目启动] --> B{阶段判断}
B -->|探索| S1
B -->|生产| C1
S1 --> C{价值验证?}
C -->|是| C1
C -->|否| D[结束]
S3 --> E{产生知识?}
E -->|是| F[导入 CE 知识库]
E -->|否| G[保持独立]
end实践场景一：探索 → 生产的无缝切换
场景：一个新项目从概念验证到生产上线
阶段一：探索（Superpowers）
Week 1-2: POC 验证
- 使用 Superpowers 快速尝试不同方案
- 快速迭代，不拘泥于代码质量
- 目标是验证核心假设阶段二：评估
Week 3: 决策点
- POC 是否成功？
- 是否值得投入生产开发？
- 如果继续，迁移到 CE阶段三：生产（CE）
Week 4+: 生产开发
- 迁移到 CE
- 将 POC 阶段的经验整理成初始知识库
- 开始系统化积累知识迁移要点：
-
经验迁移
# 手动整理 POC 阶段的关键经验 /ce:compound "整理 POC 阶段遇到的 API 限制和解决方案" -
代码重构
- 利用 CE 的 review 功能，系统性地重构 POC 代码
- 记录重构过程中的最佳实践
-
知识库初始化
docs/solutions/ ├── 000-poc-lessons.md # POC 阶段的经验总结 ├── 001-tech-stack.md # 技术栈选型理由 └── 002-architecture.md # 架构决策记录
实践场景二：个人探索 + 团队共享
场景：个人使用 Superpowers 进行技术探索，有价值的经验分享给团队
工作流程：
sequenceDiagram
participant Dev as 开发者
participant SP as Superpowers
participant Filter as 价值筛选
participant CE as Compound Engineering
participant Team as 团队知识库
Dev->>SP: 技术探索
SP-->>Dev: 实验结果
Dev->>Filter: 评估价值
Filter->>Filter: 是否可复用？<br/>是否节省团队时间？
alt 有价值
Filter->>CE: 整理成 learning
CE->>CE: /ce:compound
CE->>Team: 写入知识库
Team-->>Dev: 通知团队
else 无价值
Filter->>Dev: 个人保留
end价值判断标准：
- ✅ 值得分享：解决了常见问题的通用方案、发现了重要的 edge case、优化了性能瓶颈
- ❌ 不必分享：特定项目的业务逻辑、一次性的 workaround、过于特定的环境配置
实践场景三：核心模块 CE + 周边模块 Superpowers
场景：项目中核心模块需要高质量保障，周边模块快速迭代
架构示例：
project/
├── core/ # 核心模块 - 使用 CE
│ ├── payment/ # 支付系统
│ ├── auth/ # 认证系统
│ └── data-access/ # 数据访问层
│
├── features/ # 业务功能 - 使用 Superpowers
│ ├── marketing-page/ # 营销页面
│ ├── admin-dashboard/ # 管理后台
│ └── reporting/ # 报表功能
│
└── experiments/ # 实验性功能 - 使用 Superpowers
└── new-feature-x/实施要点：
- 明确边界：哪些模块用 CE，哪些用 Superpowers，团队内达成共识
- 接口契约：核心模块提供清晰的 API，周边模块通过接口调用
- 知识流动：核心模块的经验通过 CE 知识库沉淀，周边模块从知识库受益
实践场景四：团队分层使用
场景：团队中有不同经验水平的成员
分层策略：
flowchart TB
subgraph "初级开发者"
J1[使用 Superpowers<br/>熟悉流程]
J2[学习团队知识库]
J3[在指导下使用 CE]
end
subgraph "中级开发者"
M1[主要使用 CE<br/>日常开发]
M2[贡献知识库]
M3[偶尔 Superpowers<br/>快速任务]
end
subgraph "高级开发者"
S1[深度使用 CE<br/>复杂任务]
S2[维护知识库结构]
S3[制定规范]
S4[Review Learnings]
end
J3 -.->|成长| M1
M3 -.->|灵活切换| S2实施建议：
-
初级开发者
- 从 Superpowers 开始，降低学习门槛
- 要求阅读团队知识库，了解项目历史
- 在 mentor 指导下尝试 CE
-
中级开发者
- 日常使用 CE，积累个人和团队知识
- 负责将探索性工作的经验整理到知识库
-
高级开发者
- 深度使用 CE 处理复杂任务
- 负责知识库的架构设计和质量控制
- 制定团队使用规范和最佳实践
实施检查清单
对于一次性项目
- 明确项目结束时间和交付标准
- 使用 Superpowers 快速开发
- 关键经验记录在 project-notes.md
- 如果项目延续，评估迁移到 CE
对于旧项目迭代
- 使用 CE，建立初始知识库（1-2 周）
- 每次 bug fix 都 compound
- 每周 review 知识库新增内容
- 定期清理过时文档（月度）
- 建立知识库治理机制
对于多人协作项目
- 强制使用 CE，知识库是团队共享资产
- 建立 learning 审核流程
- 将知识库纳入 onboarding
- 定期举办 knowledge sharing 会议
- 考虑实现 compound janitor 自动化
对于混合模式
- 明确不同场景使用的模式
- 建立知识从 Superpowers 到 CE 的迁移机制
- 保持代码结构一致性
- 定期评估模式选择的合理性