🤖 OpenSpec + Antigravity CLI (agy) 實戰開發規範與無縫續命全指南

本手冊定義了新專案如何透過 Google Antigravity CLI (agy) 與 OpenSpec 進行「規格驅動開發 (Spec-driven Development)」，並深入解析開發過程中遭遇 Gemini Pro 訂閱配額（Quota）用盡時，如何跨平台（Windows / macOS / Linux）100% 無痛換號接續對話的救援方案與避坑指南。

⚠️ 先決條件 (Prerequisites)

在開始建立專案之前，請確保您的開發環境中已經安裝並能在終端機正常呼叫以下工具：

  • Git (命令列版本)：用於版本控制 (官方下載)
  • Node.js / npm：用於套件與工具管理 (官方下載)
  • Python 3：用於執行部分擴充腳本與工具 (官方下載)
    *(注意：Windows 安裝時請務必勾選「Add Python to PATH」)*

🛠️ 一、新專案起手式與環境準備

第 0 項：建立專案目錄並進入

在終端機執行以下指令來建立並進入您的新專案：

mkdir my-new-project
cd my-new-project

第 1 項：初始化版本控制與忽略設定

為了避免不必要的大型檔案或隱私資訊進入版本控制，我們必須在專案一開始就建立 .gitignore 檔案。

請先建立 .gitignore 檔案，並填入以下樣板內容：

venv/
node_modules/
__pycache__/
*.pyc
.DS_Store
.env
logs/
records/
*.db
*.log
*.csv

存檔後，在終端機執行以下指令，完成身份確認與首次 Commit：

# 確保已設定全域名稱與信箱 (若已設定過可略過這兩行)
git config --global user.name "您的名字"
git config --global user.email "您的信箱"

# 初始化並進行首次提交
git init
git add .gitignore
git commit -m "chore: initial commit with gitignore"

第 2 項：產生專案專屬大腦結構

執行以下指令，為這個專案建立獨立的設定檔結構：

openspec init
重要提示：當系統詢問框架時，請選擇 antigravity。

第 3 項：核心觀念（這些隱藏目錄是怎麼來的？）

🧠 雙大腦架構解析

執行完上面的 openspec init 指令後，專案目錄下會多出 .agents/ 與 openspec/ 兩個目錄。這就是專案的「專屬雙大腦」：

  • .agents/：掌管 AI 的行為模式與專案鐵律（例如目錄規範統整於 .agents/、執行指令前必須取得同意、強制要求版控等）。
  • openspec/：負責儲存專案的系統規格、架構設計與任務狀態，確保每次對話都能延續專案的記憶。

⚡ 二、AI 啟動、模型切換與專案鐵律注入

第 4 項：啟動 AI 並切換至 Pro 模型

執行以下指令啟動 Antigravity CLI：

agy

啟動後，務必先將模型切換為 pro (High) 以獲得最佳的邏輯推理與架構設計能力。

操作方式：在對話框輸入 /model 然後選擇 pro，或直接輸入 /model pro。

第 5 項：注入專案鐵律與規格設定

現在我們要將精心設計的專案鐵律與設定寫入剛剛產生的目錄中。

⚠️ 貼上前的注意事項：
下方的指令中包含了 [填寫專案名稱] 與 [填寫技術棧] 兩個佔位符。請在送出給 AI 前，先將它們替換成您實際的專案名稱與預計使用的技術棧（例如：React, Node.js 等）。

請在 CLI 對話框中直接貼上並修改以下完整指令，讓 AI 一次幫您建好檔案：

/openspec-explore 請幫我建立新專案的基礎規範。

