AI 编程工程化实战：用项目级规则约束 Agent 的目录、修改边界与验证流程

前面几篇文章中，我们已经让 AI Agent 完成需求开发、多角色协作和线上 Bug 排查。但真正把 AI 用进日常开发后，很快会遇到一个反复发生的问题：

为什么同一个要求，每次开启新对话都要重新解释？

你告诉它后端不能直接修改数据库表，下一次它又生成了一段迁移脚本；你提醒它项目使用 pnpm，换个任务后它又执行 npm；你强调不要格式化整个文件，它却在修复一行代码时制造了几百行差异。

这并不一定是模型能力不足，而是项目中的隐性规则没有被写成 Agent 可以稳定读取的工程上下文。

本文将用一个典型的前后端项目为例，建立一套可复用的“项目级规则”：Agent 第一次进入仓库时先识别技术栈和目录，再确认修改边界，最后按风险选择验证方式。目标不是让 AI 记住更多内容，而是让它在关键位置少犯错。

文中的文件名和工具命令是通用示例。不同 AI 编程工具支持的规则文件名称可能不同，实际使用时应以所用工具的文档和仓库现状为准。

一、为什么只靠聊天提示词不够？

聊天中的要求通常只服务于当前任务。新开会话、切换工具或把任务交给另一个 Agent 后，这些信息未必会被继承。

更麻烦的是，开发规则往往分散在很多地方：

• README 介绍如何启动项目；
• package.json 记录前端命令；
• pom.xml 或 build.gradle 记录后端结构；
• CI 配置里才有真正执行的检查；
• 团队成员知道哪些模块不能碰，但文档里没有写；
• 某些目录还有自己的局部约束。

如果让 Agent 每次自行猜测，它可能做对，也可能把常见经验误当成当前项目事实。

项目级规则的作用，就是把那些高频、稳定、犯错代价较高的信息放到仓库中的固定入口。

二、项目级规则应该管什么？

一份有效的规则文件通常包含五层信息。

1. 项目地图

告诉 Agent 每个主要目录负责什么，例如：

server/       Java 后端服务
web/          Vue 前端应用
docs/         设计与接口文档
scripts/      本地辅助脚本
database/     经审核后执行的数据库变更

它不需要列出每个文件，但必须能帮助 Agent 快速判断任务应该从哪里开始调查。

2. 技术栈与工具

只写能够从仓库验证的事实：

后端：Java 17、Spring Boot、Maven
前端：Vue 3、TypeScript、pnpm
测试：JUnit、Vitest
格式化：遵循仓库已有配置

版本号容易变化。规则中如果写了版本，最好同时告诉 Agent 去哪个文件复核，而不是把一份旧文档当作永久真相。

3. 修改边界

这是最有价值的一层，例如：

• 修复缺陷时不得顺带重构无关模块；
• 不覆盖或回退其他人的未提交改动；
• 数据库脚本只允许生成草稿，未经授权不得执行；
• 不读取或输出密钥、令牌和生产配置；
• 修改公共接口前先检查调用方和兼容性；
• 同一文件存在不明改动时先调查归属。

4. 验证策略

明确什么改动需要什么验证：

改动类型	最低验证要求
文档与注释	检查格式、链接和事实一致性
前端局部改动	类型检查或目标测试，必要时浏览器验证
后端业务逻辑	相关模块测试及关键分支验证
数据访问层	SQL/Mapper 测试和兼容性检查
公共接口	编译、契约检查和调用方回归
高风险配置	明确人工确认，不自动部署

5. 交付格式

要求 Agent 最终说明：改了什么、为什么改、执行了哪些验证、结果如何、还有哪些未验证风险。

这能显著减少一句“已经完成”背后的信息缺口。

三、规则的核心不是“越长越好”

很多人第一次写规则文件，会把团队所有规范一次性塞进去，最后得到几千行内容。规则太长会产生两个问题：关键要求被淹没，旧规则长期无人维护。

更合理的分层方式是：

仓库根规则
  ├─ 全局安全边界
  ├─ 项目地图与通用验证
  ├─ server/ 局部规则
  │    └─ Java、接口、数据库约束
  └─ web/ 局部规则
       └─ Vue、组件、样式与浏览器验证

根规则只放所有任务都需要知道的内容，技术细节尽量靠近对应目录。这样前端 Agent 不必阅读大量数据库规范，后端 Agent 也不会被组件样式规则干扰。

如果工具不支持分层规则文件，也可以在根规则中放简短索引，要求处理某个模块前先读取对应的说明文档。

四、先让 Agent 自动调查，再生成规则草案

项目规则不应该凭空手写。第一次建立时，可以先让 Agent 做一次只读调查。

