理解项目结构：OpenCode /init命令深度解析

AI编程助手正在重塑日常开发的工作流——这一点，已有大量开发者亲身体验。

不是“未来几年才会发生”，而是此刻已经真实落地。

Cursor、GitHub Copilot、Claude Code 这些工具在过去一年中密集涌现。你可能已经尝试过其中某款，让AI帮助编写代码、修复Bug。效果时好时坏——有时AI仿佛真正理解你的项目，有时它连你用的框架都搞不清楚。

问题并非出在AI模型本身。Claude和GPT-4的能力有目共睹，代码逻辑推理毫无问题。

症结在于上下文。

AI并不了解你的项目结构、所用技术栈、代码风格、哪些是核心逻辑、哪些是自动生成文件。你提出需求时，它只能靠猜测作答。猜对是运气，猜错是常态。

OpenCode通过/init命令解决了这一痛点。本文不谈概念，只聚焦它究竟如何运作。

一、一个命令，改变了什么

OpenCode是SST团队开发的开源AI编程Agent，采用Go语言编写，运行在终端中。它的定位非常清晰：不是聊天窗口，而是能够读取代码、修改文件、执行命令的智能Agent。

安装OpenCode后，进入项目目录，输入opencode，即可启动TUI界面。

接着输入/init。

操作极为简单，但其背后发生的动作远超你的想象。

OpenCode会扫描整个项目，分析代码组织方式，并自动生成一个AGENTS.md文件。这个文件记录了项目的结构、技术栈、代码规范等关键信息。

此后，你在OpenCode中提出的任何问题或需求，AI都会基于这个文件来理解你的项目。

简而言之，/init解决了一个根本性问题：AI如何知晓你的项目全貌。

二、本质是“让AI拿到项目的说明书”

要理解/init的价值，首先需要了解AI编程助手运行的底层逻辑。

AI模型本身并不包含你项目的任何信息。当你询问“帮我给这个项目加个登录功能”时，它只能根据你提供的有限上下文（比如当前打开的文件、你刚说的话）进行推测。如果它不知道你的项目基于Next.js还是Express、数据库是什么、代码风格如何，生成的内容大概率需要大量修改。

AGENTS.md本质上是一份专为AI设计的项目说明书。

工具决定了AI能做什么（读文件、改代码、执行命令），而AGENTS.md决定了AI应该怎么做。它定义了项目结构、代码风格、开发规范、架构决策等核心要素。

OpenCode启动时，会将AGENTS.md的内容加载进AI的系统提示词中。这意味着AI在回答任何问题之前，已经阅读了这份“说明书”。

/init正是生成这份说明书的最快途径。

三、/init 到底做了什么——四个步骤拆解

第一步：扫描目录结构
/init触发后，OpenCode会遍历项目根目录及子目录。它不是简单地罗列文件名，而是识别组织模式——哪些是源代码目录、哪些是配置文件、哪些是构建产物。

这一步的关键在于区分“项目内容”和“项目噪音”。node_modules、.git、dist等目录不会被当作项目核心结构处理。

第二步：识别框架和语言模式
OpenCode通过文件扩展名和特定文件的存在来判断技术栈。

看到package.json即判定为Node.js项目；看到requirements.txt或pyproject.toml则识别为Python；看到go.mod确定为Go；看到pom.xml则识别为Java Maven项目。

这一步并非猜测，而是基于确定性特征做出判断。

第三步：读取关键配置文件
/init会读取package.json、tsconfig.json、.eslintrc这类配置文件，从中提取：

• 项目名称和版本
• 主要依赖
• 构建工具和脚本
• 语言版本要求

这些信息会被写入AGENTS.md，让AI了解项目所用的库及版本号。

第四步：生成 AGENTS.md
基于前三步收集的数据，OpenCode生成一份结构化的Markdown文档。

这份文档通常包含：

• 项目概述
• 架构说明
• 目录结构及每个目录的功能
• 代码规范
• 常用操作

如果项目已存在AGENTS.md，/init会在其基础上进行补充，而非覆盖。

整个过程完全自动化，无需手动填写任何内容。

四、有 /init 和没有 /init 的差别

场景一：没有 /init

你打开OpenCode，直接输入：“帮我找到支付流程的入口。”

AI不知道你的项目结构。它只能猜测——可能位于src/payment、routes或api。它会尝试读取几个它认为可能的文件，如果猜错，你需要多轮对话来纠正。

场景二：运行了 /init

同样的需求。AI的系统提示词中已包含AGENTS.md的内容。它知道项目是TypeScript + Express架构，明白src/payment/是支付模块，routes/下是路由定义。

它能够直接定位到正确的文件，并清晰说明流程。

差别不是“快一点”，而是从“猜测”转变为“确知”。

再看一个更具体的对比：

/init将AI从一个“会写代码的陌生人”转变为“懂你项目的同事”。

五、对你有用的三个工程启示

启示一：上下文是AI编程的瓶颈，而非模型能力

许多人抱怨AI生成的代码不实用，归根结底是上下文没给够。/init所做的本质上就是将项目上下文结构化、持久化。

OpenCode的上下文管理思路值得借鉴：不是每次对话重新构建上下文，而是通过AGENTS.md这样的文件做到一次性建立、持续性复用。

你的项目里是否也有类似的“上下文资产”？技术文档、架构决策记录、代码规范——这些都可以成为AI的输入。

模型能力决定了AI的上限，而上下文质量决定了AI的下限。

启示二：AGENTS.md 可以团队共享，不仅限于个人使用

AGENTS.md推荐提交到Git仓库。这意味着团队所有成员共享同一份项目上下文。

新人入职后，git clone后运行/init，AI就能基于团队统一的规范辅助开发，无需老员工反复口头交代“我们这个项目需要注意什么”。

本质上，AGENTS.md是将团队的隐性知识转化为显性文档，而且是AI可直接读取的文档。

启示三：/init 不只是初始化，而是持续演进

/init并非只运行一次。项目结构变化、技术栈升级、新增模块——这些变化都应反映在AGENTS.md中。

OpenCode支持在opencode.json中通过instructions字段加载额外的规则文件，例如CONTRIBUTING.md、docs/guidelines.md。这意味着你可以将项目规范分散维护，OpenCode会自动聚合。

良好的项目上下文不是一次性生成的，而是随着项目一起成长。

六、最后问你一个问题

你的团队当前使用的AI编程工具，每次对话是否都知道你的项目结构、技术栈和规范？

如果答案是否定的，你浪费的不仅仅是Token——你还在浪费AI本应具备的“项目理解力”。

而这个问题，仅需一个/init就能解决。