我怎样与 OpenCode Agent 协作

用了一段时间 OpenCode 之后，我不再把它看成更聪明的代码补全。补全工具等着人给出下一行，Agent 会读取项目、搜索代码、调用命令、修改文件，再根据结果继续行动。它接手的是一段工作流程。

但它能做更多事，不等于它知道该做到什么程度。实际效果往往取决于任务边界、项目背景和验收方式是否说清楚。与 Agent 协作，更像是带一位执行力很强、但刚进入项目的工程师，而不是向一个无所不知的系统许愿。

先补足项目上下文 #

Agent 常见的失误不是不会写代码，而是在缺少上下文时做出了看似合理、却不适合当前项目的选择。它可能引入从未使用过的依赖，重构一个本来只需修补的模块，也可能按照通用的“最佳实践”改掉团队有意保留的约定。

第一步不是把需求写得很长，而是让它先认识项目。仓库说明、构建命令、目录职责和已有代码风格，都比一句“帮我优化一下”有用。它需要知道当前任务属于哪一部分，哪些文件可以修改，哪些行为必须保留；也要知道如何检查结果，以及哪些生成文件、密钥和用户改动不能碰。

这类稳定规则适合写进仓库级的 AGENTS.md 或类似文件，免得每次重复。具体需求仍放在当次对话里，不要让长期说明混入临时细节，时间久了很容易失真。

先让它调查，再让它动手 #

面对已有项目，直接要求 Agent 修改代码未必更快。它可能很快给出一个完整的补丁，却建立在错误理解上。我通常让它先读相关文件、搜索调用关系、确认当前实现，再做最小修改。

排查缺陷时更该如此。错误出现在哪一行，原因未必就在那里。应该沿着输入、状态变化和调用链找证据，能复现就先复现，确认根因后再修。否则，一层层增加空值判断和异常捕获，只会把症状藏得更深。

我更愿意给出这样的任务：

移动端文章列表的日期发生换行。先检查相关模板和样式，确认触发条件，
然后做最小修改。不要改变桌面端布局，完成后运行项目现有的构建检查。

我没有规定具体的 CSS 属性，那要看过代码才能判断。问题范围、不能破坏的行为和验证方式则已经说清楚，Agent 可以自己调查，也不至于把任务做成一次页面重写。

把验收方式写进任务 #

“实现一个功能”没有说明怎样才算完成。即使构建失败、漏了边界条件，或者页面没有走到新逻辑，Agent 也可能认为任务已经完成。因此，任务里还要写清不能破坏的行为和验证方法。

比如“增加文章搜索”还是太宽。把搜索范围、空结果状态、能否引入 JavaScript、移动端表现和最终要运行的检查写清楚，Agent 才有机会在执行中自行纠偏，我也更容易判断结果是否可信。

验证不能只听 Agent 解释代码。能运行测试就运行测试，能构建就构建。界面改动要看真实渲染结果，配置变化要确认程序确实读取了它。没有自动化测试，也可以做静态构建、格式检查，或者手工走一遍关键路径。

Agent 对代码的解释不能代替项目检查。

最小改动比大规模重写更可靠 #

Agent 擅长生成代码，也容易生成过多代码。一个小需求可能带来新的抽象层、兼容逻辑、辅助函数，甚至一套测试框架。每一项单看都有理由，合在一起却增加了审查面积，真正的行为变化反而更难找。

两种方案都正确时，我通常沿用现有结构，选择改动较小的方案。只有逻辑确实会复用时才抽取，也不会为尚未出现的需求增加兼容代码。这样的补丁更容易审查和验证。

这不是拒绝重构。如果根因就在错误的边界上，局部修补只会把问题拖下去，那就应该重构。但依据应当是调查结果，而不是 Agent 对“整洁代码”的偏好。先弄清现有结构为什么无法安全承载变化，再扩大范围。

让工具提供证据 #

编码 Agent 可以接触真实环境，这是它比单纯生成代码更有用的地方。搜索能确认符号在哪里使用，版本历史有时能解释一段代码为何存在，构建命令会暴露模板或类型错误，浏览器和截图则用来检查界面。

我更愿意让工具输出代替猜测。互不依赖的搜索和读取可以并行，有前后关系的动作就按顺序做：先确认父目录再创建文件，修改完成后再格式化，提交前先看差异。普通的工程纪律对 Agent 一样有效。

工具权限也要有边界。读取和搜索风险较低；删除文件、修改依赖、访问网络、提交代码或操作远程仓库则要谨慎。没必要关闭所有权限，但不可逆或会影响其他协作者的操作，应该先确认。

计划的作用是减少返工 #

并非每个任务都要先写计划。改一处文案、补一个判断或运行一条命令，直接做更省事。涉及多个模块、设计取舍或数据迁移时，再花时间计划。

计划应该提前处理执行中绕不过去的决定，包括数据来源、状态归属、迁移方式和失败恢复，并写明各步骤怎样验收。边界定下来后，执行时可以减少返工。

长任务还要随手记录状态，包括已经确认的事实、没解决的问题、执行过的命令和下一步入口。这样即使上下文被压缩或会话中断，也不必从头调查。这些记录也方便之后审查。

我怎样与 Agent 分工 #

Agent 可以读很多文件，快速尝试方案，反复执行检查，但它不承担产品和工程决定的后果。需求是否值得做、体验是否符合预期、风险能否接受，仍要由人判断。

我的分工方式很简单：人定义目标、优先级、约束和验收标准，Agent 调查现状、实施改动并收集验证证据。涉及关键取舍、越界变化或不可逆操作时，再由人决定。

这不需要逐行指挥。指令过细，会把 Agent 用成昂贵的键盘；指令太宽，它只能靠猜。说清结果与边界，把实现路径留给它调查，碰到会影响方向的歧义再停下来问。

失败时先改协作方式 #

Agent 给出糟糕结果时，重新生成一次偶尔有用，但我会先看失败发生在哪一层：是漏读了关键文件、误解需求、没做验证，还是权限和范围没有约束。原因不同，改法也不同。

反复提醒的规则应该写进项目说明，太晚才发现的错误可以通过自动化检查提前暴露。任务容易失控时，应明确最小改动和禁止范围；关键决策缺少依据时，则要求 Agent 遇到歧义先提问。这些做法比一句“下次注意”有用。

当然，Agent 还是会犯错。它可能误读命令输出，引用不存在的接口，或者为了通过测试去修改测试本身。与其期待它永远正确，不如让差异可审查、命令可复现、修改可撤销。

我的日常处理顺序 #

我现在处理真实任务，大致按下面的顺序：

说明目标、范围、约束和验收方式。
让 Agent 阅读项目规则与相关实现，先建立上下文。
对复杂任务确认方案，对简单任务直接做最小修改。
让它运行构建、测试或其他可重复检查。
审查代码差异，重点看越界修改、隐藏假设和异常路径。
把反复出现的教训沉淀为项目规则或自动化检查。

我的做法是先理解项目，再控制改动范围并验证结果。高风险操作仍需人工确认。

OpenCode 一类的 Agent 提高了执行速度，也会更快暴露含糊的需求、薄弱的测试和混乱的边界。项目规则清楚，它就能独立多走几步；项目依赖口头约定和隐性知识，它也会沿着看似合理的方向越走越远。比起反复琢磨一句提示词，我更愿意把时间花在整理项目规则和验收手段上。