OpenCode3个实用命令快速理解陌生代码库

说真的，你接过多少个“裸奔”的项目？

那种——没有文档、没有注释、连 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 模式平级。在 TUI 里按 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，而是什么时候用 /build。

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

• 改动范围很小，改一行配置、修一个错别字
• 你已经完全理解了这个项目，明确知道 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 开始改文件、跑测试。你在旁边随时监督，有问题可以随时中断。

几个实用技巧

• Tab 键切换主袋里：在 TUI 里按 Tab 键可以在 Build 和 Plan 之间快速切换，不用每次都敲命令。
• 子袋里可以嵌套调用：你可以在任何对话里用 @ 提及子袋里。比如在 Build 模式下突然想查一个东西，直接 @explore xxx，不用切换模式。
• 不确定先用什么？：问自己一个问题：我想知道，还是我想改？想知道就用 @explore，想改但不确定怎么改就用 /plan，确定要改就直接 /build。
• 把 AGENTS.md 用起来：OpenCode 支持在项目根目录放一个 AGENTS.md 文件，用来固化仓库的规则和上下文。第一次用 @explore 梳理完项目之后，可以把关键信息写进 AGENTS.md，这样下次再让 OpenCode 干活时，它自动就有了项目背景，不用每次都重新解释一遍。

总结

三个命令，一张表梳理清楚：

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

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

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