Antigravity CLI 怎麼設定？用 AGENT.md 管好小豬

Agy CLI 專案管理（Agent Project Governance） 是指透過 Google 新一代 Antigravity CLI (agy) 命令列工具，並於專案根目錄建立 AGENT.md 最高憲法，以嚴格規範 AI 代理人的角色權責、架構邊界與交付標準的工程體系。其實踐流程分為三步：第一步於本機終端機安裝與初始化環境；第二步擬定剛性負面邊界與型別規範；第三步指揮 Agent 在受約束的軌道上自動生成程式碼與單元測試。

在上一篇文章中，我們確立了「Prompt 是餵飼料，Workflow 才是養殖場」的核心觀念。

後來我真的帶著好奇心跑去研究與觀察了現代化智慧養豬場，結果發現一個極具衝擊力的真相：

在現代養殖業裡，真正累人的早就不是「餵豬」本身（小豬自己會吃、會睡、會長大），最折磨場長的其實是「管理」！

你必須隨時管理環境溫濕度、人員進出的生物安全隔離規範、精準調配飼料配方、定期記錄各項生理數據，還有防止外部病毒入侵的層層標準作業程序（SOP）。

回到軟體開發，情況竟然一模一樣。基礎語法的撰寫已經被 AI 大幅簡化，真正讓資深工程師瀕臨爆肝的反而是管理——管理 Codebase 邊界、管理 Context 雜訊、管理 AI Agent 的行為準則，以及防止未經驗證的套件入侵現有架構。

為了拯救被管理壓垮的工程師，今天我們要正式請出 Google 的命令列神器：Agy CLI，並在專案中建立這座智慧養殖場的最高管理憲法——AGENT.md！

智慧養豬場 vs 軟體工程：概念對照大表

在讓工具進駐專案前，我們先把「智慧養豬場」與「AI 驅動軟體工程」的對照關係梳理清楚。搞懂這張映射表，你就能一眼看穿自動化架構的管理本質：

第一步：請 Agy CLI 進駐專案終端機

要讓 AI 直接在你的專案裡「下地幹活」，傳統手動複製貼上 Prompt 到網頁端對話框的方式已經太慢，而且容易遺失檔案階層資訊。我們需要能直接感知檔案系統、執行 CLI 指令的工程工具。

1. 安裝與初始化 Agy CLI

在 Windows PowerShell 環境下執行官方安裝指令（請確保環境中已設定好 Google API 金鑰）：

1
2

# 安裝 Agy CLI
irm https://antigravity.google/cli/install.ps1 | iex

若在 macOS 或 Linux 環境下，亦可使用官方提供的 Shell 腳本完成安裝。

2. 專案根目錄驗證

安裝完成後，進入你的專案目錄直接輸入 agy：

1
2

# 於專案根目錄啟動 Agy CLI
agy

有了 Agy CLI 後，你就可以在 Terminal 中直接讓模型讀取專案檔案、進行 Code Review 或生成專案元件，徹底擺脫手動複製貼上的低效循環。

第二步：建立專案最高管理憲法 AGENT.md

養豬場如果沒有公佈「場內管理守則」，飼育員跟豬隻就會亂成一團；專案如果沒有 AGENT.md，Agy CLI 進來就會像野豬闖進菜園一樣隨便亂寫！

AGENT.md 是放置於專案根目錄（或 .agents/ 目錄）下的 Markdown 檔案。Agy CLI 在每次啟動或執行任務時，都會優先讀取這份檔案作為最高 System Instruction。

📄 實戰範例：專案根目錄下的 AGENT.md

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

# 專案 AGENT.md - 前端 Web Component 開發規範

## 1. 角色設定 (Role)
你是一位精通 Web Standards 的資深前端架構師，專注於編寫高隔離度、零依賴的原生 Web Component。

## 2. 架構與邊界規範 (Architecture Constraints)
- **封裝隔離**：所有 UI 元件必須使用原生 Web Component (`customElements.define`) 搭配 Shadow DOM (`this.attachShadow({ mode: 'open' })`)，建立嚴格的生物安全隔離。
- **零依賴原則**：嚴禁私自引入 React、Vue 或 Angular 肥大 Runtime。若需第三方函式庫，僅能透過原生 ESM URL Import (如 `esm.sh`)。
- **樣式邊界**：CSS 必須完全封裝在 Shadow DOM 內部，嚴禁對宿主頁面產生任何全域樣式污染。

