AI编码助手虽好用，却常因不理解项目规范而输出格格不入的代码。本指南提供了一套完整的配置方法，通过创建项目指令文件，能将AI训练成真正懂项目、守规矩的智能伙伴，显著提升开发效率与代码质量。
智能速览
通过AGENTS.md文件定义项目规则，让AI理解项目上下文。
使用/init命令可一键生成项目指令文件初稿。
支持项目级和全局规则合并，兼顾团队规范与个人偏好。
利用opencode.json引用现有文档，避免信息重复维护。
配置后，AI生成的代码能自动遵守项目的特定规范。
精华内容
AI助手虽强大，却常因不懂项目规范而事倍功半。通过一套清晰的配置机制，可以将其训练成懂项目、守规矩的智能伙伴，从源头解决问题。
项目速成手册
核心在于创建一个名为AGENTS.md的文本文件，它就像是给AI准备的项目“独家记忆”。开发者可以在其中明确定义项目的技术栈（如TypeScript）、代码风格、目录结构等关键信息。
配置过程极其简单，只需在项目根目录下运行/init命令，OpenCode便会自动扫描项目并生成一份初稿。之后将此文件提交至Git，团队成员即可共享同一套项目规范。
例如，文件可明确告知AI，当前是一个SST v3的Monorepo项目，所有共享代码必须放置于packages/cores目录。有了这些上下文，AI再生成或重构代码时，就能精准遵守约定，不再需要手动修改。
兼顾团队与个人
为了平衡团队统一性和个人习惯，系统支持项目级与全局两种配置模式。项目级规则存放在项目根目录，跟随Git版本控制，是所有成员必须遵守的团队共识。
全局规则则存放在用户个人配置目录中，仅对当前用户生效，非常适合定义个人编码偏好，例如“始终使用箭头函数”。
当两种规则同时存在时，系统不会强制二选一，而是将两者智能合并加载。项目规则作为基础，个人规则作为补充，从而实现既遵守团队规范，又保留个人编码风格的最佳实践。
规则复用高级技巧
对于已有完善文档（如CONTRIBUTING.md）的项目，重复将内容粘贴到AGENTS.md中既低效又容易出错。此时，可以利用opencode.json文件实现规则的优雅复用。
opencode.json扮演着“指路牌”的角色，通过其instructions数组，可以列出希望AI读取的外部文件路径。它支持引用单个文件、指定目录下的所有文件，甚至可以使用通配符（如docs/*.md）进行批量引用。
这种机制确保了信息的唯一来源，团队只需维护好一套核心文档即可，避免了多处同步的繁琐，让AI指令的维护变得轻松高效。
通过这套配置方法，开发者与AI助手的交互模式被彻底改变，从被动修正转为主动引导。AI不再是模糊的通用工具，而是能深刻理解项目背景、无缝融入工作流的核心成员。现在就去尝试，让你的AI助手正式‘入职’吧，你最想先教会它什么？