1. 請寫入以下內容到 `.agents/AGENTS.md` 檔案中：
# 專案鐵律 (Rules)
- **目錄規範 (Directory Conventions)**：專案內所有 Agent 相關設定與規範，一律統整於 `.agents/`（複數），嚴禁建立單數的 `.agent/` 目錄。
- **執行前確認 (Execution Confirmation)**：在修改檔案、執行指令或進行破壞性變更之前，永遠必須先向使用者提出計畫與變更內容，並取得明確同意後才可執行。
- **嚴格的版本控制 (Strict Version Control)**：在完成任何重大更新或功能後，永遠必須主動執行 `git add .` 與 `git commit`。
- **非同步任務同步 (Async Task Synchronization)**：當呼叫非同步的背景子代理或任務時，永遠必須等待回傳完成訊息後，才可進行 Git Commit 或分支操作。
- **防呆與錯誤處理 (Error Handling & Guardrails)**：在實作任何核心邏輯或 UI 互動時，必須主動考慮極端情況並加入適當的阻擋機制。
- **流程圖文件化 (Flowchart Documentation)**：產生的系統架構或邏輯流程圖，必須使用 `mermaid` 語法記錄到 Spec 文件中。
- **自動同步主文件 (Auto-Sync Master Docs)**：變更歸檔後，必須自動重新生成 `openspec/specs/README.md`。

2. 請寫入以下內容到 `openspec/config.yaml` 檔案中：
schema: spec-driven
context: |
  Project: [填寫專案名稱]
  Tech Stack: [填寫技術棧]
  Conventions:
    - 遵守 Conventional Commits 規範
    - 嚴格遵守 Spec-driven 的開發流程
  Language Requirement:
    - CRITICAL: 所有未來產出的 OpenSpec 文件絕對必須使用繁體中文 (zh-TW) 撰寫。
rules:
  proposal:
    - "Must be written in Traditional Chinese (zh-TW) / 所有提案必須以繁體中文撰寫"
  tasks:
    - "Must be written in Traditional Chinese (zh-TW) / 所有任務必須以繁體中文撰寫"
  specs:
    - "Must be written in Traditional Chinese (zh-TW) / 所有規格說明書必須以繁體中文撰寫"

完成後請告訴我。

第 6 項：必備外掛安裝：架構拷問官 (w-grill)

為了確保 AI 在實作前具備嚴格的架構審查防呆能力，強烈建議安裝 w-grill 技能。

請在專案根目錄開啟終端機，執行以下指令將技能匯入：

npx skills add WilliamFromTW/skills -s w-grill
功能說明： 架構拷問官 (w-grill) 是一個無情的架構審查官。當您提出新需求時，只要在對話框輸入 /w-grill，AI 就會自動讀取剛才的探索脈絡，針對潛在的安全漏洞、資料庫設計或架構缺陷進行嚴厲的反問與防呆，確保設計滴水不漏！

🔄 三、OpenSpec 規格驅動開發 (SDD) 六部曲協作流水線

完成基礎設定後，日常任何新功能開發或重構，請嚴格依照 OpenSpec 規格驅動開發流程推進：

  1. 宣讀鐵律：在對話起手式，務必先要求 「請遵守 .agents/AGENTS.md 的鐵律」。
  2. 探索與討論：輸入 /openspec-explore 進入探索模式，與 AI 進行需求推演與技術選型。
  3. 自我拷問防呆：討論產生初步共識後，輸入 /w-grill 讓架構拷問官對剛剛的設計進行漏洞審查。
  4. 建立提案與規格：討論收斂後，輸入 /openspec-propose。AI 會自動生成符合 SDD 規範的 proposal.md、design.md、tasks.md 與規格 Delta。
  5. 開發與實作：規格確認無誤後，輸入 /openspec-apply-change，AI 將嚴格按照任務清單逐步寫代碼並打勾標記 - [x]。
  6. 封存與歸檔：功能開發與測試通過後，輸入 /openspec-archive-change 封存變更，系統會自動將規格合併至主文件並歸檔。
📝 專案收尾與文件化：
當階段性開發告一段落時，請直接命令 AI 產出專案入口說明（例如：「請根據目前的系統實作進度，在根目錄產生一份 README.md，內容需包含系統說明、環境安裝與執行步驟。」），確保專案隨時保持易於交接與部署的狀態。

🚨 四、實戰救援：Gemini Pro 額度爆了？跨平台換號無縫續接 SOP

在開發中途，最常遇到的突發狀況就是 Gemini Pro 額度用盡。很多人不敢中斷對話，深怕改到一半的程式碼遺失或被新對話沖掉。其實只要掌握以下機制，換帳號接續輕而易舉！

💡 核心原理：為什麼換帳號對話不會消失？

