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 | 有 /init |
|---|---|---|
| AI对项目结构的理解 | 为零，需要你逐步告知 | 完整，启动即具备 |
| 代码生成一致性 | 每次可能风格不同 | 遵循项目现有规范 |
| 多轮对话效率 | 重复解释项目背景 | 一次初始化，全程复用 |
| 接手新项目 | 从零开始摸索 | /init 三秒建立认知 |
/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就能解决。
