先问一个问题

你接过多少个别人写的项目？

我指的是那种——没有文档、没有注释、连 README 都只有一行“TODO”的项目。打开文件夹，里面几十上百个文件，目录结构五花八门，命名风格各成一派。你想改一个功能，但不知道入口在哪；你想修一个 Bug，但不知道数据从哪来、往哪去。

传统做法是什么？grep搜关键字，翻文件，画调用关系图，折腾半天还没开始写代码。

OpenCode 能帮上忙。但很多人装完之后只会用一种用法：把需求丢进去，让它直接改代码。这当然能干活，但如果你想先看懂一个陌生项目再动手，有几个命令比你想象中好用得多。

下面说三个。

命令一：@explore —— 项目讲解员

这是你面对陌生代码库第一个该敲的东西。

@explore是 OpenCode 内置的一个子代理（subagent），定位非常明确：只读、快速、探索代码库。它不会改任何文件，不会执行任何有副作用的操作，唯一做的事情就是读代码、搜代码、回答你对代码库的问题。

用法很简单。在 OpenCode 的 TUI 里直接输入：

@explore 这个项目的入口文件在哪？ @explore 找出所有和数据库交互的代码 @explore 梳理一下这个项目的目录结构 @explore 这个认证逻辑是怎么串起来的？

它会自动调用grep、glob、read这些工具去翻你的代码库，然后给你一个带文件路径和行号的回答。

跟直接问有什么区别？直接问默认走的是@general代理，它什么都能干但什么都不是最擅长。@explore是专门为“看懂已有项目”设计的，它的工作方式就是搜索 + 读取 + 总结，不会跑偏去给你写代码或者改文件。

什么时候用@explore：

• 刚拿到一个陌生项目，想知道它大概是干什么的

• 想找一个功能在哪实现，但不知道关键字怎么搜

• 想理清模块之间的调用关系

• 任何“我只想知道，不想改动”的场景

记住一句话：看不懂代码的时候，先@explore，别直接@general或者/build。

命令二：/plan —— 先想清楚再动手

@explore帮你搞清楚了“项目现在是什么样”。下一步是“如果要改，应该怎么改”。

这时候用/plan。

/plan是 OpenCode 的主代理（primary agent）之一，和默认的Build平级。你按 Tab 可以在 Build 和 Plan 之间切换。

Plan 模式和 Build 模式的核心差异只有一条：Plan 不修改任何文件，Build 会修改文件。

Plan 模式禁用了所有写操作——edit不调，write不调，有文件写入风险的bash命令也被限制。它只做三件事：读相关代码、分析依赖关系、输出实施方案。

用法：

/plan 我想给这个模块加一个缓存层，你先出一个方案 /plan 重构这个函数的逻辑，告诉我改哪些文件、怎么改 /plan 把这个项目的日志从 console.log 换成 winston，列一下改动范围

Plan 模式会给你一份自然语言的实施计划：涉及哪些文件、每一步改什么、有没有风险点。你看了方案觉得不对，可以调整；觉得没问题，再切到 Build 模式执行。

为什么推荐先/plan再动手？根据社区数据，复杂重构任务采用“先 Plan 后 Build”的策略，**代码一次性通过率能提升大约 40%**。说白了就是：让 AI 先把方案拿出来给你看，你确认了再让它干，比让它直接干然后你返工要快得多。

什么时候用/plan：

• 需求涉及多个文件、多个模块

• 你不确定改动会波及哪些地方

• 你想先看看 AI 的理解对不对，再让它动手

• 任何“改动范围超过 3 个文件”的事情

小改动（改个配置、修个错别字）直接 Build 就行。大改动先 Plan。

命令三：/build —— 动手干活

这个你可能已经用过了。/build是 OpenCode 的默认主代理，拥有所有工具的完整权限——读、写、编辑、删文件、跑命令，全都能做。

但这里要说的不是怎么用/build，而是什么时候用。

很多人打开 OpenCode 就直接输入需求，默认走的就是 Build 模式。这在两种情况下没问题：

1. 改动范围很小，改一行配置、修一个错别字

2. 你已经完全理解了这个项目，知道 AI 要改什么、改哪里

但在陌生代码库上，直接/build的风险在于：AI 可能理解错你的意图，改了你不想改的地方，或者漏掉了关键依赖。

正确的打开方式是把三个命令串起来：

第一步：@explore看懂项目第二步：/plan确认方案第三步：/build执行改动

一个完整的工作流示例

假设你刚接手一个 Express + MongoDB 的项目，需要给用户模块加一个“软删除”功能。

第一步，@explore：

@explore 这个项目的用户模块在哪里？现有的删除逻辑是怎么实现的？

OpenCode 会搜出来src/models/user.js、src/routes/user.js、src/controllers/user.js，告诉你删除接口调的是User.findByIdAndDelete。

第二步，/plan：

/plan 我要把用户删除改成软删除，加一个 deletedAt 字段，查询的时候默认过滤掉已删除的用户。出个方案。

Plan 模式会分析现有代码，告诉你需要改 Model 定义、改 Controller 里的删除逻辑、改查询方法、可能需要加一个索引。方案列得清清楚楚。

第三步，审完方案没问题，切到 Build：

/build 按刚才的方案执行

OpenCode 开始改文件、跑测试。你在旁边看着，有问题随时中断。

几个实用技巧

1. Tab 键切换主代理

在 TUI 里按 Tab 可以在 Build 和 Plan 之间切换。不用每次都敲/plan或/build，按一下 Tab 就行。

2. 子代理可以嵌套调用

你可以在任何对话里用@提及子代理。比如在 Build 模式下突然想查个东西，直接@explore xxx，不用切换模式。

3. 不确定先用哪个？

问自己一个问题：我想知道，还是我想改？

想知道就用@explore，想改但不确定怎么改就用/plan，确定要改就直接/build。

4. 把AGENTS.md用起来

OpenCode 支持在项目根目录放一个AGENTS.md文件，用来固化仓库的规则和上下文。第一次用@explore梳理完项目之后，可以把关键信息写进AGENTS.md，下次再让 OpenCode 干活的时候它自动就有了项目背景，不用每次都重新解释一遍。

总结

三个命令，一张表说清楚：

核心就一句话：陌生代码库，先 Explore 后 Plan 再 Build。别上来就 Build。

这跟写代码的习惯是一样的——需求来了先理解上下文，再设计方案，最后才动手编码。只不过现在这些事可以让 OpenCode 帮你做一部分，你只需要在关键节点上做判断。

下次拿到一个陌生项目，不妨试试这个流程。比你硬啃代码快得多。