AI 記憶在本地：agy 的所有對話紀錄（Transcript）、暫存碼（Brain Staging）與工作區記憶，都是即時存放在開發者本機的檔案系統中（Linux/macOS 為 ~/.gemini/antigravity-cli/brain/；Windows 為 %USERPROFILE%\.gemini\antigravity-cli\brain\）。

帳號只負責提供運算水管：切換 Google 帳號或訂閱，改變的只是「呼叫 Gemini API 所消耗的 Quota 與 Token」。只要本地的對話 ID 還在，換上新帳號重新掛載原對話，AI 就會完整繼承上文所有脈絡！

跨平台換號無縫續接 5 步流程

步驟 1：查詢當前對話的 Conversation ID
若 CLI 視窗已關閉，可直接在終端機一行指令撈出最後一筆對話 ID：

macOS / Linux (Bash / Zsh)：

ls -td ~/.gemini/antigravity-cli/brain/*/ | head -n 1 | xargs -n 1 basename

Windows (PowerShell)：

Get-ChildItem $env:USERPROFILE\.gemini\antigravity-cli\brain | Sort-Object LastWriteTime -Descending | Select-Object -First 1 Name

*(輸出會是一串 UUID，例如：0bb41a6b-d044-4687-93aa-e55a066b2dca)*

步驟 2：優雅退出目前的 Session
在對話輸入列輸入 /exit（或按兩次 Ctrl+D）正常退出，確保最後一輪對話紀錄（transcript.jsonl）與快取完整寫入硬碟，切忌強殺視窗。

/exit

步驟 3：切換並登入您新的訂閱帳號
依照認證流程完成新 Google 帳號的登入與授權（取得新的有效 API Token）。

步驟 4：精準接續原對話（核心指令）
回到專案目錄，執行以下指令（各平台通用）：

agy --conversation 0bb41a6b-d044-4687-93aa-e55a066b2dca

進入後，先前的所有討論、修改軌跡與未完成任務將全面還原！

步驟 5：發送「定心咒」重回戰場
接回對話後，第一句話建議發送：

我已切換新帳號接續。請檢查目前的 git status 與中斷點，繼續剛才未完成的工作。

⚠️ 新手常見避坑地雷

  • 地雷 1：誤用 agy -c <ID>
    -c 是 --continue 的縮寫，不接受任何參數，它只會盲目接續「最新一筆對話」。若登入新帳號時不小心開了新 Session 測試，agy -c 就會跑進新對話而非原本工作。永遠使用 agy --conversation <ID> 最穩健！
  • 地雷 2：程式改一半未設防護網
    換帳號前，若程式已被修改但尚未編譯通過，請先在終端機下 git status 與 git diff 檢視，並打個暫存 Commit： 
    git add .
git commit -m "wip: checkpoint before switching gemini account"
    確保就算換帳號出現意外，隨時都能 git reset 回到安全斷點。

⚙️ 五、進階維護與高階設定

1. 系統工具升級指南

隨著工具版本迭代，建議定期升級以取得最新修復與功能：

🚀 升級 Antigravity CLI：

agy update

📦 升級 OpenSpec 框架（兩階段更新）：

# 1. 全域重新安裝最新版
npm install -g @fission-ai/openspec@latest

# 2. 進入既有專案目錄強制更新設定結構
openspec update --force

2. 全自動免詢問推土機模式設定

如果您覺得 AI 頻繁停下來詢問「是否同意寫入」或「是否執行指令」打斷思維，可以透過設定全面授權：

  1. 在 Antigravity CLI 中輸入 /settings 指令，確認 "toolPermission" 設定為 "always-proceed"。
  2. 在 CLI 中輸入 /permissions 指令，選擇 project 範圍。
  3. 一筆一筆新增以下授權規則：
    • command(*)
    • mcp(*)
    • read_url(*)
    • write_file(*) 與 read_file(*)

⚠️ 終極安全警告

開啟全自動權限後，AI 將直接讀寫檔案與執行指令不再詢問。享受全自動極速開發的同時，請務必在使用前養成 Git Commit 的良好習慣，避免 AI 產生幻覺時破壞既有代碼！

文件基於工具版本：openspec 1.11.0+，agy 1.1.22+