神童豬沒有手，MCP 與 Agy 工具治理深鑽指南

Agy 治理防線（Agent Guardrail & Tooling Architecture） 是指在 Google Antigravity 生態中，透過 Model Context Protocol (MCP) 擴充外部工具雙手，並結合 Hooks 連鎖驗證、Rules 檔案條件約束與 Plugin 模組化容器，建立自我把關且不流於人治口頭說教的 AI 開發環境。其實踐步驟包含：第一步連接 GitHub 與檔案系統 MCP；第二步配置 post-edit 與 pre-commit Hooks 自動執行 Lint 與單元測試；第三步使用 Glob 條件式 Rules 防止型別污染；第四步將完整工具鏈封裝為 Plugin 一鍵複用。

經過前幾天的訓練，靠著 Agy CLI 與 AGENT.md 專案憲法，我終於在專案裡養出了一隻智商極高、懂專案邊界、又能拆解任務的「神童級 AI 豬」。

看著牠精準地寫出 Web Component 程式碼，我滿懷期待地對牠說：

「去，把剛才寫好的 Feature 建立一個 GitHub Issue，順便發個 PR，順便把遠端的資料庫欄位更新一下。」

這隻聰明的小豬只是用圓滾滾的眼睛看著我，無辜地搖了搖尾巴——因為牠根本沒有手！

AI 的終極尷尬：大腦 200 分，手腳 0 分

大語言模型（LLM）的本質是一個「文字推理大腦」。若沒有對外介面，牠就只能像被關在玻璃缸裡的超級天才：

• 牠知道程式碼哪裡有 Bug，但無法直接操控遠端 API。
• 牠知道需要這份最新文件，但無法自己連上外部資料庫查詢。
• 牠知道這段 Code 可以提 PR，但無法幫你打開瀏覽器點擊 GitHub 的按鈕。

要讓 AI 從「只會聊天的吉祥物」變成真正的「自動化生產力工具」，我們必須幫牠裝上雙手，並同步立下嚴格的四重治理防線！

flowchart TD
    A["Gemini / Agy 決策大腦"] --> B["第一防線：MCP 工具介面卡 (裝上雙手)"]
    B --> C["執行檔案變更與指令"]
    C --> D["第二防線：Hooks 自動連鎖校驗 (自動洗槽)"]
    D --> E["第三防線：Rules 動態規章制度 (全場規矩)"]
    E --> F["第四防線：Plugin 模組化打包 (分場整包帶走)"]

第一重防線：MCP (Model Context Protocol) 裝上工具雙手

以前要讓 AI 呼叫外部 API，工程師必須手動寫一堆客製化的 API Wrapper，每個工具都要重新定義 Prompt 與 Function Calling Schema，維護起來苦不堪言。

而 MCP (Model Context Protocol) 的出現，就像給 AI 訂立了 Universal USB 介面！

不論外部工具是 GitHub、本機檔案系統、PostgreSQL 還是 Notion，只要該服務提供標準的 MCP Server，AI 就可以透過統一的 MCP Client 協定，隨插即用這些外部能力：

flowchart LR
    Brain["Gemini 大腦"] --> Core["Agy 控制核心"]
    Core --> MCP["MCP 介面卡 (標準協定)"]
    MCP --> GitHub["GitHub Server"]
    MCP --> FS["File System"]
    MCP --> DB["Local Database"]
    MCP --> Custom["Custom API"]

對照養豬：從手動餵食到自動餵食器

agy CLI + GitHub MCP：全自動閉環流水線

當 Agy CLI 接上 GitHub MCP 與 File System MCP 後，原本需要你手動複製貼上與敲 Git 指令的繁瑣過程，瞬間串接成一條完全閉環的自動化流水線：

1

GitHub Issue 偵測 ➔ Gemini 解析脈絡 ➔ Coding 自動修改 ➔ Test 本機測試 ➔ Commit 語意化提交 ➔ PR 自動建立

原本你要花 30 分鐘切換視窗、複製程式碼、打 Git 指令與開瀏覽器的繁瑣動作，Agent 在背景幾秒內幫你自動完成——這才是真正長出雙手的手腳級 Agent！

第二重防線：agy Hooks 自動連鎖防線

現在你的 AI 豬不僅聰明、能進 Terminal，還能自己拿工具幹活了。但很快你又會發現一個新問題：豬吃完飯，誰來檢查與清理食槽？

在傳統養豬場裡，如果豬吃完飯沒有自動清槽與檢查環境，殘留的飼料很快就會發霉變質；在寫 Code 時也是一樣，如果 Agent 每次改完 Code，你都還要手動去敲 npm run lint 或 npm test，那只要你一時疏忽，壞掉的 Code 就會直接溜進 Codebase！