建议它依次检查：

1. 仓库根目录与主要模块；
2. README 和已有开发文档；
3. 依赖及构建配置；
4. CI 中实际运行的命令；
5. 测试目录及命名惯例；
6. 格式化、静态检查和提交规范；
7. 环境变量示例与敏感配置边界；
8. 最近几个同类实现的代码模式。

调查提示词可以这样写：

请只读调查当前仓库，为建立项目级 AI Agent 规则提供事实依据。

请确认：
1. 主要目录及职责；
2. 前后端技术栈和版本来源；
3. 包管理、构建、测试、格式化命令；
4. CI 实际执行的检查；
5. 现有文档中的开发约束；
6. 数据库、部署、密钥等高风险操作边界；
7. 是否存在嵌套模块或多份项目副本风险。

每条结论必须附带来源文件。无法从仓库验证的内容标记为“待人工确认”，不要根据常见项目经验补全。
本阶段禁止修改文件、安装依赖或执行构建。

这一步非常关键：先收集事实，再写规则；不要先想象规则，再去寻找支持它的证据。

五、一份可直接改造的根规则模板

不同工具可能使用不同入口文件。下面重点展示内容结构，你可以把它放入当前工具能够自动读取的项目规则文件中。

# 项目级 Agent 规则

## 语言与沟通
- 默认使用简体中文说明分析、改动和验证结果。
- 代码标识符遵循项目既有命名，不强行中文化。

## 项目地图
- `server/`：后端服务。
- `web/`：前端应用。
- `docs/`：项目文档。
- 修改前先定位真实模块，不按历史路径猜测。

## 工作原则
- 先调查现有实现，再提出修改方案。
- 只修改完成当前任务所必需的文件。
- 不覆盖、不回退来源不明的现有改动。
- 优先复用项目已有模式，不另造一套架构。
- 不把推测写成已经验证的事实。

## 高风险边界
- 未经明确授权，不执行数据库写操作、部署、发布或远程提交。
- 不读取、输出或提交密钥、令牌和真实生产配置。
- 删除、覆盖、批量移动文件前必须确认准确目标和影响范围。

## 验证
- 根据改动风险选择最小但充分的验证。
- 报告实际执行的命令和结果。
- 无法验证时明确说明原因、影响和人工检查方式。
- 不通过删除测试、放宽断言或隐藏错误制造成功。

## 最终交付
- 列出修改文件及作用。
- 总结关键实现与兼容性考虑。
- 列出验证证据、失败项和未验证风险。

这份模板故意没有写死具体命令，因为命令应该从真实项目配置中提取。

六、后端局部规则应该补充什么？

假设 server/ 是 Java 后端，可以增加：

# 后端模块规则

- 修改接口前检查 Controller、Service、数据访问层和调用方。
- 新增参数默认考虑旧客户端未传参数时的兼容行为。
- Mapper 参数名必须与方法签名和 XML 引用一致。
- 动态 SQL 要验证空值、组合条件、分页和权限过滤。
- 数据库结构以迁移文件和实际映射为依据，不根据字段名猜测。
- 数据库变更只生成脚本和影响说明，未经授权不执行。
- 优先运行目标模块测试；扩大到完整构建前评估时间和影响。

这类规则不是 Java 教程，而是项目中最容易重复踩坑的检查清单。

七、前端局部规则应该补充什么？

假设 web/ 使用 Vue 和 TypeScript，可以增加：

# 前端模块规则

- 使用仓库锁定的包管理器，不混用 npm、yarn 和 pnpm。
- 优先复用现有组件、请求封装和类型定义。
- 修改筛选条件时检查重置、分页、空值和请求参数传递。
- 不为局部功能改动格式化整个页面文件。
- 视觉修改需在真实页面验证关键状态，不能只根据源码推断。
- 至少覆盖加载、空数据、正常数据、错误和禁用状态中相关的场景。
- 不在前端写入密钥或把服务端权限判断替换为界面隐藏。

八、把“必须”写成可执行规则

模糊规则对 AI 的帮助很有限。

下面这类写法看似正确，实际上无法执行：

保证代码质量。
注意安全。
充分测试。
不要乱改。

更好的写法是：

模糊要求	可执行规则
保证质量	修改后执行与风险匹配的测试，并报告实际结果
注意安全	不读取或输出密钥；外部写操作必须获得授权
充分测试	覆盖原场景、相邻边界和旧行为兼容性
不要乱改	只修改任务必需文件，不进行无关重构和全文件格式化
先了解项目	修改前读取入口、调用链和最近的同类实现

判断规则是否有效，可以问一句：任务结束后，能否根据输出判断 Agent 有没有遵守它？

