【深度对比】四大 AI 编程智能体规则架构指南：Antigravity・Kiro・Claude Code・Codex（AGENTS.md 与专属扩展）

📅 发布日: 2026/11/03, 更新日: 2026/11/07 ⏱️ 预计阅读时间约19分钟 (7,709字)

全面解析 Google Antigravity、Kiro、Claude Code 与 OpenAI Codex 的规则工程架构：涵盖 AGENTS.md 通用标准、150行 Token 预算、YAML 按需延迟加载与确定性 Hooks 防护栏。

概述
1. 为什么 AI 智能体的规则文件总会失控？（三大反模式）
2. 四大智能体规则引擎深度横评：通用标准 vs 专属扩展
3. 跨所有智能体的通用最佳实践（Universal Foundation）
4. 【完全边界设计】全局 vs 工作区：什么该放哪里？（Scoping Architecture）
5. 榨干各家智能体“专属超能力”的实战技巧
6. 【终极模板】绝不崩塌的“混合联邦型规则架构”
1. 规则架构自检清单（完成度审计）
7. 总结
相关文章

概述

在日常软件研发工作中，我会同时编排并混用多款 AI 编程智能体（Google Antigravity、Anthropic Claude Code、Kiro 以及 OpenAI Codex）。然而，在长期高强度的协作里，最让我头疼、也引发过最多返工与惊险事故的瓶颈，就是 “智能体规则定义（提示词与指令文件）的崩塌与跨工具漂移” 。

起初我天真地以为，只要把编码规范与安全红线认真整理成一份文档，直接贴进 AGENTS.md 或 CLAUDE.md ，所有工具都会乖乖照做。但随着并行项目增多、多仓库架构规模扩大，生产一线接连暴露出令人焦头烂额的故障模式：

复制粘贴双份维护引发的规则冲突（配置漂移） ：同时在 AGENTS.md 和 CLAUDE.md 维护相同规范，某次只改了其中一份，结果不同智能体对指令理解相互打架，提交 PR 时格式化混战不断。
规则膨胀导致的上下文窒息与“选择性失明” ：抱着“这条也要约束、那条也得提醒”的心态不断往里塞内容，最终滚成上千行的巨型单文件；会话进行到中段，大模型受 Lost in the Middle （中间迷失）效应影响，直接无视最核心的安全指令。
“自然语言恳求”酿成的破坏性事故 ：哪怕在 Markdown 里用醒目文字反复叮嘱“※绝对禁止直接向 main 分支 push”，一旦上下文吃紧，智能体依然会面不改色地敲出 git push origin main ，让人惊出一身冷汗。
不同工具隐藏的解析差异 ：在 Antigravity 下顺畅运行的 YAML Frontmatter 条件规则在其他工具中被彻底无视；Codex 遇到超过 32 KiB 的文档会在末尾静默截断；而 Kiro 的动态文件引用语法在 Claude Code 中无法原生解析。

在这篇深度实战总结中，我将分享自己在踩遍上述大坑后沉淀出的 “四大 AI 编程智能体（Antigravity / Kiro / Claude Code / Codex）规则架构完全设计指南” 。

我们将彻底厘清哪些是所有工具通用的 开放标准基座（Universal Foundation） ，哪些是各家独有的 专属超能力（Specialized Superpowers） ，并给出一套经过生产验证、绝不崩塌的 混合联邦型规则架构（Federated Rules Architecture） 蓝图。

1. 为什么 AI 智能体的规则文件总会失控？（三大反模式）

在工程一线高频使用 AI 编程智能体的团队，几乎百分之百会踩中以下三个经典陷阱。

反模式 1：巨型单体的上下文税（The Monolithic Context Tax）

试图把单元测试规范、Commit Message 格式、废弃依赖库版本、云端 IAM 最小权限要求等所有条款，统统塞进仓库根目录唯一的一份 AGENTS.md 中。

