网硕互联帮助中心两级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问题的时候，你少花了几十分钟的沟通成本。
评论前必须登录！
注册