OpenCode 共通 Agent Loop¶

无论你用 Claude Code、Codex 还是 OpenCode，高质量工作流都可以归纳成同一条循环。差异主要在生态、权限、模型和配置，不在基本工程闭环。

标准循环¶

flowchart LR
  A["Research<br/>只读分析，不改文件"] --> B["Plan<br/>写出文件范围、步骤、风险、验证"]
  B --> C["Implement<br/>小步修改，遵守计划"]
  C --> D["Validate<br/>跑测试、lint、typecheck、build"]
  D --> E["Review<br/>人看 diff，Agent 修复问题"]
  E --> F["Record<br/>把重复经验写回规范或 skill"]
  F --> A

每一步的交付物¶

阶段	交付物
Research	相关文件、调用链、现有模式、风险
Plan	分步计划、文件范围、验证命令
Implement	最小改动 diff
Validate	命令输出、失败原因、修复结果
Review	风险清单、未覆盖边界
Record	AGENTS.md / CLAUDE.md / agent config / skill 更新建议

三个 CLI 的 loop 差异¶

阶段	Claude Code	Codex	OpenCode
Research	适合配合 subagents 和 MCP 做复杂探索	适合按上下文指针读 repo 并形成任务计划	适合用只读 agent、LSP 和不同模型探索
Plan	适合用 Plan / Thinking 流程拆任务	适合用 Goal / Context / Constraints / Done When 委派	适合把 planning agent 和 build agent 分开
Implement	适合多文件 feature 和工具协作	适合最小补丁、测试修复和审查驱动修改	适合按模型能力切换执行方式
Validate	适合结合 hooks、MCP、浏览器工具	适合把验证作为 Done When 的硬要求	适合把验证命令写入 agent 工作流
Record	适合写回 `CLAUDE.md` 或 skill	适合写回 `AGENTS.md` 或 workflow	适合写回 agent 配置、提示文件或项目规则

什么时候必须先 Research¶

不熟悉代码库。
需要改多个文件。
需要接已有接口。
任务涉及安全、权限、支付、数据。
你不确定项目已有模式。

什么时候必须先 Plan¶

任务超过 20 行改动。
涉及 3 个以上文件。
有多个可选方案。
可能破坏兼容性。
需要人确认产品行为。

什么时候必须 Validate¶

所有真实项目任务。

如果无法运行验证，Agent 必须交代：

为什么无法运行。
应该运行什么命令。
预期成功输出是什么。
如果失败下一步怎么查。

常用阶段提示词¶

Research：

先不要修改文件。请阅读相关代码、调用链、已有测试和项目规范，然后总结现状。

Plan：

请给出实现计划，列出要改的文件、每步目的、风险和验证命令。等我确认后再修改。

Implement：

按刚才确认的计划实现。保持最小改动，不要重构无关代码。

Validate：

请运行相关测试、lint、typecheck 或 build。失败时先分析原因，再做最小修复。

Review：

请基于当前 diff 做自查，重点看无关改动、测试缺失、边界情况和安全风险。