过去一年，AI Agent 在软件工程中的角色变化很快。
它已经不只是“帮忙补一段代码”的工具，而是开始参与需求拆解、代码修改、测试验证、文档沉淀，甚至跨仓排障。能力越强，越容易让团队产生一个错觉：只要模型足够聪明，就可以把更多工作直接交给它。
真实落地后我们发现，问题往往不在“Agent 不会写”，而在“Agent 写得太快，但上下文错了”。
在一个典型多仓工程中，可能同时存在前端 React 仓、Node Agent Runtime 仓、Go 服务仓、iOS 仓、安卓仓、回调中转仓、文档与架构决策区。不同仓库负责不同运行边界，验证方式也完全不同。如果没有规范治理，Agent 很容易在看似合理的路径上越走越偏。
这篇文章分享的是一套从实际工程里沉淀出来的 AI Agent 规范治理方法：让 Agent 不只是“能用”，而是逐步变得可靠、可验证、可协作、可扩展。
1. 先承认一个现实：Agent 需要被工程化管理
很多团队第一次接入 AI Agent，会把重点放在模型能力、Prompt 技巧和工具权限上。但进入实际项目后，最先暴露的通常是治理问题。
常见问题包括：
| 问题 | 表现 | 后果 |
|---|---|---|
| 规则分叉 | 不同工具入口里维护了不同说明 | Agent 行为不一致，协作口径漂移 |
| 仓库误判 | 前端问题改到了服务端，Runtime 问题改到了客户端 | 引入跨层副作用 |
| 证据不足 | 没有复现、日志、测试或调用链，就直接改代码 | 看似修复，实际没有覆盖问题 |
| 验证错位 | 只跑了无关检查，就声称任务完成 | 交付可信度下降 |
| 经验流失 | 一次排障结束后，没有沉淀到规范或知识库 | 下次继续踩同样的坑 |
这些问题本质上不是模型问题，而是工程协作问题。
所以，Agent 规范治理的目标不是限制 AI，而是给 AI 建立工程化工作条件：它应该知道从哪里开始读、应该进入哪个仓、哪些边界不能越过、什么时候需要确认、最终如何证明结果。
2. 第一条原则：建立唯一规范源
如果团队同时使用多个 AI 工具，不同工具往往有自己的入口目录、技能目录或项目说明文件。早期为了方便，大家可能会在每个入口里各写一份规则。短期看很快，长期看一定会漂移。
更稳妥的做法是建立“唯一规范源”：
- 所有真实规则只在一个规范源目录中维护。
- 工具专用入口只作为适配层存在。
- 适配层可以复制、引用或生成，但不能反向成为规则源。
- 人类可读文档用于解释治理体系，不替代规范源。
这个设计有一个非常朴素的好处：当规则发生变化时，团队知道应该改哪里；当工具行为不一致时，也知道应该回到哪里排查。
3. 第二条原则：把“该进哪个仓”显式化
多仓工程里，Agent 最容易出错的地方就是任务路由。
人类工程师看到一个问题，通常会结合经验判断它属于哪个系统。但 Agent 如果只看到片段上下文，很容易把相邻概念混在一起。例如用户说“页面没有响应”，问题可能在前端 React 仓，也可能在 Node Agent Runtime 仓的接口返回，还可能在移动端容器的加载策略。
治理方式是把仓库边界写成显式路由表。
| 技术栈仓库 | 主要职责 | 典型验证 |
|---|---|---|
| 前端 React 仓 | Web 页面、交互体验、前端 API client、H5 运行容器 | 类型检查、组件测试、浏览器验证 |
| Node Agent Runtime 仓 | Agent 编排、模型调用、工具执行、任务状态流转、服务端事件流 | 单元测试、集成测试、运行时日志 |
| Go 服务仓 | 稳定业务 API、数据库访问、缓存、对象存储等后端能力 | Go 测试、接口测试、构建检查 |
| iOS 仓 | iOS WebView 容器、Native Bridge、签名与包内资源加载 | 本地构建、真机或模拟器验证 |
| 安卓仓 | Android WebView 容器、Gradle 构建、Native Bridge、静态资源加载 | Gradle 检查、设备验证 |
| 外部系统回调中转仓 | 第三方系统事件接收、参数校验和页面中转 | 页面构建、端到端回调测试 |
| 架构与文档区 | 跨仓设计、长期决策和架构决策记录 | Markdown 检查、链接和事实源核对 |
路由表不是给人看的摆设，而是给 Agent 的“第一判断”。每次任务开始时，Agent 应先确定 Route，再决定读取哪些模板、知识库、源码和测试。
显式路由的价值，是把“凭经验猜”变成“按规则进入上下文”。
4. 第三条原则：把事实、规则和能力分开
很多团队会把所有内容都塞进一个巨大 Prompt：项目背景、编码规范、排障流程、命令说明、测试要求、业务边界，全部堆在一起。这样做的问题是，文档会越来越长，Agent 也很难判断哪些内容是事实、哪些是方法、哪些是一次性提醒。
更好的拆法是分层：
可以简单理解为：
- 规则层回答“什么必须遵守”。
- 路由层回答“这个任务属于哪里”。
- 知识层回答“项目事实是什么”。
- 能力层回答“Agent 应该用什么方法做”。
- 命令层回答“怎样执行和验证”。
这种分层的好处，是每类内容都有自己的维护位置。项目事实变化时，不需要改技能；调试方法升级时，也不需要改仓库边界。
5. 第四条原则：适配不同工具，但不要让适配层变成第二套规范
实际团队很可能同时使用多种 AI 工具。不同工具读取上下文的方式不一样，有的偏向项目入口文件，有的偏向技能目录，有的支持 MCP，有的支持本地脚本。
这时候不要强迫所有工具读取同一种目录结构，也不要为每个工具手写一份规则。更好的方法是：
- 维护一个统一规范源。
- 为不同工具生成或维护轻量适配入口。
- 用一致性检查保证适配入口没有漂移。
- 在适配入口里明确标注“不要手工编辑”。
适配层的定位要非常克制：它是让工具读懂规范的翻译层，不是新的规范中心。
6. 第五条原则：用修改前 Manifest 控制上下文漂移
Agent 执行任务时，最危险的不是它慢，而是它在错误上下文里很快。
因此，我们引入一个简单但非常有效的机制：修改前 Manifest。
在真正写文件前，Agent 需要向用户说明：
- 当前任务归属哪个仓库或模块。
- 已经读取了哪些具体文件或证据。
- 当前判断基于什么事实。
- 预计修改哪些文件。
- 哪些边界不会改。
- 准备用什么命令或方式验证。
任务：修复某页面操作后无响应
目标：前端 React 仓
证据：浏览器复现、组件调用链、相关测试
预计修改：页面组件和对应 hook
不应改动：Node Agent Runtime 仓、Go 服务仓、移动端容器仓
验证：组件测试 + 浏览器复现路径
这个机制的价值不在于形式，而在于让边界提前暴露。用户可以在 Agent 写代码前发现：它是否进错仓、是否证据不足、是否准备修改过多文件、验证是否不能覆盖原始问题。
7. 第六条原则：验证要证明原始目标，而不是证明“项目没坏”
很多工程团队都有类似经验：一次改动跑了 lint，也跑了构建，但用户反馈的问题仍然存在。原因是验证没有对齐原始目标。
Agent 协作里，这个问题会更明显。因为 Agent 很容易把“某个检查通过”当作“任务完成”。
更可靠的验证思路是：
| 原始任务 | 合格验证 | 不够的验证 |
|---|---|---|
| 修复按钮点击无响应 | 复现路径通过，点击后请求或状态变化符合预期 | 只跑类型检查 |
| 修复服务端任务状态异常 | 覆盖状态流转测试，日志和接口结果符合预期 | 只跑前端构建 |
| 修复移动端加载失败 | 真机或模拟器能加载目标资源，错误日志消失 | 只检查 Web 页面 |
| 修改 Agent 调用链 | 相关工具执行、异常恢复和事件流都被覆盖 | 只看单个函数测试 |
验证闭环应该回答一个问题：用户最初要解决的问题，是否被证据覆盖了？
8. 第七条原则：把经验沉淀成可复用资产
Agent 治理不是一次性文档工程。真正有价值的是，在日常协作中持续把稳定经验沉淀下来。
沉淀可以分为几类：
| 经验类型 | 示例 | 建议沉淀位置 |
|---|---|---|
| 稳定事实 | 仓库职责、接口边界、运行环境 | 项目知识库 |
| 工作方法 | 调试流程、代码审查方法、TDD 约定 | Agent 技能 |
| 命令流程 | 启动、检查、同步、构建、发布前验证 | 命令说明 |
| 架构决策 | 为什么拆分某个仓，为什么禁用某类方案 | 架构文档 |
| 协作规则 | 什么时候必须确认，什么时候不能写文件 | 规范源 |
但沉淀也要克制：临时猜测、一次性本地状态、未验证结论、敏感信息，都不应该进入长期文档。
一个实用原则是：每次任务结束时，Agent 可以判断是否出现了可复用经验；如果有，只提出沉淀建议，由人类确认后再写入长期资产。
9. 一套可复制的落地路径
如果一个团队想从零开始做 AI Agent 规范治理，可以按下面的顺序推进：
这条路径不要求一开始就做得很重。可以先从三件事开始：
- 明确唯一规范源。
- 写清仓库职责和任务路由。
- 要求 Agent 修改前说明边界和验证计划。
只要这三件事做到位，Agent 协作的可控性就会明显提升。
10. 最后：不要把 Agent 当魔法，要把它纳入工程系统
AI Agent 的上限来自模型能力，但下限来自工程治理。
没有治理的 Agent，可能短期很快，长期却会带来上下文漂移、规则分叉和验证缺口。有治理的 Agent，才有机会成为团队稳定协作的一部分。
我们最终要构建的不是“更长的 Prompt”，而是一套工程系统：
- 有唯一可信的规则源。
- 有清晰的仓库和模块边界。
- 有面向任务的上下文路由。
- 有适配不同工具的入口层。
- 有修改前可见的边界说明。
- 有对齐原始目标的验证闭环。
- 有持续沉淀经验的机制。
当这些基础设施建立起来，Agent 才能从“能用”走向“可靠”，从“个人效率工具”走向“团队工程能力”。