由于智能体在每一轮调用工具时都会把整份规则文档重新注入提示词窗口，一份 1,000 行（数千乃至上万 Token）的巨型文件 不仅会在每次操作中白白烧掉高昂的 Token 预算，还会迅速耗尽模型的注意力机制，使核心指令被漏掉的概率呈指数级飙升 。

反模式 2：双份维护导致的配置漂移（Duplication Drift）

觉得“Claude Code 需要 CLAUDE.md ，其他工具需要 AGENTS.md ”，于是靠手工复制粘贴维护两份文件。
每当新增特性或修订架构规范时，只要漏改其中一边，智能体 A 就会按新规写代码，而智能体 B 则拿着旧规把刚写好的逻辑破坏性重写，陷入无休止的代码回归地狱。

反模式 3：依赖自然语言“苦口婆心”的伪安全（Plea-Based Security）

指望仅靠礼貌或严厉的自然语言描述（例如“请千万不要执行高危命令”、“严禁提交密钥”）来阻止高风险操作。
大语言模型本质上是概率模型，在复杂多步推理或上下文紧迫时，纯文本提示词随时可能被绕过。 铁律只有一条：底线规则绝不能靠写文章恳求，而必须通过 Hook（钩子）、权限策略与沙箱从物理层面强制阻断。

2. 四大智能体规则引擎深度横评：通用标准 vs 专属扩展

下面基于最新官方机制，横向对比四大主流编程智能体加载与处理规则的核心差异：

评估维度	Google Antigravity	Kiro (CLI / IDE)	Anthropic Claude Code	OpenAI Codex
核心规则文件	`~/.gemini/config/rules/*.md` `<repo>/AGENTS.md`	`~/.kiro/steering/.md` `.kiro/steering/.md` `AGENTS.md`	`CLAUDE.md` `~/.claude/rules/*.md` `AGENTS.md` (兜底回退)	`~/.codex/AGENTS.md` `<repo>/AGENTS.md` `AGENTS.override.md`
开放标准 `AGENTS.md` 支持	原生支持（常驻加载）	原生支持（常驻加载）	兜底支持（无 `CLAUDE.md` 时生效）	原生支持（自上而下级联合并）
文档读取体积上限	取决于模型上下文窗口	取决于项目配置	取决于上下文窗口	默认 32 KiB （可在 `config.toml` 调整）
条件触发 / 动态加载机制	YAML Frontmatter ( `glob` , `model_decision` , `manual` )	Steering 配置 (Always, Conditional, Manual)	基于目录层级匹配	`AGENTS.override.md` （阻断父级继承）
外部文件实时动态引用	通过 Agent Skill 按需读取	`#[[file:...]]` 语法（支持行号范围与目录）	`@path/to/file` 导入语法	仅支持内联文本
强制拦截 / 执行护栏	PreToolUse / PostToolUse Hooks	Permission 策略 (allow/ask/deny)	PreToolUse Hooks ( `settings.json` )	`config.toml` 沙箱权限策略

3. 跨所有智能体的通用最佳实践（Universal Foundation）

无论主力使用哪一款工具，以下三条架构原则放之四海而皆准。

① 三层级联覆盖（继承 UNIX 层级哲学）

如同 Linux 的 /etc/ → ~/.config/ → ./ 体系，智能体规则必须按从宏观到微观的三层组织，严格贯彻 “局部（近端工作区）配置永远覆盖全局配置” 的原则：

Global（ ~/.config/ , ~/.gemini/config/rules/ , ~/.claude/rules/ ） ：跨项目不变的个人或组织准则（Git 作者署名属性、基础安全红线、默认回复语言）。
Workspace Root（ ./AGENTS.md ） ：当前仓库的核心架构约束、必选构建与测试命令、目录组织规范。
Subdirectory（ ./src/api/AGENTS.md ） ：特定子包或微服务专属的框架细节与局部约定。

② 上下文预算（150～200 行黄金法则）