我們需要的是一個「只要豬一吃完飯，不用人下指令，自動引發連鎖反應」的機制——這就是 agy Hooks！

sequenceDiagram
    autonumber
    participant Agent as Agy Agent
    participant Hook as post-edit Hook (感應器)
    participant Linter as ESLint (自動水槍)
    participant Tester as Vitest (水質檢測)

    Agent->>Hook: 修改 UserCard.tsx 完成 (豬隻離槽)
    Hook->>Linter: 自動執行 eslint --fix
    Linter-->>Hook: 語法風格通過
    Hook->>Tester: 自動跑受影響的單元測試
    Tester-->>Hook: 測試全數通過
    Hook-->>Agent: 綠燈放行，允許進入 Commit 階段

軟體工程實戰：.agy/hooks.json

在專案中配置 Hooks，可讓每次修改都強制通過自動化卡關驗證：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

{
  "hooks": {
    "post-edit": [
      {
        "name": "Auto Linting",
        "command": "npx eslint --fix ${FILE_PATH}",
        "on_failure": "block_and_notify"
      },
      {
        "name": "Run Affected Unit Tests",
        "command": "npm run test -- --findRelatedTests ${FILE_PATH}",
        "on_failure": "retry_agent"
      }
    ],
    "pre-commit": [
      {
        "name": "TypeScript Type Check",
        "command": "npx tsc --noEmit",
        "on_failure": "abort"
      }
    ]
  }
}

• post-edit：Agent 修改完某個檔案瞬間觸發，自動替該檔案跑 eslint --fix，並只跑受影響的單元測試。若測試失敗，直接要求 Agent 自行修正。
• pre-commit：在 Agent 打包 Commit 前進行全局型別檢查，失敗直接中止 Commit 流程。

第三重防線：Antigravity Rules 規章制度化

有了 MCP 的手與 Hooks 的自動清槽，隨著處理的需求越來越多，你一定會碰上一種心累的狀況：每次叫 AI 寫 Code，你都得在 Prompt 裡重複唸經：「記得型別不要寫 any 喔！」、「元件命名要用 PascalCase 喔！」、「記得補測試喔！」

養一兩隻豬的時候，靠你每天站在豬舍門口口頭叮嚀還可以；但當你要管理 1,000 隻豬的時候，你總不能每一隻豬跑過來，你就重複背一次養豬注意事項吧？

[!TIP]
Prompt 是一次性的，Rules 是制度化的。
與其在每次對話中耳提面命，不如打造一個**「讓 AI 想做壞事都做不到」**的制度化環境。

Rules 的四種生效層級

Antigravity 提供了靈活的 Rules 分流機制，就像養豬場不同區域有不同的管理強度：

1. Global Rules (總場通用規章)：放置於 ~/.agents/rules/，不論開哪個專案都必須遵守（例如：禁止在 Commit 中寫入任何 API Key 或 Secret）。
2. Workspace Rules (專案專屬規章)：放置於專案 .agents/rules/ 目錄下，僅對當前儲存庫生效。
3. Always On (全時段強制生效)：每次與 Agent 對話、每次讀檔時自動載入。
4. Glob Pattern Match (條件限定啟用)：只在 Agent 觸發特定副檔名或目錄時動態載入（最推薦的最佳實踐）。

實戰範例：.agents/rules/react-components.md

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

---
name: react-component-rules
description: React 元件開發與型別卡關規範
globs: "src/**/*.tsx"
alwaysOn: false
---

# React Component Development Rules

只要修改或新增 `src/**/*.tsx` 下的任何檔案，必須嚴格遵守以下守則：

### 1. 型別與介面 (Type Safety)
- 嚴禁使用 `any` 或 `unknown`！所有 Props 必須建立專屬的 `interface` 或 `type`。
- Event Handler 必須標註明確 Event 型別 (如 `React.MouseEvent<HTMLButtonElement>`)。

### 2. 效能與狀態 (Performance)
- 嚴禁在 Component 頂層直接定義複雜的物件或陣列 initializer，避免每次 re-render 重複建立。
- 複雜計算必須使用 `useMemo` 包覆，傳遞給子元件的 Callback 必須使用 `useCallback`。

### 3. 單元測試對齊 (Testing Alignment)
- 修改 Component 檔時，必須同步確認 `src/**/*.test.tsx` 是否需要補上相對應的渲染測試。

