从能用到可靠：AI Agent 规范治理的工程实践

过去一年，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 需要向用户说明：

当前任务归属哪个仓库或模块。
已经读取了哪些具体文件或证据。
当前判断基于什么事实。
预计修改哪些文件。
哪些边界不会改。
准备用什么命令或方式验证。

text 复制代码

任务：修复某页面操作后无响应
目标：前端 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 才能从"能用"走向"可靠"，从"个人效率工具"走向"团队工程能力"。