常驻加载的根目录 AGENTS.md 应严格控制在 150～200 行以内 。请对文件中的每一句话执行试金石测试（Litmus Test）：
> “如果删掉这一行，智能体会犯下灾难性或不可逆的错误吗？”

凡是 Linter、Formatter 或类型检查器能自动拦截的代码风格细节，以及主流框架人尽皆知的常规写法，一律果断删掉。只保留智能体无法单靠阅读源码猜出来的“项目特殊例外”与“精确构建测试命令”。

③ “规范（Rule）”与“流程（Skill）”彻底解耦

切勿把冗长的部署手册或多步数据库迁移脚本直接塞进规则文件：
- Rule（ AGENTS.md ） ：只定义任何时刻都不可违背的判断标准、边界约束与禁令。
- Skill（ SKILL.md ）/ Runbook ：将分步操作手册、排查脚本与自动化命令拆分为独立技能，仅在触发对应任务时按需（On-Demand）加载。

4. 【完全边界设计】全局 vs 工作区：什么该放哪里？（Scoping Architecture）

即便理解了三层级联原则，工程团队在落地时最容易踩坑的依然是 作用域边界（Scoping）设计 —— “到底哪些指令该写进用户级全局配置，哪些必须留在代码仓库内部？”

我早期也曾图省事，把某个项目的配置随手写进全局规则，结果切换到另一家客户的仓库时差点用错云账号凭证引发误部署；反过来，我也曾把个人 Mac 的本地绝对路径提交进仓库的 AGENTS.md ，直接导致团队同事和 CI 流水线集体报错。

下面是我目前在所有生产级多智能体工作流中严格执行的“全局 vs 工作区”职责边界矩阵：

职责边界矩阵（什么内容该定义在哪里）

类别	全局作用域 ( `~/.config/` , `~/.gemini/...` )	工作区作用域 ( `./AGENTS.md` , `./.agents/...` )
身份与署名属性	操作者署名与人设准则・Git 提交作者姓名（Kanji Shinohara）与邮箱・禁止出现 AI 助手署名的铁律・默认交互语言（如中文技术表述规范、日语 `です/ます` 、英文代码注释）	项目团队与业务上下文・内部产品代号与项目命名规范・指定的代码审查人（Reviewer）与干系人标识
软件工程原则	普适研发方法论与质量底线・TDD 强制要求（Red-Green-Refactor，覆盖率 >=80%）・不可变性原则（禁止原地修改，返回新副本）・规划先行（动代码前先对齐方案）・函数行数上限（建议少于 50 行）	技术栈与架构约定・目录划分规范（ `features/` , `components/` ）・状态管理与 API 客户端模式（React Query, Zustand）・设计系统 Token 与样式约定
宿主机与 OS 安全护栏	宿主机环境绝对防线・禁止侵入式本地 GUI 操作（严禁抢占鼠标与窗口焦点）・5 位端口号防冲突管理（30000～49999 独占分配）・临时脚本与缓存卫生（严格限定在 `/tmp` ，严禁污染仓库根目录）・后台守护进程启停规范	构建、测试与开发命令・精确的构建与测试指令（ `npm run build` , `pytest` ）・本地开发服务器启动命令（ `npm run dev` ）・静态检查与类型校验命令（ `tsc --noEmit` , `ruff check` ）
安全与合规控制	通用机密与认证防护・零硬编码密钥（严禁提交或外发 API Key、私有 Token）・凭证扫描与防泄露拦截・网络沙箱边界强约束	行业监管与业务域合规要求・金融行业合规（严禁无资质投资建议、诱导买入或预测目标股价）・商业化披露义务（ `SPONSORED` / 广告标识展示）・GDPR、HIPAA 等特定业务域法规要求
Git 与发布策略	通用 Git 协作协议・Conventional Commits 规范（ `feat:` , `fix:` ）・强制使用 HTTPS 连接（避免 SSH 密钥认证故障）・多分支并行开发强制使用 `git worktree` 隔离	仓库专属分支与部署流水线・分支模型（ `develop` 集成 → `main` 生产）・部署目标（Firebase Hosting, Cloudflare Pages, Cloud Run 等）・GCP 项目 ID、AWS Profile 名称
上下文预算管理	会话预算与子智能体委派策略・大规模检索与反复编译排错隔离至子智能体（Subagent）・防止上下文枯竭的压缩（Compact）与重置策略	内联引用与项目实时上下文・核心 Schema 与类型定义路径指针（如 `#[[file:...]]` ）・关键架构图谱与 README 所在路径

