用 OpenCode 理解陌生代码库：3 个实用命令助你快速上手任何项目

先问一个问题
你接过多少个别人写的项目？

我指的是那种——没有文档、没有注释、连 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 模式。这在两种情况下没问题：

改动范围很小，改一行配置、修一个错别字
你已经完全理解了这个项目，知道 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 之间切换。不用每次都敲 /plan 或 /build，按一下 Tab 就行。

子袋里可以嵌套调用

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

不确定先用哪个？

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

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

把 AGENTS.md 用起来

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

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

命令
类型
能改文件吗
什么时候用
@explore
子袋里
否
看不懂项目，想梳理结构、搜代码
/plan
主袋里
否
想改东西，但先要个方案看看
/build
主袋里
是
方案确认了，直接动手干
核心就一句话：陌生代码库，先 Explore 后 Plan 再 Build。别上来就 Build。

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

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

推荐学习
把指令、脚本和资源打包成一个标准化的“技能包”。一次教会，终身受用；换个平台，照样生效。

课程内容：

彻底搞懂 Skill、Prompt、MCP 三者的本质区别，从此不再概念混淆
掌握“按需加载”机制，让 AI 只读取当前任务需要的上下文，Token 省着花
手把手封装你的第一个个人专属 AI 技能，现场跑通
进阶用法：用脚本和条件触发，让 AI 自动执行复杂工作流，不再只能“查资料”
掌握开放标准，一次打包，Claude、Cursor 等多平台无缝复用