如果无法判断，这条规则大概率仍然太抽象。

九、不要让规则文件变成过期知识库

项目级规则也会过期。例如包管理器从 npm 切到 pnpm，Java 版本升级，旧模块被拆分，测试命令发生变化。如果规则和源码冲突，Agent 可能稳定地做错事。

建议建立一个简单维护闭环：

1. Agent 执行任务时发现规则与仓库不一致；
2. 在交付报告中指出冲突和证据；
3. 人工判断是代码异常还是规则过期；
4. 单独修改规则并进行审查；
5. 后续任务验证新规则是否解决问题。

不要允许 Agent 在执行普通需求时悄悄修改规则文件。规则变化会影响之后所有任务，应该作为独立变更进行审查。

十、哪些内容不应该写进规则文件？

1. 密钥和真实账号

规则可以说明密钥从哪里安全注入，但不能保存真实密钥、Cookie、数据库密码或个人信息。

2. 一次性任务细节

“本周修复用户筛选 Bug”不属于长期规则，应放在任务描述或需求文档中。

3. 无法验证的绝对断言

例如“这个接口绝不会被旧客户端调用”。如果没有证据，这种规则只会放大风险。

4. 大段通用编程常识

规则文件的上下文很宝贵。与项目无关的教程、语言百科和冗长价值观应删除。

5. 相互冲突的要求

一处要求“每次修改都执行完整构建”，另一处又要求“默认不要运行耗时命令”，Agent 将难以判断优先级。规则应该说明适用范围和例外条件。

十一、规则冲突时如何决定优先级？

可以在项目规则中明确以下顺序：

当前用户对本任务的明确要求
  → 安全与权限边界
  → 当前目录的局部规则
  → 仓库根规则
  → 普通文档和历史示例
  → Agent 的通用经验

不过，用户要求也不能自动授权明显超出任务范围的高风险操作。遇到删除数据、发布生产、发送外部消息等动作时，仍应核对目标和授权。

当源码与规则中的事实描述不一致时，不应偷偷选择其中一个。正确做法是报告冲突，使用更接近当前运行状态的证据，并建议更新过期规则。

十二、如何验证规则真的有效？

不要只看 Agent 是否回复“我已阅读规则”，而要设计几个小任务观察行为。

测试一：局部缺陷修复

给它一个只需修改一个文件的问题，观察是否出现无关重构、全文件格式化或额外依赖。

测试二：跨前后端小需求

观察它是否先确认接口契约，是否检查参数的完整传递链路。

测试三：数据库相关需求

观察它是否只生成脚本和说明，而不是未经授权直接执行。

测试四：存在未提交改动

观察它是否保留其他人的修改，并把重叠风险报告出来。

测试五：无法完成的验证

人为制造一个缺失依赖的环境，观察它是否如实报告，还是声称“应该通过”。

可以记录以下指标：

• 重复提醒同一规则的次数；
• 无关文件改动数量；
• 命令或项目目录选择错误次数；
• 交付报告中的未验证项是否完整；
• 人工返工和代码审查问题数量。

规则是否有效，最终应体现在错误率和沟通成本上，而不是文件写得多么漂亮。

十三、一份完整的“首次进入仓库”提示词

你将处理一个不熟悉的项目。开始修改前，请完成以下步骤：

1. 确认当前实际工作目录和仓库边界；
2. 读取适用于根目录及目标模块的项目级规则；
3. 查看项目地图、依赖配置、构建命令、测试和 CI 配置；
4. 定位与任务直接相关的入口、调用链和现有同类实现；
5. 汇总已确认事实、待确认问题、计划修改文件和验证方案；
6. 发现不明的现有改动时保留它，不得覆盖或回退；
7. 只实施任务必需的最小改动；
8. 完成后报告修改内容、实际验证结果和未验证风险。

不要根据其他项目的经验猜测当前项目结构、命令或业务规则。
涉及数据库写入、部署、发布、删除或外部发送时，必须先确认授权与准确目标。

十四、写在最后

一个优秀的 AI Agent 不只是会生成代码，还应该知道在当前项目里什么能做、什么不能做、做完如何证明。

项目级规则的价值，不是用更多文字控制 AI 的每一个动作，而是把团队反复强调的边界变成稳定、可检查的工程资产：

把项目事实写清，把风险边界写窄，把验证结果写实。

当 Agent 每次进入仓库都能先读地图、再查证据、后改代码，它才真正从一次性聊天工具变成可以融入团队流程的开发助手。

下一篇可以继续实战：如何搭建一条 AI Agent 自动代码审查流水线，让每次提交都经过风险分级和证据化检查。