#实战案例

以下案例展示 Plan → Explore → Build 的典型工作流，可直接在项目中复现。

#案例 1：为新 API 端点做方案（Plan + Explore）

目标： 在 Express 项目中添加 POST /users 端点。

1. Tab 切到 Plan

2. 输入：

   我们要添加 POST /users。先不要写代码，列出需要改动的文件、验证步骤和风险点。

3. @explore：

   @explore 现有路由如何注册？是否已有 User 模型与校验中间件？

4. 审阅 Plan 输出，确认方案

5. Tab 切到 Build，粘贴方案摘要：

   按刚才的方案实现 POST /users，并添加测试。

要点： Plan 避免盲目改文件；Explore 快速对齐现有模式。

#案例 2：修 failing test（Build + LSP）

目标： CI 中某单测失败。

1. Build 模式：

   运行 pnpm test -- src/auth/login.test.ts，根据失败信息修复，直到通过。

2. 若 TypeScript 报错，确保 opencode.json 已配置 typescript-language-server

3. Agent 利用 LSP diagnostic 迭代修复

permission 提示： 若 bash 为 ask，对 pnpm test* 可在配置中设为 allow 减少打断。

#案例 3：自定义 Code Review Subagent

1. 创建 .opencode/agents/review.md（见 Agent 与权限系统）

2. Plan 模式：

   @review 审查当前分支相对 main 的 diff，按严重程度列出问题

3. 仅允许 git diff*、git log*，避免 Review Agent 改代码

#案例 4：Monorepo 并行会话

场景： 同时处理前端样式与后端 API。

1. 会话 1（Build）：apps/web 相关任务，@apps/web/package.json
2. 会话 2（Build）：packages/api 相关任务
3. 各会话独立上下文，减少混淆

注意： 合并前统一 git pull，避免并行改同一文件。

#案例 5：Headless 生成 CHANGELOG 草稿

opencode run "根据 git log 自上次 tag 以来的提交，生成 CHANGELOG 草稿，Markdown 格式"

适合 release 前人工润色。CI 中需配置 API Key 与 permission，并控制 token 成本。

#案例 6：MCP 查内部文档

配置只读 Confluence/Notion MCP 后：

@explore 在内部文档中查「OAuth 刷新 token」流程，总结给 Build 实现用

Explore + 只读 MCP，Build 再实现，降低误写外部系统的风险。

#案例 7：/init onboarding 新成员

1. 克隆仓库
2. opencode → /init → 审阅 AGENTS.md
3. Plan 模式问：「如何在本项目跑通第一个测试？」
4. 新成员 30 分钟内可自助上手

#反模式（避免）

#下一步

• 资源与链接
• 快速上手