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

过去一年里，AI智能体在软件工程领域的职能演进速度，确实超出了绝大多数人的预料。

它早已不再是那个仅用于“帮忙补写一段代码”的辅助工具。如今，它已开始涉足需求拆解、代码重构、自动化测试、文档编写，甚至跨仓库的问题排查。随着能力的增强，团队很容易产生一种错觉：只要模型足够强大，就能把越来越多的工作直接交给它处理。

然而，当真正将智能体部署到实际生产线时，问题便开始显现：并非智能体写不出代码，而是它写得过快，导致上下文却出现了错误。

在典型的多仓库工程项目中，可能同时存在前端React仓库、Node Agent Runtime仓库、Go服务仓库、iOS仓库、安卓仓库、回调中转仓库以及架构文档区。每个仓库的工作边界和验证方法都完全不同。如果缺乏一套规范的治理手段，智能体很容易沿着一条看似合理的路径，逐渐走向偏离。

下面这套框架，是从实际工程经验中反复打磨出的AI智能体规范治理体系。其核心目标只有一个：让智能体不仅仅是“可用”，而是逐步变得可靠、可验证、可协作、可扩展。

1. 首先，承认一个现实：智能体需要被工程化地管理

许多团队最初引入AI智能体时，焦点往往集中在模型能力、提示词技巧和工具权限上。但是，一旦接入真实项目，最先暴露的问题往往是治理层面的。

常见问题包括：

这些问题本质上并非模型本身的缺陷，而是工程协作上的不足。

因此，智能体规范治理的目标不是限制AI，而是为AI建立一套可工程化的工作条件。它需要明确：从哪里开始阅读、应进入哪个仓库、哪些边界不可逾越、何时需要确认，以及最终如何证明它已完成任务。

2. 第一条原则：建立唯一的规范源

如果一个团队同时使用多种AI工具，每个工具通常都有自己的入口目录、技能目录或项目说明文件。早期为了方便，大家可能会在每个入口都写一份规则。短期看，这样做确实很快，但从长远看，必然会导致规则漂移。

更稳妥的做法是建立一个“唯一的规范源”：

• 所有真实规则仅在一个规范源目录中维护。
• 各工具专用的入口仅作为适配层存在。
• 适配层可以复制、引用或生成规则，但绝不能反向成为规则源。
• 人类可读的文档用于解释治理体系，但不替代规范源。

这样设计有一个非常朴素的好处：当规则需要变更时，团队清楚地知道应该修改哪里；当工具的行为不一致时，也能迅速回溯到源头进行排查。

3. 第二条原则：将“该进入哪个仓库”显式化

在多仓库工程中，智能体最容易出错的地方是任务路由。

人类工程师遇到一个问题，通常能根据经验判断它属于哪个系统。但智能体如果只看到片段的上下文，很容易混淆相邻的概念。例如，用户反馈“页面没有响应”，问题可能出现在前端React仓库，也可能是Node Agent Runtime仓库的接口返回异常，或移动端容器的加载策略不当。

治理方式其实很简单：将仓库边界编写成一张显式的路由表。

这张路由表并非给人看的摆设，而是为智能体提供的“第一判断依据”。每次任务开始时，智能体应首先确定路由，再决定读取哪些模板、知识库、源码和测试。

显式路由的核心价值在于，将“凭经验猜测”转变为“按规则进入正确上下文”。

4. 第三条原则：将事实、规则和能力分开管理

许多团队会将所有内容都塞进一个巨大的提示词中：项目背景、编码规范、排障流程、命令说明、测试要求、业务边界……全部堆砌在一起。但这样做，文档会越来越长，智能体也难以分辨哪些是事实、哪些是方法、哪些是一次性提醒。

更好的做法是分层管理：

• 规则层：回答“什么必须遵守”。
• 路由层：回答“这个任务属于哪里”。
• 知识层：回答“项目事实是什么”。
• 能力层：回答“智能体应该用什么方法执行”。
• 命令层：回答“如何执行与验证”。

