安裝
npx create-gaia@latest my-app適合誰
GAIA 自述為 "A serious harness for Claude Code"：給 Claude Code 的一套嚴肅工程骨架。它把「先想清楚再動手」固化成流程——編碼前先寫規格（Specs before code），每次提交設品質關卡，每次合併引入 Code Audit Team 稽核。它適合這樣的開發者：
- 用 Claude Code 做真實的軟體開發，希望每筆改動先有規格依據、提交可驗證、合併可稽核，而不是一次對話就產出未經檢查的程式碼。
- 願意接受流程約束：提交前要通過型別檢查、lint、單元與 Storybook 測試、Playwright E2E 和開發伺服器冒煙測試，全部通過才算過關。
- 滿足執行前提：Node.js >= 22.22.0。
以下情況不適合或需要先確認：
- 不使用 Claude Code 的環境：官方只把它描述為 Claude Code 的骨架，能否用於其他 agent 未說明。
- 只想快速產生腳本、不需要規格與測試流程的情境：它要求先寫規格，前置成本更高。
- 期望通用聊天或純寫作輔助的情境：官方對它的描述全部圍繞開發流程約束，沒有提及其他用途。
- 除 Node.js >= 22.22.0 外，官方未列出其他環境限制，系統相容性在確認前應視為未知。
3 分鐘完成第一次嘗試
推薦主路徑只有一條：先用官方指令建立專案，再到 Claude Code 裡觸發規格撰寫。
前提：本機已安裝 Node.js >= 22.22.0，並可以使用 Claude Code。
安裝：在終端機執行
npx create-gaia@latest my-app
官方明確要求以這種方式開始專案，而不是 clone 或 fork 儲存庫。指令裡的 my-app 是新專案的名字，第一次嘗試保持這個名字即可，避免與既有目錄混淆。
觸發任務：進入新建的 my-app 目錄，在 Claude Code 中輸入 /gaia-spec。官方描述該操作透過蘇格拉底式提問（Socratic discovery）撰寫一份不可變的 SPEC 工件。也就是說，它不會一開始就產生文件，而是圍繞需求逐項追問，等你回答後再把結論收斂成規格。副作用與確認點：它會產生規格工件，且一經產生即為不可變（immutable），因此回答提問時要把需求確認清楚再收尾；建議第一次就在這個全新專案裡進行，不觸及既有程式碼。
成功訊號：提問結束後拿到產生的 SPEC 工件，表示規格撰寫流程已經完成。如果中途看到的是一輪輪收斂式的追問而不是立刻產出全文，這正是該操作的設計——它靠提問釐清需求。
使用案例
案例一：新專案動工前固定需求。
情境：要啟動一個新專案，擔心口頭需求在多輪對話中漂移，不同輪次得到的實作方向不一致。
發起：在 npx create-gaia@latest my-app 建立的專案裡，向 Claude Code 發出 /gaia-spec。
過程與結果：agent 以蘇格拉底式提問逐項釐清需求，最終產出不可變的 SPEC 工件；由於規格先行是這套骨架的工作方式，這份工件會成為後續寫程式前的一致基準。工件不可變，產生前的提問環節就是唯一的確認點，回答前把關鍵決策想清楚。SPEC 工件的檔名與存放位置官方未寫明，可確認的終點是「產生不可變工件」這一步。
案例二：提交一處小改動，體驗提交前品質關卡。 情境：你在 GAIA 專案裡修改了一處程式碼，準備提交。 發起：按日常流程執行一次提交。 過程與結果：提交前會執行品質關卡——型別檢查（Typecheck）、lint、單元與 Storybook 測試、Playwright E2E、開發伺服器冒煙測試——全部通過提交才能繼續，任何一項未通過，提交都無法完成。建議選一處影響小的改動，便於觀察關卡執行的全過程；關卡包含 E2E 與冒煙測試，會實際執行，第一次執行通常比沒有關卡的提交更花時間，本機環境也需要能啟動開發伺服器。是否存在跳過關卡的方式，官方未說明。
使用邊界
- 執行環境：官方確認的要求只有 Node.js >= 22.22.0，其餘系統層面的限制未給出，使用前請自行核實環境。
- 用戶端前提：GAIA 面向 Claude Code；能否配合其他 agent 使用，官方未說明。
- 副作用與確認點：
/gaia-spec產生不可變的 SPEC 工件，產生前有提問確認環節；提交觸發的關卡會實際執行測試、E2E 和開發伺服器冒煙測試。 - 關卡範圍：官方列出的檢查項目就是型別檢查、lint、單元與 Storybook 測試、Playwright E2E 與開發伺服器冒煙測試這些；除此之外是否還有其他檢查未說明。
- 沙箱限制：官方寫明沙箱規則會阻止讀取 .env 檔案、金鑰與憑證檔案、憑據命名檔案（block reads of .env files, key and certificate files, credential-named files），用於減少 agent 接觸敏感憑據的機會。
- 合併約束：每次合併都有 Code Audit Team 稽核；稽核的具體產出形式與耗時官方未說明。
- 尚未確認：除
/gaia-spec外還有哪些操作、SPEC 的儲存位置、有無圖形介面、支援的語言範圍，官方頁面均未給出，請以專案內的實際說明為準。