這就像：只有進到母豬舍的機器人，才自動套用「母豬營養配給條例」，完全不佔用無關任務的 Token 空間！

第四重防線：Antigravity Plugin 模組化打包帶走

正當我看著這座自動化養豬場順暢運轉，坐在咖啡廳開心地喝著 Latte 時，老闆突然拍了拍我的肩膀：

「彥成啊，這座養豬場運作得太棒了！我們公司決定在隔壁園區再開一間分店，你明天去把另一座豬場也蓋起來吧！」

……等等，難道我要重新把所有的 AGENT.md 貼過去、把 .agents/skills/ 重新複製一遍、重新設定 hooks.json，再把一堆 Rules 手動搬一次？我是來養豬的，還是來辦 AI 新人訓練營的？

這時你會發現：我們需要的是一個可以整包打包搬走的「智慧豬場模組化套件」——Antigravity Plugin！

「Rules 是訂規矩，Plugin 是把整套規矩、技能與工具設備一起打包帶走。」

flowchart TD
    Plugin["Antigravity Plugin 模組箱"] --> Rules["Rules (規章規範)"]
    Plugin --> Skills["Skills (養殖 SOP)"]
    Plugin --> MCP["MCP (工具設備)"]
    Plugin --> Hooks["Hooks (連鎖巡檢)"]

官方 Plugin 目錄結構與宣告檔

一個標準的 Plugin 目錄結構如下：

1
2
3
4
5
6
7
8
9
10

plugins/
└── my-pig-farm/
    ├── plugin.json         # 模組總宣告檔 (元資料與版本)
    ├── mcp_config.json     # 工具設備 (MCP 伺服器配置)
    ├── hooks.json          # 自動巡場機制 (post-edit / pre-commit)
    ├── skills/             # 專業技能庫
    │   └── pig-farming/
    │       └── SKILL.md
    └── rules/              # 規章制度庫
        └── pig-farm-rules.md

1
2
3
4
5
6
7
8
9
10
11
12

{
  "name": "my-pig-farm-suite",
  "version": "1.0.0",
  "description": "前端雙刀流自動化豬場完整套件：包含 React/TS Rules、Lint Hooks 與 GitHub MCP 工具",
  "author": "林彥成",
  "capabilities": {
    "skills": ["skills/pig-farming/SKILL.md"],
    "rules": ["rules/pig-farm-rules.md"],
    "hooks": "hooks.json",
    "mcp": "mcp_config.json"
  }
}

有了 Plugin，新專案 0 門檻直接繼承團隊多年累積的 AI 規範與自動化設施！

常見問題 FAQ

Q1：MCP 與傳統 REST API 呼叫有什麼不同？

傳統做法需要為每個外部 API 撰寫專門的 Function Calling 定義與處理邏輯。MCP 提供了一套通用協定，只要服務端支援 MCP（如官方提供的 GitHub 或 PostgreSQL MCP），AI 客戶端即可無縫即插即用，大幅降低整合成本。

Q2：Hooks 執行失敗會中斷 Agent 嗎？

這取決於在 hooks.json 中設定的 on_failure 行為。若設定為 block_and_notify 或 retry_agent，系統會直接中斷當前流程，並將錯誤輸出（如 ESLint 報錯或測試失敗記錄）回饋給 Agent 要求其就地修正。

Q3：Rules 寫太多會不會導致模型混亂？

會的。這正是為什麼推薦使用 Glob Pattern 條件啟用 Rules。只有在 Agent 碰觸特定副檔名（如 .tsx 或 .sql）時才動態掛載對應規章，既節省 Context Token，又確保規範具備精準的約束力。

本日實作作業

1. 嘗試在專案中建立一個簡易的 .agy/hooks.json，在 post-edit 時自動觸發程式碼排版或語法檢查。
2. 嘗試將專案中通用的 Rules 與 Skills 抽離成一個獨立的 Plugin 資料夾，體驗一次「把整座豬場打包帶走」的快感！

雖然有了規矩與工具，但晚上兩間養豬場同時有問題怎麼辦？豬農總不能 24 小時盯著螢幕吧！
明天我們將進入多 Agent 協作：介紹 Sidecar 24 小時自動巡場，以及如何派出 Subagent 專業小豬機器人團隊 分工合作！

系列導讀與延伸連結

• 上一篇：Agy CLI 專案架構管理指南：以憲法守則約束代理人行為邊界實踐
• 下一篇：Agy 多代理人平行分工指南：以邊車監控與非同步架構守護脈絡實踐
• 延伸閱讀：用 Loop Engineering 讓 AI 不再需要你微管理

• ← 上一篇
• 下一篇 →