生产现场高发的“三大越界反模式”

一旦上述边界变得模糊，智能体瞬间就会给研发团队埋下隐蔽故障与安全隐患。

越界 1：工作区配置污染全局（Global Leaking）

为了省去每次配置的麻烦，把 AWS_PROFILE=client-prod 或某个本地绝对路径（如 /Users/user01/workspace/client-a/... ）硬编码进全局规则（ ~/.gemini/config/rules/ 或 ~/.claude/rules/ ）。
当你切换到个人开源项目或客户 B 的代码库时，智能体会 下意识地调用客户 A 的凭证去执行云端命令，轻则因权限报错卡死中断，重则把代码误部署到别家生产基础设施上 。

越界 2：本地隐私路径泄露至代码仓库（Workspace Leaking）

把个人 Mac 独有的绝对路径（ file:///Users/kanji/... ）、私有 SSH 别名或本机专属环境变量写进仓库的 AGENTS.md 并直接 Git 提交。
一旦 GitHub Actions 流水线、Docker 容器或使用 Windows 的团队成员拉取代码， 自动化构建会因找不到路径瞬间崩溃，而你个人电脑的内部目录结构也会永久留在 Git 历史记录中 。

越界 3：全局规则过度堆砌引发“上下文窒息”（Global Bloating）

抱着“以后所有项目说不定都能用上”的心态，把 Next.js、Python、Terraform、Docker、Go、Rust、Tailwind 的全套最佳实践一股脑塞进全局规则。
结果哪怕只是开个会话写一行简单的 Shell 脚本，智能体在启动瞬间也要被迫吞下超过 10,000 Token 的无关规则， 直接挤占理解当前用户指令的注意力窗口，大幅推高幻觉率与指令违背率 。

源自 UNIX 哲学的“规则归属试金石清单（Litmus Test）”

每当不确定一条新规则该放哪里时，只需问自己两个简单问题：

“如果明天我启动一个完全不相关的新项目（换一门编程语言、换一家客户），这条规则依然需要 100% 严格生效吗？”
- 是（YES） ：操作者身份署名、TDD 准则、本地 GUI 保护、防密钥泄露 → 放全局 Global（ ~/.config/ ）
- 否（NO） ：特定框架写法、构建命令、云端 Profile、行业法规 → 放工作区 Workspace（ AGENTS.md ）
“包含这条规则的文件，能否不做任何脱敏直接公开到 Public GitHub 仓库？”
- 是（YES） ：架构设计模式、代码检查命令、目录编码规范 → 放工作区 Workspace（ AGENTS.md ）
- 否（NO） ：内部认证信息、个人电脑目录配置、专有云账号 ID → 放全局 Global 或环境变量

💡 中间层最优解：借助 Frontmatter 实现“按需加载的条件全局规则”

对于“跨多个项目通用，但仅在处理特定技术时才需要”的规范（例如 Terraform 资源命名规范或 Dockerfile 编写准则），可以利用 Antigravity 的 trigger: glob: "**/*.tf" 或 Kiro 的 Conditional Steering。 将规则文件存放在全局目录，但仅在打开匹配后缀的文件时才延迟注入上下文 ——这是 Gen 3 阶段最优雅的工程实践。

5. 榨干各家智能体“专属超能力”的实战技巧

搭好通用底座之后，下一步就是精准调用各款工具的差异化特性，把工程杠杆拉满。

