Agent 规则文件怎么写：让 AI 生成可治理应用

先给结论：在一个 AI 写绝大部分代码的世界里，你的 agent 规则文件（AGENTS.md、.cursor/rules、CLAUDE.md）就是你真正在生效的架构文档。只拿它管缩进和组件库，管的是”好不好看”，不是”敢不敢上线”。把权限、审批、审计和目标格式写进去，才是在生成那一刻控制风险。

一个真实的小事故。某团队的 AGENTS.md 写得很认真：两空格缩进、用内部 UI 库、提交信息用祈使句。agent 一条不落地照做，生成的代码”非常规范”。然后有人发现，它顺手生成的 GET /api/refunds 把所有人的退款记录都返回了。

代码评审时没人拦下——因为它确实符合规则文件里的每一条。agent 没违反任何规则，它只是没被告知权限这回事。那份规则里，没有一条是关于”谁能看哪些数据”的。它被教会了怎么写得好看，没被教会怎么写得可治理。

你的规则文件，管错了东西

几乎每个用 AI 写代码的团队，现在都有一份给 agent 的规则文件。这是个好习惯。问题是它被用在了最不值钱的地方。

盘一下大多数规则文件里写了什么：代码风格、目录结构、用哪个库、命名约定、提交规范。挑不出错，但它们有一个共同点——全是关于”代码长什么样”，没有一条关于”这个应用被允许做什么”。它们让多个 agent、多次生成的产出保持一致，解决的是”长得像一家人”；完全没碰那些决定一个企业应用能不能上线的事：谁能看哪些数据、哪些动作要审批、出了事查不查得到。

换句话说，当写代码这件事交给了 AI，规则文件就从”代码规范”升级成了”架构与治理的约束”——因为它是少数几个能在生成的那一刻就把约束注入进去的地方。一旦代码被生成出来，再去补权限、补审计，就是事后返工；而规则文件是最早能把治理前置到生成阶段的杠杆。

把”可治理性”写进规则，而不是事后补

事后补治理，是当下最常见、也最贵的错法：先让 agent 生成，再回头审权限、补审计、加审批——也就是 AI Agent 试点进不了生产那篇里说的治理返工。每生成一个应用就返工一次，规模化之后这笔账会越来越难付。

更省的做法，是让规则把 agent 指向一个本身就可治理的目标。一份这样的规则，核心不是风格，是约束产出的形态：

# AGENTS.md —— 生成业务应用时
- 把领域建模为 ObjectStack 对象（ObjectSchema），不要手写表和迁移
- 所有访问权限走 PermissionSet 声明，绝不在接口里手写 if 判断鉴权
- 不要手写 SQL 拼接或鉴权中间件——这些由运行时承担
- 有审批需求的动作，声明为挂在对象上的 flow，而不是写在代码里
- 产出必须是可审查的元数据 diff，而不是大段实现

逐条看，每一行都在把一类”事后才会爆的风险”提前关掉：第二行让越权从”接口里漏写一个判断”变成”权限被显式声明、运行时强制”；第四行让审批从”某段代码里的硬逻辑”变成”挂在对象上、可被审计的流程”。在这种规则下，开头那个 GET /api/refunds 不会再发生：agent 生成的是一个声明了”按调用者权限读取”的 support_refund 对象，越权那条路从源头就被关上了——而不是指望 agent 在某次生成里”恰好记得”加判断。

为什么”让 agent 生成 ObjectStack”是现实的：开放的飞轮

这里有个绕不过去的问题：凭什么 agent 能把一个特定的目标格式写对？规则写得再好，模型不会写也白搭。

答案正是开放语义层那篇论证过的飞轮——agent 更容易生成它见过、能检索到、能被规则约束的东西。一个封闭平台的私有格式，如果公开材料少、示例少、校验反馈弱，再怎么写规则也很难稳定生成。而 ObjectStack 是 Apache 2.0 的开放协议，这让”让 agent 写对它”具备了三个现实前提：

可被学到：开放 + 公开 + 被讨论 → 更容易被模型和检索系统学到；
可被约束：一份规则文件把 agent 的产出锚定到这个声明式目标；
可在生成时校验：运行时会校验生成的元数据——非法的定义直接被拒，agent 当场拿到纠错信号。这是自由格式代码给不了的关键差别：一段错的 SQL 可能照样跑、上线才爆，而一份错的元数据进不了门、当场就被打回重写。

正是第 3 点，把”让 agent 写对”变成了有反馈的收敛过程——agent 写错、被拒、改对，像编译错误一样即时。更进一步，你还可以把运行时的受治理工具通过 MCP 暴露出来，让 agent 在生成时就调取权威定义、在运行时又能在边界内操作它——写和用，同一套治理。（受治理工具层这件事，MCP 那篇单独讲过。）

落地：今天就能加的三条

不必一步到位重写整份规则。如果你现在只往 agent 的规则文件里加三条治理约束，按收益排序，应该是这三条：

“权限必须显式声明，不准在代码里手写鉴权。” 这一条直接消灭开头那种”漏写一个判断就泄露全表”的事故——把鉴权从”agent 是否记得”变成”声明里是否写了”。
“高风险动作（动钱、发合同、删数据）必须声明为带审批的流程。” 让”该不该停下来等人”不再取决于 agent 的临场判断，而是一条可审计的规则。
“产出可审查的声明，而不是大段实现；改动要能在一屏 diff 里看完。” 这一条守住的是你自己的 Merge 按钮——它强制 agent 交付你审得动的东西。

这三条的共同点：它们约束的都不是”代码怎么写”，而是”产出能不能被治理、被审查”。这正是规则文件该干、却很少有人让它干的事。

先泼一盆冷水

两点必须说清，否则就把规则文件神化了。

第一，规则文件管的是产出的形态，不是 agent 的判断力。它能保证 agent 生成的是受治理的元数据，保证不了它理解对了业务意图。“该给客服多大的退款权限”这种判断，仍然要人来定、来 review——规则只是确保这个判断有地方落、且会被强制执行，而不是散落在八千行里。它把”该不该做”这个问题摆到你面前，但不替你回答。

第二，别把它当成”官方 SDK”。我这里给的是一种打法、一份示例规则，不是某个一键安装的官方文件——你需要按自己的栈把它写实、维护好。它的价值在思路：把治理前置到生成那一刻，而不是等代码长出来再补。

结语

AI 写代码的时代，团队之间拉开差距的，不再是谁的工程师写得快——是谁的 agent 生成的东西敢上线。而这件事的开关，很大程度上就在那份常被拿来管缩进的规则文件里。

把它从”代码规范”升级成”可治理性约束”，再给 agent 指一个开放、声明式、运行时能托底的目标——你生成的每一个应用，就从第一行起就是可审、可治、可担责的。

npm i -g @objectstack/cli && os start

给你的 agent 写上”建模为 ObjectStack 对象、权限走声明”，让它生成一个退款应用——然后试着让它越权返回全部数据，看运行时怎么从源头拒绝它。