## 3. 資料與 API 規範 (Data Contract)
- 資料來源預設接收結構化 JSON 數據。
- 元件的所有 Properties 必須定義清晰的 TypeScript 型別檢查與預設值。

## 4. 完成定義 (Definition of Done)
- 每次生成的元件必須包含完整的 Custom Element 類別與基本 HTML 示範。
- 必須同時生成對應的 Vitest 單元測試檔，確保資料解析與 Event 觸發無誤。

這份文件的靈魂在於：正面界定職責，負面畫出紅線。 只要寫清楚「嚴禁引入肥大 Runtime」與「樣式必須完全隔離」，AI 就不會偷偷幫你安裝無關套件。

第三步：指揮 Agy CLI 遵循憲法生成元件

當 AGENT.md 建立完成後，你的專案就具備了剛性防護網。現在你可以放心地讓 Agy CLI 讀取專案環境並進行開發：

1

agy "請參考 src/components 目錄架構，幫我建立一個名為 <pig-health-card> 的 Web Component，用於顯示小豬健康生理數據"

sequenceDiagram
    autonumber
    actor Boss as 場長 (工程師)
    participant Agy as Agy CLI
    participant Const as AGENT.md 專案憲法
    participant Codebase as 專案程式庫

    Boss->>Agy: 下達建立 pig-health-card 元件需求
    Agy->>Const: 讀取角色規範與 Shadow DOM 隔離邊界
    Agy->>Codebase: 檢視現有目錄結構
    Agy-->>Boss: 產出高隔離度元件原始碼與 pig-health-card.test.ts

因為受到 AGENT.md 的約束，Agy CLI 產出的程式碼將會自動遵守 Shadow DOM 隔離、零全域樣式污染，並主動附帶單元測試檔——這就是自動化工程管理的第一步！

結語：從勞動工人升級為產線管理者

當你把 AGENT.md 設定好的那一刻，你就完成了一次關鍵的角色轉變：

你不再是蹲在專案裡一行行手搓語法的苦力工人，而是立下了管理規則、指揮 Agy CLI 在特定軌道上運行的產線管理者。

常見問題 FAQ

Q1：AGENT.md 應該放在專案根目錄還是子目錄？

Agy CLI 與 Antigravity 生態系支援專案根目錄的 AGENT.md，亦相容 .agents/AGENTS.md。建議將專案全域憲法放置於根目錄，模組專屬規範則可配合 Rules 機制配置於子目錄。

Q2：如果在對話中 AI 違反了 AGENT.md 的規則該怎麼辦？

首先檢查規則是否過於冗長或語意模糊。將核心禁令改為明確的條列清單，並使用強烈關鍵詞（如「嚴禁使用」、「必須提供」）。必要時可透過後續章節說明的 Rules 與 Hooks 建立自動化卡關驗證。

Q3：團隊多人協作時如何維護這份憲法？

將 AGENT.md 納入 Git 版本控制，將其視同專案的架構設計文件（ADR）。團隊成員提出架構調整時，必須透過 Pull Request 共同審查這份文件的修訂。

本日實作作業

1. 於本機終端機安裝並驗證 Agy CLI 是否能正常運行。
2. 在目前的工作專案根目錄下建立第一份 AGENT.md，明確寫下至少 3 條具體約束（例如：禁止使用特定套件、強制補上測試、規範檔案命名習慣）。

在有了憲法後，經過幾天訓練，我終於養出了一隻智商極高、懂專案架構的「神童級 AI 豬」。
但當我叫牠幫忙開 PR 時，牠卻用圓滾滾的眼睛看著我——因為牠沒有手！
下一篇，我們將來看 MCP 如何幫牠裝上雙手，並透過 Hooks、Rules 與 Plugin 築起四重防線！

系列導讀與延伸連結

• 上一篇：Agy 自動化工作流架構指南：從單次提示詞邁向任務拆解產線實踐
• 下一篇：Agy 四重治理防線架構指南：整合外部工具與自動連鎖校驗機制實踐
• 延伸閱讀：從 Gemini CLI 遷移至 Antigravity (agy CLI) 實戰記錄

• ← 上一篇
• 下一篇 →