【深度對比】四大 AI 程式設計代理規則架構指南：Antigravity・Kiro・Claude Code・Codex（AGENTS.md 與專屬擴充）

📅 發布日: 2026/11/03, 更新日: 2026/11/07 ⏱️ 預計閱讀時間約20分鐘 (7,947字)

全面解析 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 ，所有工具都會聰明地照單全收。但隨著並行專案增加、多儲存庫（Multi-Repo）規模擴大，開發第一線接連爆發出一連串慘痛的運作故障：

複製貼上雙重維護引發的規則衝突（設定漂移） ：同時在 AGENTS.md 與 CLAUDE.md 維護相同規範，某次只改了其中一份，結果不同代理對指令的解讀互相牴觸，發送 Pull Request 時不斷引爆排版與風格大戰。
規則肥大化導致的上下文窒息與「選擇性無視」 ：抱著「這條也要規定、那條也得提醒」的心態不斷追加規則，最後膨脹成超過 1,000 行的巨型單體檔案；對話進行到中段，大型語言模型受 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 訊息格式、棄用套件版本、雲端 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 提交。
一旦 CI/CD 管線（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 的條件式 Steering。 將檔案存放在全域區域，但只有在實際開啟符合條件的檔案時才延遲注入上下文 ——這正是 Gen 3 階段最洗鍊的工程作法。

5. 發揮各家代理「專屬超能力」的實戰技巧

穩固通用基石之後，下一步就是精準運用各款工具的獨門擴充功能，將開發槓桿發揮到極致。

1. Google Antigravity：基於 YAML Frontmatter 的延遲載入（Lazy-Loading）

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 型別定義更新，代理讀取的 Steering 上下文就會自動同步至最新狀態。此外，隨時都能透過 /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 匯入指示：
```
@AGENTS.md

## Claude Code 專屬指示
- （僅在此處補充 Claude Code 獨有的行為規範或專屬子代理角色設定）
```
因為它本身就是標準的 Markdown 純文字檔，無論在 Windows、macOS、Linux 或容器化 CI Runner 環境下都能 100% 確定性地展開，同時也能乾淨分離 Claude 專屬的額外指示。
零設定替代方案：乾脆不放 CLAUDE.md （交由原生備援機制處理）
Claude Code 官方內建了備援回退（Fallback）機制：只要儲存庫裡完全沒有 CLAUDE.md ，它就會 自動尋找並載入 AGENTS.md 。如果專案不需要針對 Claude 撰寫專屬提示詞，只維護唯一一份 AGENTS.md 是最乾淨的零維護模式。

此外，針對絕對不容許踩線的安全規則，請不要在提示詞裡用文字懇求，而是透過 .claude/settings.json 中的確定性 PreToolUse Hook 進行機械式攔截：

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

Warning

實戰踩坑警告 1：避開 PreToolUse Hook 把自己鎖死的「自爆死鎖陷阱」
在 PreToolUse Hook 中檢查機密資訊（如 OpenAI/Anthropic API 金鑰）時，若使用缺乏單字邊界的粗糙正規表示式（例如 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 。準備一支會在寫入前自動將既有規則檔備份為 .bak 並提示合併的安裝腳本（ install.py ），是團隊導入時的最佳實踐。

4. OpenAI Codex：透過 `AGENTS.override.md` 實現乾淨的上下文切斷

在大型 Monorepo 中，如果希望特定子套件或安全隔離區完全切斷上層目錄龐大的歷史規範，Codex 的 AGENTS.override.md 能發揮強大威力。放置該檔案的目錄及其下層會立即停止向上回溯搜尋 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 行以內？
全域職責（作者署名、主機環境保護）與工作區職責（建置指令、技術堆疊）是否已嚴格解耦？
能交由 Formatter 或 Linter 自動檢查的程式碼風格細節是否已全數移除？
CLAUDE.md 是否已透過 @AGENTS.md 匯入或原生備援機制避開跨平台符號連結陷阱？
絕對禁止的破壞性操作是否已透過確定性 Hook 與權限策略阻擋，而非依賴自然語言拜託？
冗長的操作手冊與腳本是否已抽離至依需求載入的 SKILL.md 或 docs/ 目錄？

7. 總結

AI 程式開發代理的規則管理，早已超越過去在提示詞對話框裡隨手補幾句注意事項的階段，而是一門需要嚴謹設計的軟體架構工程。

嚴格切分全域與工作區的作用域邊界（從源頭防堵憑證誤用與本機路徑外洩）
將核心基礎規則集中於廠商中立的單一真實來源 AGENTS.md
嚴格控管上下文 Token 預算（< 150～200 行），避免注意力飽和
精準疊加各工具的專屬武器（Antigravity 的 Frontmatter、Kiro 的即時檔案參照、Claude Code 的 Hook、Codex 的階層切斷）
用確定性的 Hook 護欄從物理層面擋下危險操作，而非靠文字懇求