两级AI Agent配置——全局规范项目细节AI从陌生人到熟悉你的项目大部分人在用AI写代码时遇到的问题AI不知道什么时候该问、什么时候该直接做不知道你喜欢什么编码风格不知道你的项目环境。解决不是靠每次对话开头给AI讲一遍——是靠两份文件全局AGENTS.md定义工作规范项目级AGENTS.md定义具体环境。文章目录两级AI Agent配置——全局规范项目细节AI从陌生人到熟悉你的项目一、为什么需要两级配置二、全局AGENTS——AI在所有项目里怎么配合你优先级——用户指令永远高于规范复杂任务先澄清简单任务直接做批量操作先验证不给废话注释但关键位置必须加操作出错立刻停下三、项目级AGENTS——当前项目的精确环境信息精度到了版本号、绝对路径容易踩坑的环境差异写进文档构建、测试、运行——命令可以直接复制项目结构——AI不是理解项目是能读到它四、两级AGENTS的配合——从陌生人到熟悉项目五、这两份文件比README更基础一、为什么需要两级配置用AI写代码最烦的有几件事该问的不问——改了一个方法签名AI没告诉你它影响了十几个调用方全给你改了不该问的问——修一个拼写错误AI跟你说这个改动可能影响性能不知道你的偏好——你习惯把SQL写在XML里AI给你塞进注解里每次都得手动改回来不知道你的环境——AI写了一个npm run dev的命令但在你的Windows上要加cmd /c前缀这些问题不是AI不够聪明——是AI不知道你的工作方式。每换一个新项目AI是零记忆的——你要花前半个小时给它讲这个项目用什么JDK、数据库怎么连、测试怎么跑。两级AGENTS.md就是解决这个问题的——全局规范告诉AI你喜欢怎么工作项目细节告诉AI这个项目的环境是什么。二、全局AGENTS——AI在所有项目里怎么配合你全局AGENTS.md放在~/.config/opencode/下AI在任何项目里都会先读这份文件。它定义了你的工作规范——不是技术细节是你和AI的协作方式。优先级——用户指令永远高于规范## 优先级 用户明确指令 本规范。当用户说不用写测试直接改等明确指示时以用户为准。这是一条硬约束AI不能因为规范里写了必须先写测试就在你明确说不改了直接修的时候跟你反复确认。规范是给你减少沟通成本的——不是给你增加沟通成本的。复杂任务先澄清简单任务直接做以下情况必须先向用户提问澄清 - 新增功能、重构、架构变更 - 需求描述模糊或有歧义 - 涉及多个模块的联动改动 以下情况可直接执行无需前置提问 - 修拼写、改变量名、调整格式等确定性修改 - 用户已给出明确、完整的指令含边界条件 - 纯配置变更、文档修正这一条的作用是控制AI的创造力范围。修改一个变量名——AI直接改。新增一个模块——AI必须先列方案等你点头。不是AI不懂技术是**谁为决策负责的边界必须清晰**。复杂任务AI只是给你罗列选项你选哪个、为什么——这些AI不能替你做。批量操作先验证批量操作编码转换、批量重命名、全局替换等必须先在单个文件上 完整执行并验证结果正确后再推广到全部文件。验证时不能只看控制台输出 要检查文件的实际字节/字符内容。这是从实际踩坑里总结出来的。AI做批量替换时可能因为编码问题把中文文件名改乱、把UTF-8 BOM头当成有效字符替换。单文件验证不是谨慎过度——是批量替换如果方向错了修回来的工作量是改一个文件的几百倍。不给废话注释但关键位置必须加禁止无意义的注释如 // i、// 设置name但关键位置必须主动加注释 无需等待提示复杂算法逻辑、非常规写法、边界条件处理、业务规则、临时方案这一条定义了你的代码风格注释不是为了满足覆盖率指标是给未来三个月后读这段代码的自己一个快速理解的机会。AI写注释容易走两个极端——要么什么都不写要么每一行都写。这条规范让AI知道你只需要在真正需要的地方写注释。操作出错立刻停下操作出错时应立即停下向用户说明不要自行反复尝试修复导致问题扩大AI容易犯的一个错误是操作A失败了→自己推测原因→执行操作B补救→B也失败了→再尝试C。三圈下来用户发现问题从一个小调整变成了一串连锁改动。这条规范确保AI在第一步没成功时就停下来而不是自己反复试错把局面扩大。三、项目级AGENTS——当前项目的精确环境信息项目级AGENTS.md放在项目根目录下AI切换到当前项目时读这份文件。它不定义怎么配合你它定义**“这个项目的技术环境是什么”**。## 环境配置 | 项目 | 值 | |------|-----| | Java 版本 | **Java 1.8.0_152** (Oracle) | | JAVA_HOME | D:\Program Files\Java\jdk1.8.0_152 | | Maven | **Apache Maven 3.9.5** | | Oracle | JDBC URL: jdbc:oracle:thin:127.0.0.1:1521:orcl, user: core | ## 重要 PowerShell 脚本执行策略禁止 npx用 cmd /c npx ... 绕过精度到了版本号、绝对路径不是写Java 8“——是写Java 1.8.0_152 (Oracle)。不是写Maven 3.x”——是写Apache Maven 3.9.5。不是写数据库Oracle——是写jdbc:oracle:thin:127.0.0.1:1521:orcl用户名core。每个参数都是精确的——不是随便写的近似值是你在这台电脑上实际跑通的配置。AI不需要猜测用户的JDK版本是什么它读到的是你的确切安装路径。容易踩坑的环境差异写进文档| **重要** | PowerShell 脚本执行策略禁止 npx用 cmd /c npx ... 绕过 |这一行不值得技术上分析半天——但AI在没有这条提示的时候会用npx playwright test直接跑然后报错。你不需要每次重新解释PowerShell需要cmd /c。写进文件里AI每次自己读。构建、测试、运行——命令可以直接复制## 构建 运行 # 编译 mvn compile -DskipTests -pl browise-platform -q # 测试 mvn test -pl browise-platform # 运行 mvn spring-boot:run -pl browise-demo不是用Maven编译项目——是完整的Maven命令。AI不用从这是一个Spring Boot项目推理出大概用mvn spring-boot:run启动——它直接拿到可执行的命令。项目结构——AI不是理解项目是能读到它## 项目结构 D:\work\browise\ ├── browise-common/ # 公共工具 ├── browise-crypto/ # SM2/SM3/SM4 加密 ├── browise-platform/ # 认证授权、JWT、缓存 ├── browise-formbuilder/ # 表单设计器后端 └── browise-vue/ # Vue 3 前端AI不是通过代码阅读理解项目结构的——你是直接告诉它每个模块是做什么的。你不需要让AI从代码里猜你写下来browise-crypto处理哪三个加密协议、browise-platform管认证和缓存。AI从你写的描述开始工作而不是从零开始猜。四、两级AGENTS的配合——从陌生人到熟悉项目用户添加了新项目 │ ▼ AI 读全局 AGENTS.md ├── 知道复杂任务先澄清、批量操作先验证单文件、不给废话注释 ├── 知道写代码后自动跑测试 └── 知道操作出错时停下来而不是反复尝试 │ ▼ AI 读项目 AGENTS.md ├── JDK 1.8.0_152路径 D:\Program Files\Java\jdk1.8.0_152 ├── Oracle 连 127.0.0.1:1521:orcl用户名 core ├── npx 必须用 cmd /c 绕过 PowerShell 限制 └── 后端用 mvn spring-boot:run -pl browise-demo 启动 │ ▼ AI 开始执行——不问环境问题、不问编码风格、直接按你的方式干活全局规范定义了跨项目的协作方式项目细节定义了这个项目的技术环境。换了项目全局规范不变只换项目细节——AI从第一次在项目上协作就知道你喜欢什么方式、这个项目应该怎么跑。五、这两份文件比README更基础README是给新人看的——“这个项目是做什么的、怎么部署”。AGENTS.md是给AI看的——“这个项目怎么在我的电脑上跑起来、跑测试、跑构建”。这份文件有一个功能README永远做不到AI不需要任何人工交互就能独自把这个项目从零跑到测试通过。这不是自动部署的级别——是任何一个新人或AI拿到这份文件都不需要再问你任何问题。不是AI变聪明了——是你把你每次给AI讲一遍的东西写成文件了。这两份AGENTS.md的价值不在技术内容本身——在它们每次替你回答AI问题的时候你少花了几十分钟的沟通成本。 两级AI Agent配置——全局规范加项目细节AI从陌生人到熟悉你的项目
两级AI Agent配置——全局规范项目细节AI从陌生人到熟悉你的项目大部分人在用AI写代码时遇到的问题AI不知道什么时候该问、什么时候该直接做不知道你喜欢什么编码风格不知道你的项目环境。解决不是靠每次对话开头给AI讲一遍——是靠两份文件全局AGENTS.md定义工作规范项目级AGENTS.md定义具体环境。文章目录两级AI Agent配置——全局规范项目细节AI从陌生人到熟悉你的项目一、为什么需要两级配置二、全局AGENTS——AI在所有项目里怎么配合你优先级——用户指令永远高于规范复杂任务先澄清简单任务直接做批量操作先验证不给废话注释但关键位置必须加操作出错立刻停下三、项目级AGENTS——当前项目的精确环境信息精度到了版本号、绝对路径容易踩坑的环境差异写进文档构建、测试、运行——命令可以直接复制项目结构——AI不是理解项目是能读到它四、两级AGENTS的配合——从陌生人到熟悉项目五、这两份文件比README更基础一、为什么需要两级配置用AI写代码最烦的有几件事该问的不问——改了一个方法签名AI没告诉你它影响了十几个调用方全给你改了不该问的问——修一个拼写错误AI跟你说这个改动可能影响性能不知道你的偏好——你习惯把SQL写在XML里AI给你塞进注解里每次都得手动改回来不知道你的环境——AI写了一个npm run dev的命令但在你的Windows上要加cmd /c前缀这些问题不是AI不够聪明——是AI不知道你的工作方式。每换一个新项目AI是零记忆的——你要花前半个小时给它讲这个项目用什么JDK、数据库怎么连、测试怎么跑。两级AGENTS.md就是解决这个问题的——全局规范告诉AI你喜欢怎么工作项目细节告诉AI这个项目的环境是什么。二、全局AGENTS——AI在所有项目里怎么配合你全局AGENTS.md放在~/.config/opencode/下AI在任何项目里都会先读这份文件。它定义了你的工作规范——不是技术细节是你和AI的协作方式。优先级——用户指令永远高于规范## 优先级 用户明确指令 本规范。当用户说不用写测试直接改等明确指示时以用户为准。这是一条硬约束AI不能因为规范里写了必须先写测试就在你明确说不改了直接修的时候跟你反复确认。规范是给你减少沟通成本的——不是给你增加沟通成本的。复杂任务先澄清简单任务直接做以下情况必须先向用户提问澄清 - 新增功能、重构、架构变更 - 需求描述模糊或有歧义 - 涉及多个模块的联动改动 以下情况可直接执行无需前置提问 - 修拼写、改变量名、调整格式等确定性修改 - 用户已给出明确、完整的指令含边界条件 - 纯配置变更、文档修正这一条的作用是控制AI的创造力范围。修改一个变量名——AI直接改。新增一个模块——AI必须先列方案等你点头。不是AI不懂技术是**谁为决策负责的边界必须清晰**。复杂任务AI只是给你罗列选项你选哪个、为什么——这些AI不能替你做。批量操作先验证批量操作编码转换、批量重命名、全局替换等必须先在单个文件上 完整执行并验证结果正确后再推广到全部文件。验证时不能只看控制台输出 要检查文件的实际字节/字符内容。这是从实际踩坑里总结出来的。AI做批量替换时可能因为编码问题把中文文件名改乱、把UTF-8 BOM头当成有效字符替换。单文件验证不是谨慎过度——是批量替换如果方向错了修回来的工作量是改一个文件的几百倍。不给废话注释但关键位置必须加禁止无意义的注释如 // i、// 设置name但关键位置必须主动加注释 无需等待提示复杂算法逻辑、非常规写法、边界条件处理、业务规则、临时方案这一条定义了你的代码风格注释不是为了满足覆盖率指标是给未来三个月后读这段代码的自己一个快速理解的机会。AI写注释容易走两个极端——要么什么都不写要么每一行都写。这条规范让AI知道你只需要在真正需要的地方写注释。操作出错立刻停下操作出错时应立即停下向用户说明不要自行反复尝试修复导致问题扩大AI容易犯的一个错误是操作A失败了→自己推测原因→执行操作B补救→B也失败了→再尝试C。三圈下来用户发现问题从一个小调整变成了一串连锁改动。这条规范确保AI在第一步没成功时就停下来而不是自己反复试错把局面扩大。三、项目级AGENTS——当前项目的精确环境信息项目级AGENTS.md放在项目根目录下AI切换到当前项目时读这份文件。它不定义怎么配合你它定义**“这个项目的技术环境是什么”**。## 环境配置 | 项目 | 值 | |------|-----| | Java 版本 | **Java 1.8.0_152** (Oracle) | | JAVA_HOME | D:\Program Files\Java\jdk1.8.0_152 | | Maven | **Apache Maven 3.9.5** | | Oracle | JDBC URL: jdbc:oracle:thin:127.0.0.1:1521:orcl, user: core | ## 重要 PowerShell 脚本执行策略禁止 npx用 cmd /c npx ... 绕过精度到了版本号、绝对路径不是写Java 8“——是写Java 1.8.0_152 (Oracle)。不是写Maven 3.x”——是写Apache Maven 3.9.5。不是写数据库Oracle——是写jdbc:oracle:thin:127.0.0.1:1521:orcl用户名core。每个参数都是精确的——不是随便写的近似值是你在这台电脑上实际跑通的配置。AI不需要猜测用户的JDK版本是什么它读到的是你的确切安装路径。容易踩坑的环境差异写进文档| **重要** | PowerShell 脚本执行策略禁止 npx用 cmd /c npx ... 绕过 |这一行不值得技术上分析半天——但AI在没有这条提示的时候会用npx playwright test直接跑然后报错。你不需要每次重新解释PowerShell需要cmd /c。写进文件里AI每次自己读。构建、测试、运行——命令可以直接复制## 构建 运行 # 编译 mvn compile -DskipTests -pl browise-platform -q # 测试 mvn test -pl browise-platform # 运行 mvn spring-boot:run -pl browise-demo不是用Maven编译项目——是完整的Maven命令。AI不用从这是一个Spring Boot项目推理出大概用mvn spring-boot:run启动——它直接拿到可执行的命令。项目结构——AI不是理解项目是能读到它## 项目结构 D:\work\browise\ ├── browise-common/ # 公共工具 ├── browise-crypto/ # SM2/SM3/SM4 加密 ├── browise-platform/ # 认证授权、JWT、缓存 ├── browise-formbuilder/ # 表单设计器后端 └── browise-vue/ # Vue 3 前端AI不是通过代码阅读理解项目结构的——你是直接告诉它每个模块是做什么的。你不需要让AI从代码里猜你写下来browise-crypto处理哪三个加密协议、browise-platform管认证和缓存。AI从你写的描述开始工作而不是从零开始猜。四、两级AGENTS的配合——从陌生人到熟悉项目用户添加了新项目 │ ▼ AI 读全局 AGENTS.md ├── 知道复杂任务先澄清、批量操作先验证单文件、不给废话注释 ├── 知道写代码后自动跑测试 └── 知道操作出错时停下来而不是反复尝试 │ ▼ AI 读项目 AGENTS.md ├── JDK 1.8.0_152路径 D:\Program Files\Java\jdk1.8.0_152 ├── Oracle 连 127.0.0.1:1521:orcl用户名 core ├── npx 必须用 cmd /c 绕过 PowerShell 限制 └── 后端用 mvn spring-boot:run -pl browise-demo 启动 │ ▼ AI 开始执行——不问环境问题、不问编码风格、直接按你的方式干活全局规范定义了跨项目的协作方式项目细节定义了这个项目的技术环境。换了项目全局规范不变只换项目细节——AI从第一次在项目上协作就知道你喜欢什么方式、这个项目应该怎么跑。五、这两份文件比README更基础README是给新人看的——“这个项目是做什么的、怎么部署”。AGENTS.md是给AI看的——“这个项目怎么在我的电脑上跑起来、跑测试、跑构建”。这份文件有一个功能README永远做不到AI不需要任何人工交互就能独自把这个项目从零跑到测试通过。这不是自动部署的级别——是任何一个新人或AI拿到这份文件都不需要再问你任何问题。不是AI变聪明了——是你把你每次给AI讲一遍的东西写成文件了。这两份AGENTS.md的价值不在技术内容本身——在它们每次替你回答AI问题的时候你少花了几十分钟的沟通成本。