1. Google Antigravity：基于 YAML Frontmatter 的按需延迟加载

Antigravity 最亮眼的杀手锏，是在 ~/.gemini/config/rules/*.md 中支持细粒度的 YAML Frontmatter 触发条件 ：

---
trigger: glob
globs: "**/*.tf, **/*.tfvars, infra/**/*.yaml"
description: Terraform naming conventions and provider requirements
---
## 基础设施命名规范
- 所有云资源名称必须包含环境前缀（prd、stg、dev）。

glob ：仅在打开匹配文件时才注入该规则，写前端页面时绝不会被厚重的基础设施或数据库迁移规范白白消耗 Token。
model_decision ：平时只向智能体暴露简短的 description 摘要，仅当模型自主判断当前任务需要该规范时才加载全文。

2. Kiro： `#[[file:...]]` 实时文件引用与 Steering

Kiro 支持在 Steering 引导文档中直接动态嵌入真实源码文件，彻底告别文档与代码的重复拷贝：

## API 错误响应契约
所有错误返回载荷必须严格遵循中央 Schema 定义：
#[[file:src/types/api_errors.ts]]

一旦底层 TypeScript 类型定义更新，智能体读取到的上下文会自动同步最新结构。此外，随时可以通过 /context show 命令实时透视并调试当前会话已激活的规则列表。

3. Anthropic Claude Code：“符号链接陷阱”与跨平台终极解法（ @AGENTS.md 与 Hooks 防护墙）

当仓库根目录存在 CLAUDE.md 时，Claude Code 会优先读取它而忽略 AGENTS.md 。
许多使用 macOS 或 Linux 的工程师习惯顺手建一个本地符号链接（ CLAUDE.md -> AGENTS.md ）来省事，但 在跨平台团队协作或包含 Windows 开发者的企业环境中，这会引发灾难性的静默故障 。

⚠️ Windows 环境下的“9 字节静默清空”陷阱

在 Windows（Git for Windows）默认配置下，符号链接处于关闭状态（ core.symlinks = false ）。
当 Windows 开发者执行 git clone 拉取包含符号链接的仓库时， CLAUDE.md 不会变成有效链接，而是 退化成一份仅包含字面字符串 "AGENTS.md" （共 9 个字节）的普通纯文本文件 。
更致命的是，Claude Code 会不报任何警告地把这 9 个字节当成完整指令集吞进去—— 导致所有安全红线与架构规范在悄无声息间被彻底清空 。

✅ 100% 跨平台兼容的黄金标准（两种推荐方案）

首选方案：使用原生 @AGENTS.md 导入语法（强烈推荐）
将 CLAUDE.md 创建为真实的轻量纯文本文件，并在首行通过 @ 指令引入主规则：
```
@AGENTS.md

## Claude Code 专属指令
- （仅在此处补充 Claude 独有的行为约束或专属子智能体角色定义）
```
因为它本身就是标准 Markdown 纯文本，无论在 Windows、macOS、Linux 还是容器化 CI Runner 中都能 100% 确定性地展开，同时还能干净地隔离 Claude 专属指令。
零配置方案：直接不建 CLAUDE.md （交由原生兜底机制处理）
Claude Code 官方内置了兜底逻辑：只要仓库中不存在 CLAUDE.md ，它就会 自动检索并加载 AGENTS.md 。如果项目不需要针对 Claude 定制额外提示词，只保留唯一一份 AGENTS.md 是最干净的零维护方案。

此外，对于绝不允许逾越的安全底线，切忌靠文字叮嘱，而应在 .claude/settings.json 中配置确定性的 PreToolUse 钩子进行机械化拦截：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "python3 scripts/secret_guard.py"
          }
        ]
      }
    ]
  }
}

Warning