这种拆分的好处是，每类内容都有其独立维护的位置。当项目事实发生变化时，无需修改技能；当调试方法升级时，也无需调整仓库边界。

5. 第四条原则：适配不同工具，但不让适配层成为第二套规范

实际团队可能会同时使用多种AI工具。不同工具读取上下文的方式各不相同，有的偏向项目入口文件，有的偏向技能目录，有的支持MCP协议，有的支持本地脚本。

此时，不要强迫所有工具都去读取同一套目录结构，也不应为每个工具手写一份独立的规则。更好的方法是：

1. 维护一个统一的规范源。
2. 为不同工具生成或维护轻量级的适配入口。
3. 通过一致性检查，确保适配入口未发生漂移。
4. 在适配入口中明确标注“请勿手工编辑”。

适配层的定位必须非常克制：它只是让工具理解规范的翻译层，而非新的规范中心。

6. 第五条原则：通过修改前 Manifest 控制上下文漂移

智能体在执行任务时，最危险的情况不是它速度慢，而是它在错误的上下文里执行过快。

为此，我们引入了一个简单但极其有效的机制：修改前 Manifest。

在真正写入文件之前，智能体需要先向用户说明：

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

任务：修复某页面操作后无响应
目标：前端 React 仓
证据：浏览器复现、组件调用链、相关测试
预计修改：页面组件和对应的 hook
不应改动：Node Agent Runtime 仓、Go 服务仓、移动端容器仓
验证：组件测试 + 浏览器复现路径

这个机制的价值不在于形式，而在于让边界问题提前暴露。用户可以在智能体编写代码之前，就发现它是否进错了仓、证据是否不足、是否计划修改过多文件、以及验证方案是否无法覆盖原始问题。

7. 第六条原则：验证需证明原始目标，而非证明“项目没坏”

许多工程团队都有类似经历：一次改动通过了 lint 检查，也通过了构建，但用户反馈的问题依然存在。原因就在于验证没有对齐原始目标。

在智能体协作中，这个问题会更加突出。智能体很容易将“某项检查通过”等同于“任务完成”。

更可靠的验证思路是：

验证闭环应回答一个核心问题：用户最初要解决的问题，是否已被证据充分覆盖？

8. 第七条原则：将经验沉淀为可复用的资产

智能体治理并非一次性的文档工作。其真正价值在于，在日常协作中持续将稳定的经验沉淀下来。

沉淀可以分为以下几类：

但沉淀也必须有所克制：临时的猜测、一次性的本地状态、未经验证的结论以及敏感信息，都不应进入长期文档。

一个实用的原则是：每次任务结束时，智能体可以判断是否出现了可复用的经验；如果是，仅提出沉淀建议，由人类确认后，再写入长期资产中。

9. 一套可复制的落地路径

如果某个团队希望从零开始构建AI智能体规范治理，可以按以下顺序推进：

这条路径并不要求一开始就做得过于沉重。可以从三件事开始：

1. 明确唯一的规范源。
2. 清晰定义仓库职责和任务路由。
3. 要求智能体在修改前说明边界和验证计划。

只要这三件事落实到位，智能体协作的可控性将得到显著提升。

10. 最后：不要把智能体当作魔法，而要将其纳入工程系统

AI智能体的上限来自于模型能力，但它的下限取决于工程治理水平。

缺乏治理的智能体，可能在短期内效率很高，但长期来看，必然会导致上下文漂移、规则分叉和验证缺口。而有良好治理的智能体，才有机会成为团队稳定协作的一部分。

我们最终要构建的，并非“更长的提示词”，而是一套完整的工程系统：

• 拥有唯一可信的规则源。
• 拥有清晰的仓库和模块边界。
• 拥有面向任务的上下文路由。
• 拥有适配不同工具的入口层。
• 拥有修改前可见的边界说明。
• 拥有对齐原始目标的验证闭环。
• 拥有持续沉淀经验的机制。

当这些基础设施建立起来后，智能体才能从“可用”走向“可靠”，从“个人效率工具”演变为“团队工程能力”。