OMCC 协作流程

角色分工

• Claude：架构师 + 验收者 + 最终决策者 + 协调者
• Coder：执行者（代码/文档改动）
• Reviewer：审核者 + 高级代码顾问
• Advisor：高阶顾问（架构设计、第二意见）→ 详见 /advisor-collaboration
• Frontend：前端/UI 专家（界面设计、样式、动效）
• Librarian：网络研究专家（文档查询 + 网络搜索 + 代码搜索）
• Looker：多模态分析专家（PDF/图片/图表分析）

任务拆分原则（分发给 Coder）

⚠️ 一次调用，一个目标。禁止向 Coder 堆砌多个不相关需求。

• 精准 Prompt：目标明确、上下文充分、验收标准清晰
• 按模块拆分：相关改动可合并，独立模块分开
• 阶段性 Review：每模块 Claude 验收，里程碑后 Reviewer 审核

🎯 如何给 Coder 编写有效的任务提示词

核心原则：Coder 是一位能力有限但勤奋的同事——他从未见过你的代码库，但会严格按照你的指令执行。任务失败的主要原因是规格不足（under-specification），而非模型能力不足。

1. "坐在你旁边的同事"测试

把 Coder 想象成一个刚入职、从未见过项目代码的初级开发者：

• ❌ 他不知道项目的文件结构和约定
• ❌ 他不了解已有的工具函数和组件
• ❌ 他不清楚潜在的业务约束
• ✅ 但他会严格按照你的指令执行

因此你需要：提供完整的上下文、明确的步骤、清晰的交付标准。

2. 给方向，不是问问题

3. 详细任务提示词模板

**任务目标**：[一句话说明要完成什么]

**背景上下文**：
- 项目使用 [框架/技术栈]
- 相关文件在 [目录路径]
- 参考已有实现 [文件路径]

**具体步骤**：
1. [第一步做什么]
2. [第二步做什么]
3. [继续列出所有步骤]

**约束条件**：
- [必须遵守的规则，如编码规范]
- [需要保持兼容的接口]
- [不要修改的文件]

**潜在陷阱**（重要！）：
- [你知道的可能出问题的地方]
- [容易被忽略的边界情况]
- [项目特有的约束]

**交付标准**（Definition of Done）：
- [ ] [具体的验收条件 1]
- [ ] [具体的验收条件 2]
- [ ] 运行 [测试命令] 确保通过

**自检步骤**（Feedback Loop）：
- 完成后运行 [命令] 验证
- 检查 [文件] 确认改动正确

4. 实际案例对比

❌ 糟糕的 Prompt：

修复登录 bug

✅ 优秀的 Prompt：

**任务目标**：修复登录功能的 token 刷新问题

**背景上下文**：
- 项目使用 JWT 认证，token 存储在 localStorage
- 认证相关代码在 `src/auth/` 目录
- 参考 `src/auth/refresh.ts` 的刷新逻辑

**问题描述**：
用户报告登录后约 1 小时会被踢出登录。经分析，问题是 token 过期后没有自动刷新。

**具体步骤**：
1. 在 `src/auth/interceptor.ts` 添加 401 响应拦截
2. 检测到 401 时调用 `refreshToken()` 函数
3. 刷新成功后重试原请求
4. 刷新失败时重定向到登录页

**约束条件**：
- 不要修改 `src/auth/login.ts` 的接口签名
- 保持与现有 axios 实例的兼容性

**潜在陷阱**：
- 刷新 token 请求本身也可能返回 401，需要避免无限循环
- 并发请求时可能同时触发多次刷新，需要加锁

**交付标准**：
- [ ] 401 响应能正确触发 token 刷新
- [ ] 刷新成功后原请求能正常重试
- [ ] 刷新失败时用户被正确引导到登录页
- [ ] 运行 `npm test -- --grep "auth"` 测试通过

**自检步骤**：
- 运行 `npm run lint` 确保代码规范
- 检查 Network 面板确认刷新逻辑正常触发

5. 常见错误

核心流程

0. 网络研究：Librarian 查询外部资料（可选）

任务开始前，如果需要查询外部文档或最新信息：

• 调用 Librarian 查询官方文档、网络搜索、GitHub 代码
• 获取最佳实践、解决方案、外部代码示例
• 将研究结果作为上下文传递给 Coder

Librarian(PROMPT="React useEffect 的最佳实践", cd=".")
→ 返回官方文档链接和代码示例
→ 将结果作为上下文传给 Coder

注意：本地代码搜索请使用 Claude 的 Explore 代理

1. 执行：Coder 处理所有改动

所有代码、文档等内容改动任务，直接委托 Coder 执行。

调用前（复杂任务推荐）：

• 调用 Librarian 查询外部文档和最佳实践
• 在 PROMPT 中列出修改清单
• 复杂问题可先与 Reviewer 沟通：架构设计或复杂方案可先咨询后再委托 Coder 执行

2. 验收：Claude 快速检查

Coder 执行完毕后，Claude 快速读取验收：

• 无误 → 继续下一任务
• 有误 → Claude 自行修复

3. 审核：Reviewer 阶段性 Review

阶段性开发完成后，调用 Reviewer review：

• 检查代码质量、潜在 Bug
• 结论：✅ 通过 / ⚠️ 优化 / ❌ 修改

工具参考

Librarian 网络研究能力

Librarian 通过 OpenCode CLI 配置的 MCP 提供网络研究能力：

注意：本地代码搜索请使用 Claude 的 Explore 代理

Looker 多模态分析

💡 Advisor 详细指南：如需了解 Advisor 的具体调用方式和触发场景，请执行 /advisor-collaboration 技能。

前端/UI 任务路由

前端/UI 任务应使用 Frontend 代理！

💡 Frontend 详细指南：执行 /frontend 技能获取完整的前端开发指南。

会话复用：保存 SESSION_ID 保持上下文。

独立决策

Coder/Reviewer/Advisor 的意见仅供参考。你（Claude）是最终决策者，需批判性思考，做出最优决策。

详细参数：[coder-guide.md](coder-guide.md) | [reviewer-guide.md](reviewer-guide.md)