【OpenCode系统性指南】第2篇：第一次对话：让AI读懂你的项目
【OpenCode系统性指南】第2篇：第一次对话：让AI读懂你的项目
引言
安装好OpenCode后，很多读者的第一反应是直接开始问问题。但很快你会发现：AI对你的项目一无所知，每次都要从头解释项目结构、技术栈、编码规范……效率极低。
有没有一种方法，让AI像老同事一样，天然就理解你的项目？
答案就是：/init命令和AGENTS.md文件。这一篇，我们来揭开这对黄金搭档的神秘面纱。
一、/init 命令的魔力
当你在一个新项目中启动OpenCode时，第一件事就应该执行/init命令。这个命令会做什么？让我们一探究竟。
1.1 一键扫描，自动分析
执行/init后，OpenCode会自动扫描你的项目：
- 文件结构：识别项目类型（前端、后端、全栈等）
- 配置文件：读取
package.json、tsconfig.json、pyproject.toml等 - 依赖信息：分析使用了哪些框架和库
- 代码规范：识别ESLint、Prettier等配置
整个过程通常只需要几秒钟，你就能看到AI正在分析各种文件。
1.2 自动生成项目文档
扫描完成后，OpenCode会自动在项目根目录生成一个AGENTS.md文件。这个文件就像是AI对这个项目的"入职笔记"，包含了：
- 项目概述和技术栈
- 目录结构说明
- 常用命令（构建、测试、启动等）
- 编码规范和约定
- 重要文件说明
1.3 增量更新机制
如果你已经有过AGENTS.md，再次执行/init会怎样？OpenCode会尝试增量更新而非覆盖，保留你手动添加的自定义内容。这意味着你可以放心地编辑这个文件，不必担心丢失个性化配置。
二、AGENTS.md：AI的项目记忆
AGENTS.md文件是OpenCode理解你项目的核心。它不只是一个文档，更是每次对话时自动注入的"项目记忆"。
2.1 为什么叫AGENTS.md？
这个命名来自OpenCode的规则系统。当你打开OpenCode时，它会自动查找并加载以下位置的规则文件：
- 项目级：
./AGENTS.md（项目根目录） - 全局级：
~/.config/opencode/AGENTS.md
这些规则会被注入到每次对话的系统提示中，让AI始终"记得"你的项目背景。
2.2 自动生成 vs 手动完善
OpenCode自动生成的AGENTS.md已经能覆盖大部分场景，但对于复杂项目，你可能需要手动补充：
# 项目规则
## 技术栈
- 前端：React 18 + TypeScript + Tailwind CSS
- 后端：Node.js + Express + Prisma
- 数据库：PostgreSQL
## 编码规范
- 使用函数式组件，避免class组件
- 状态管理优先使用Zustand
- API响应统一使用Result模式
## 禁止事项
- 不要修改prisma/schema.prisma中的已有字段
- 不要在组件中直接调用fetch，使用封装的apiClient
2.3 团队协作利器
强烈建议将AGENTS.md提交到Git仓库。这样团队每个成员使用OpenCode时，都能获得一致的AI体验。新同事加入项目时，AI已经"熟悉"项目，大大降低上手成本。
三、如何向AI描述你的需求
有了AGENTS.md，AI已经理解你的项目。但如何高效地向AI描述你的具体需求？这里有几个实用技巧。
3.1 具体比模糊好
❌ 模糊的请求：
帮我优化一下这个函数
✅ 具体的请求：
@src/utils/parser.ts 的parseConfig函数目前有性能问题，
当配置文件超过1MB时会卡顿。请分析瓶颈并优化，
目标是将处理时间控制在100ms以内。
3.2 使用@引用相关文件
当你提到某个文件或目录时，用@符号让AI精确知道你在说什么：
@src/components/Button.tsx 这个按钮组件需要支持loading状态，
请添加一个isLoading属性，loading时显示旋转图标。
OpenCode会自动读取你引用的文件内容，无需你复制粘贴代码。
3.3 分步验证理解
对于复杂任务，建议先让AI复述需求：
我需要实现一个用户权限系统，包含角色管理和资源分配。
请先总结一下你理解的需求，确认无误后再开始实现。
这样可以避免AI理解偏差导致的大量返工。
四、三个真实对话示例
让我们通过三个实际场景，感受OpenCode的高效协作。
示例1：解释陌生代码
场景：你接手了一个遗留项目，遇到一段看不懂的代码。
用户：@src/legacy/priceCalculator.js 这个calculateFinalPrice函数
逻辑太复杂了，请用通俗的语言解释它在做什么，并画出流程图。
OpenCode：这个函数实现了阶梯定价逻辑：
1. 首先根据用户等级确定基础折扣（VIP用户8折，普通用户9折）
2. 然后根据购买数量应用阶梯优惠：
- 100件以上：额外95折
- 500件以上：额外9折
3. 最后检查是否有可用优惠券，取最优价格
流程图如下：
[用户等级] → [基础折扣] → [数量阶梯] → [优惠券检查] → [最终价格]
关键点：用@引用文件，让请求具体化。
示例2：添加新功能
场景：需要给现有组件添加新特性。
用户：@src/components/UserCard.tsx 需要支持显示用户在线状态。
后端API已经返回了isOnline字段，请：
1. 在组件中显示一个绿色/灰色的状态点
2. 添加hover时显示"在线"/"离线"的tooltip
3. 确保与现有的Tailwind样式一致
OpenCode：我来分析现有组件并实现在线状态显示...
[查看组件结构]
[添加状态指示器]
[实现tooltip功能]
已完成修改，主要变更：
- 添加了StatusDot子组件
- 使用Tailwind的bg-green-500和bg-gray-400
- tooltip使用title属性实现（轻量方案）
关键点：明确列出具体需求，AI会逐步实现并汇总变更。
示例3：修复Bug
场景：发现了一个难以定位的Bug。
用户：用户反馈在Safari浏览器上，@src/components/DatePicker.tsx
的日期选择器点击后没有反应。控制台报错：
"TypeError: undefined is not a function"
请分析原因并修复。
OpenCode：让我分析这个组件...
[读取组件代码]
[检查事件处理逻辑]
发现问题：组件使用了forEach的第二个参数thisArg，
Safari对某些情况的支持不完整。
修复方案：
1. 使用箭头函数替代bind
2. 或者使用可选链操作符?.
我推荐方案1，更加简洁。是否继续修复？
关键点：提供错误信息和复现场景，AI能更快速定位问题。
小结
/init是第一步：在新项目中运行/init，让AI自动理解项目结构- AGENTS.md是项目记忆：提交到Git，让团队获得一致的AI体验
- 具体描述需求：使用
@引用文件，分步验证AI的理解 - 对话是迭代过程：先让AI理解，再让它执行，最后验证结果
📥 想获取更多 OpenCode 资源？
扫码加入「大熊掌门AI编程会员群」：
进群即领：
- 📄 Claude Code 入门指南 PDF（群内领）
专栏更新中，后续解锁：
- 📁 OpenCode 完整配置模板库
- 📝 5个常用自定义命令模板
- 📋 AGENTS.md 规则模板
- 📖 本专栏完整版 PDF 电子书（约20篇文章整合）
群内还有：
- 每周技术干货分享
- 问题答疑
- 付费内容专属优惠