生产踩坑预警 1：避开 PreToolUse 钩子锁死自身的“自爆死锁陷阱”
在 PreToolUse 钩子中扫描敏感密钥（如 OpenAI/Anthropic Key）时，如果使用缺少单词边界的粗糙正则表达式（例如 sk-[A-Za-z0-9_-]+ ），极易把 Markdown 正文中正常的短横线命名文本（如 risk-assessment-workflow... ）误判为密钥泄露并返回退出码 2。一旦返回退出码 2，Claude Code 会立即 封锁后续所有工具调用（包括读取和修改文件） ，把智能体死死锁在连修 Bug 都无法动弹的死循环中。
请务必严格加上单词边界（ \b ），并对本地开发 .env 与测试 Mock 文件做好安全白名单放行（Fail-Open 设计）。

Tip

生产踩坑预警 2：用安装脚本（ install.py ）防范覆盖事故
在团队内部推广标准化规则包时，手工执行 cp 命令经常会无提示覆盖掉成员原有的 AGENTS.md 或 CLAUDE.md 。最佳实践是提供一份自动化安装脚本（ install.py ），在写入前自动将已有规则文件备份为 .bak 并提示合并，实现零冲突平滑落地。

4. OpenAI Codex：利用 `AGENTS.override.md` 实现干净的上下文切断

在超大型 Monorepo 中，如果希望某个独立子包或安全隔离目录彻底摆脱上层目录庞大的历史包袱，Codex 的 AGENTS.override.md 堪称利器。放置该文件后，Codex 会停止向上级目录回溯拼接 AGENTS.md ，为智能体提供一片干净清爽的上下文空间。

同时务必留意 Codex 默认的 32 KiB 文档体积上限：超出部分会在末尾被静默截断，因此要么在 config.toml 中调大 project_doc_max_bytes ，要么保持规则本身足够精炼。

6. 【终极模板】绝不崩塌的“混合联邦型规则架构”

下面这套标准化仓库目录结构，支撑我在同一代码库中同时平滑调度四大智能体且互不干扰：

my-project/
├── AGENTS.md                  # [SSOT] 全智能体通用核心规则（严格控制在 200 行内）
├── CLAUDE.md                  # Claude 专属入口（通过 @AGENTS.md 导入，100% 兼容 Windows）
├── .kiro/
│   └── steering/              # Kiro 专属文件匹配规则与 #[[file:...]] 实时引用
├── .gemini/ (或置于全局目录)
│   └── rules/                 # Antigravity 专属 glob 与 model_decision 按需规则
├── .codex/
│   └── config.toml            # Codex 字节上限配置与沙箱权限策略
└── .agents/
    └── hooks.json             # 物理阻断高危操作的 PreToolUse / PostToolUse 护栏

规则架构自检清单（完成度审计）

根目录 AGENTS.md 总行数是否控制在 200 行以内？
全局职责（身份署名、宿主机保护）与工作区职责（构建命令、技术栈架构）是否已严格解耦？
能否交给 Linter 和 Formatter 自动检查的代码风格条款是否已全部剔除？
CLAUDE.md 是否已通过 @AGENTS.md 导入或原生兜底机制彻底规避跨平台符号链接陷阱？
高危破坏性操作是否已通过确定性 Hook 和权限策略拦截，而非依赖自然语言恳求？
冗长的部署手册与运维脚本是否已剥离至按需加载的 SKILL.md 或 docs/ 目录？

7. 总结

今天对 AI 编程智能体规则的治理，早已不再是往提示词输入框里随手补几句注意事项那么简单，它本身就是一门严谨的软件架构工程。

严格隔离全局与工作区作用域（从源头杜绝凭证串用与本地路径泄露）
以厂商中立的精简版 AGENTS.md 作为唯一真实数据源（SSOT）
死守上下文 Token 预算（< 150～200 行），拒绝注意力稀释
精准叠加各工具的专属超能力（Antigravity 的 Frontmatter、Kiro 的实时文件引用、Claude Code 的 Hook、Codex 的层级截断）
用确定性的 Hook 护栏从物理层面锁死安全底线，而非靠文字祈祷