AI Agent 规则系统设计指南 V2
面向 Codex、Claude、Gemini、Copilot 等 AI 编程代理 一套用于构建可预测、可控、可验证、可扩展 AI 行为的工程化规则系统
1. 背景与问题
随着 AI 编程代理（AI coding agents）在工程中的普及，一个典型项目往往会同时使用多个工具，例如：
- Claude Code
- OpenAI Codex
- Gemini Code Assist
- GitHub Copilot
这些工具通常会读取仓库中的规则文件（如 AGENTS.md、CLAUDE.md、instructions 等）来指导行为。
1.1 现实问题
在实际工程中，规则往往呈现以下状态：
- 多个规则来源并存（AGENTS、CLAUDE、工具私有目录等）
- 不同 agent 加载方式不同
- 规则更新不同步
- 无法确认规则是否被真正加载
- 无法保证规则被严格执行
最终导致：
同一任务，在不同 agent 或不同上下文中，行为不一致且不可预测
1.2 问题本质
问题不在于“有没有规则”，而在于：
规则是否能够被稳定加载、正确理解、实际执行，并可被验证
2. 设计目标
本指南的目标是构建一套工程级规则系统，而不仅是文档结构。
系统必须具备以下能力：
2.1 可预测性（Predictability）
在相同上下文下，不同 AI agent 的行为应尽可能一致。
2.2 可控性（Control）
规则修改后，应能够稳定影响 agent 行为，而不是“可能生效”。
2.3 可验证性（Verifiability）
必须能够回答：
- 哪些规则被加载？
- 哪些规则被覆盖？
- agent 是否遵守规则？
2.4 可扩展性（Scalability）
规则系统可以增长，但必须：
- 不引发上下文失控
- 不导致规则冲突
- 不降低执行一致性
3. 核心思想
V2 的核心思想是：
规则系统不是文档集合，而是一个工程系统
该系统包含四个协同部分：
1. Source（规则源）
2. Compile（编译分发）
3. Enforce（执行与强制）
4. Verify（验证与审计）
4. 总体架构
推荐结构如下：
repo/
├─ AGENTS.md
├─ CLAUDE.md
├─ GEMINI.md
│
├─ agents/ # 唯一规则事实来源
│ ├─ core/
│ ├─ conventions/
│ ├─ modules/
│ └─ skills/
│
├─ agents-compiled/ # 编译产物（各 agent 入口）
│
├─ agents-runtime/ # 执行与强制层
│
├─ scripts/ # 编译与工具
│
└─ docs/
5. 核心原则
原则 1：单一事实来源
所有项目规则必须集中在：
agents/**
其他文件（AGENTS.md、CLAUDE.md 等）不得成为独立规则来源。
原则 2：入口文件是“投影”，不是来源
不同 AI agent 使用不同入口文件。
因此：
AGENTS.md / CLAUDE.md / GEMINI.md 是规则的“投影”，而不是规则本身
这些文件应由规则源生成，而不是手动维护。
原则 3：规则与执行分离
规则系统必须区分：
- 规则（What is correct）
- 执行（How to do）
- 强制（Must happen）
原则 4：软约束与硬约束分离
软约束（Soft Constraints）
通过文本规则表达，例如：
- 设计原则
- 编码风格
- 架构约定
硬约束（Hard Constraints）
必须通过执行机制实现，例如：
- 测试必须通过
- 禁止危险命令
- 必须执行 lint
- 禁止修改关键文件
原则 5：规则必须可验证
每条关键规则都应能回答：
如何验证该规则是否被遵守？
原则 6：按需加载（控制上下文）
不是所有规则都应常驻上下文。
规则必须支持：
只在需要时加载
6. Source Layer（规则源）
agents/** 是系统唯一事实来源。
6.1 core（全局规则）
用于定义：
- 架构约束
- 安全边界
- 验证标准
- 思维模型
特点：
- 全局适用
- 稳定
- 高频
6.2 conventions（实现约定）
用于定义：
- API 设计
- 数据访问
- 测试方式
- 代码结构
特点：
- 高频使用
- 可演化
6.3 modules（领域例外）
仅在存在领域特殊性时使用，例如：
- 特殊状态机
- 权限模型
- 数据语义
6.4 skills（按需加载）
用于定义任务型规则，例如：
- 设计流程
- TDD 流程
- 发布流程
作用：
减少常驻上下文，提高规则遵守率
7. Compile Layer（编译层）
7.1 目的
解决：
不同 agent 使用不同入口文件的问题
7.2 编译目标
从 agents/** 生成：
- AGENTS.md
- CLAUDE.md
- GEMINI.md
- Copilot instructions
7.3 编译原则
原则 A：规则只写一次
所有规则必须只存在于 agents/**
原则 B：编译产物允许重排
编译产物可以：
- 摘要
- 重排结构
- 添加索引
- 适配工具格式
原则 C：禁止手动修改编译产物
必须明确：
该文件为生成文件，不允许手动修改
8. Runtime / Enforcement Layer（执行层）
8.1 作用
将规则从“建议”变成“约束”。
8.2 组成
- hooks（pre-commit 等）
- CI（持续集成）
- scripts（自动化检查）
- 权限控制（sandbox / denylist）
8.3 必须下沉到执行层的规则
例如：
- 测试必须通过
- lint 必须通过
- 禁止危险命令
- 禁止修改关键路径
判断原则
凡是“绝不能违反”的规则，必须由执行层保证
9. Verification Layer（验证层）
9.1 加载验证
确认规则是否被加载，例如：
- Claude：查看 memory
- Gemini：查看 context
- Codex：查看 instructions
- Copilot：查看 references
9.2 行为验证
确认 agent 是否按规则执行，例如：
- 是否遵循流程
- 是否按结构输出
- 是否先澄清需求
9.3 结果验证
确认产物是否符合规则，例如：
- 测试
- 构建
- lint
- 安全扫描
10. 优先级模型
完整优先级如下：
1. system / user prompt
2. 执行层（hooks / CI / permissions）
3. adapter（各 agent 入口文件）
4. core
5. modules
6. conventions
7. skills（按需加载）
11. AGENTS.md 的角色
在 V2 中，AGENTS.md 是：
规则系统的统一入口说明，而不是唯一规则来源
它应包含：
- 项目说明
- 技术栈
- 架构概览
- 规则树位置
- 优先级说明
- 验证方法
- 执行层说明
12. 反模式
反模式 1：多处定义同一规则
会导致规则漂移。
反模式 2：手动维护多个入口文件
应通过编译统一生成。
反模式 3：把硬约束写成文档
必须下沉到执行层。
反模式 4：规则无限增长
必须通过 skills 和作用域控制。
反模式 5：无法验证规则加载
必须提供验证方式。
13. 适用范围
适用于：
- 多 AI agent 协作项目
- 长期维护仓库
- 需要统一 AI 行为的团队
14. 最终结论
AI Agent 规则系统不是文档问题，而是工程问题
一个有效的系统必须：
- 有唯一规则来源
- 能适配不同 agent
- 能强制关键约束
- 能验证执行结果
