系統定位
Claude Code Game Studios 是一個可複製的遊戲專案範本。它把 Agent 角色、技能、設定解析、檔案規範與 Hook 放在儲存庫內，讓 Claude Code 依遊戲企劃、程式、美術、音效、測試與製作管理的分工處理任務。
輸入可以是一個遊戲構想、現有設計或既有專案；產出包含遊戲簡報、設計文件、開發工作項目、程式碼與驗收紀錄。使用者仍需提供引擎環境、選擇設計方向，並實際檢查遊戲是否符合預期。
| 元件 | 核對結果 | 用途 |
|---|---|---|
.claude/agents/ | 49 個 Agent 定義 | 指定角色責任、工具與委派方式 |
.claude/skills/ | 74 個 SKILL.md | 提供從構想到發布的操作流程 |
.claude/hooks/ | 18 個 shell 檔案，其中 15 個接入設定 | 其餘為輔助或選用診斷腳本 |
.claude/rules/ | 14 個路徑規則檔 | 依遊戲程式、資料、介面等位置載入規範 |
.claude/docs/templates/ | 根目錄 63 個檔案，另有 8 個指引檔 | 包含遊戲文件與框架維護範本 |
適合已有基本遊戲開發能力、希望把 AI 工作拆成可檢查任務的個人或小團隊。範本包含 Godot、Unity 與 Unreal 的角色及流程；它不附完整遊戲作品，也不替代各引擎、Claude Code 或外部素材的授權與使用成本。
安裝與驗證
- 未完成：
已安裝 Git 與可使用的 Claude Code。
- 未完成：
已安裝 Python 3；設定解析會使用它。
- 未完成：
shell 可以找到 Bash；Windows 使用 Git for Windows 提供的 Git Bash。
- 未完成：
準備要採用的遊戲引擎及其執行環境。
- 未完成：
建議安裝 jq，讓 Hook 更可靠地解析 JSON 輸入。
先檢查工具。jq 是建議項目；其餘版本輸出必須符合已安裝的工具，Python 輸出須為 Python 3：
git --version
bash --version
python3 --version
jq --versionWindows 環境也可能以 python 或 py 呼叫 Python 3，依實際安裝方式確認。缺少 Python 時，設定可能回退預設值，暫存資料 JSON 的 commit 也會被驗證腳本阻擋；缺少 Bash 則無法執行 Hook。
在工作目錄複製範本，從包含 CLAUDE.md、project.yaml 與 .claude/ 的根目錄啟動：
git clone https://github.com/Donchitos/Claude-Code-Game-Studios.git my-game
cd my-game
claude這會取得執行當下的預設分支；若要比對本文，另以本次固定 commit 檢查差異。GitHub 的 Use this template 也是官方提供的起始方式；既有遊戲導入與日後升級應先保留原始專案及自訂設定。
直接 clone 後，origin 仍指向範本儲存庫。首次推送前用 git remote -v 確認目的地，改用自己的遊戲儲存庫；/start 也會對仍指向上游的 remote 提醒。
首次啟動與引擎設定
在 Claude Code 輸入 /start，說明自己目前是沒有構想、已有概念、已有設計或已有遊戲。這個技能會確認專案狀態，經核准後保存階段、流程強度與自動化偏好，最後指出下一步；它不會自行執行那個下一步。
| 情境 | 操作 | 確認項目 |
|---|---|---|
| 新遊戲 | /start | 專案階段、modes.rigor、modes.automation |
| 尚未選引擎 | /setup-engine | 引擎、語言、版本與平台 |
| 已選 Godot | /setup-engine godot | 讓技能確認版本，使用實際可安裝或已安裝的版本 |
| 已有遊戲 | /adopt 或 /project-stage-detect | 保留既有結構，先辨識目前階段與缺漏 |
| 不知道下一步 | /help | 依目前產物與設定取得下一項操作 |
引擎設定會更新 project.yaml、CLAUDE.md 與引擎參考文件。確認程式碼根目錄：Godot 通常使用 src/，Unity 使用 Assets/，Unreal 使用 Source/<Module>/；不要讓 Agent 把 Unity 或 Unreal 程式都寫進 src/。
Godot 流程可在缺少專案檔時提議建立 project.godot。Unity 與 Unreal 應先用官方 Hub 或編輯器建立引擎專案，再回到設定流程；技能不會替使用者安裝引擎。
流程強度與自動化
modes.rigor 決定流程需要多少文件、審查與測試證據；modes.automation 決定 Agent 何時詢問使用者。兩者分開設定，調高流程強度不等於授權更多自主操作。
| 強度 | 設計與文件 | QA 與審查 | 適用起點 |
|---|---|---|---|
minimal | 單頁遊戲簡報，不要求 GDD；文件精簡、工作項目較大 | 最小證據要求、solo 審查、individual 團隊 | 小型試作、驗證玩法 |
standard | GDD 有 5 個必要章節，含數值規則時另需公式；文件與工作項目採中等粒度 | 標準證據、lean 審查、individual 團隊 | 需要追溯與分工的專案 |
full | GDD 要求 8 個章節；文件完整、工作項目細分 | 完整證據、full 審查、studio 團隊 | 複雜系統與跨職能協作 |
GDD 是 Game Design Document，記錄玩法與系統規格；ADR 是 Architecture Decision Record，記錄技術決策及理由。較重流程會讓需求、決策、實作與測試互相連結，也增加產生及維護文件的工作量。
| 自動化模式 | 決策與寫檔方式 |
|---|---|
collaborative | 依提問、選項、決策、草稿與核准流程合作；部分狀態與記憶寫入有既定例外 |
guided | 重大選擇由使用者決定；小型選擇及既有檔案更新可依規則繼續，新檔案仍需詢問 |
autonomous | 在模式規則內自行決定並記錄；automation_always_ask 類別仍需詢問 |
預設必問類別為 scope_changes、file_deletions 與 schema_changes。這是範本的協作規則；Claude Code 本身的工具權限、會話模式與執行環境仍會影響實際行為。
有效設定與覆寫
使用 /settings 檢查有效值及其來源，再修改需要調整的項目：
/settings
/settings modes.review_mode
/settings modes.rigor=standard
/settings --local modes.review_mode=solo設定優先序是允許的 project.local.yaml 個人覆寫、共享 project.yaml、舊版對應文字檔、modes.rigor 展開值，最後才是文件定義的預設值。無效列舉值會被略過並列在診斷中；每個有效值旁的來源可用來找出錯誤覆寫。
modes.rigor 會展開為以下六項設定。明確寫入其中一項，就會固定該項而蓋過強度推導；只寫入需要覆寫的項目：
modes.workflow與docs.density。qa.level與modes.story_granularity。modes.review_mode與team.size。
project.local.yaml 只接受白名單內的個人設定，例如審查模式、團隊大小與自動化偏好。modes.rigor 應寫入共享設定；放到本地檔案會被診斷，不能藉此改變團隊的產物要求。
若只有戰鬥等單一系統需要更完整的設計，使用系統層級覆寫；測試證據是否阻擋關閉則由 testing.strict.* 等設定影響。分別核對 workflow、qa.level 與實際驗收門檻，確認目前要求。
核心技能
構想
/brainstorm
建立遊戲方向
在 minimal 流程建立單頁遊戲簡報，保留玩法、MVP 範圍與建造順序，作為後續工作項目的來源。
設計
/design-system
細化系統規格
在需要系統設計的流程中補齊規則、公式、邊界與驗收條件，依流程強度決定必要章節。
規劃
/create-stories
拆出可實作的工作項目
minimal 從簡報建立 Epic 與 Story；standard 和 full 先確認既有 Epic、需求與相關決策。既有 Story 不會因此自動重寫。
開發
/dev-story
實作單一 Story
檢查前置條件，指定程式 Agent 與引擎專家，限制檔案範圍，整理測試、執行結果與交接。
驗收
/story-done
核對條件與證據
逐項檢查驗收條件、證據與審查結果，產生完成、附註完成、未評估或阻擋的結論；它本身不執行測試。
維護
/skill-test
檢查工作室技能
依結構、分類規準、行為規格或覆蓋率檢查框架，與遊戲本身的測試分開。
技能完整索引
斜線指令在 Claude Code 內輸入，不能直接貼進一般 shell。先使用主要流程，遇到對應任務再選其他技能：
| 類別 | 指令 |
|---|---|
| 引導與導航 | /start、/help、/project-stage-detect、/setup-engine、/adopt、/settings |
| 遊戲設計 | /brainstorm、/map-systems、/design-system、/quick-design、/review-all-gdds、/propagate-design-change |
| 美術與資產 | /art-bible、/asset-spec、/asset-audit |
| 使用體驗與介面 | /ux-design、/ux-review |
| 架構 | /create-architecture、/architecture-decision、/architecture-review、/create-control-manifest |
| 工作項目與 Sprint | /create-epics、/create-stories、/dev-story、/sprint-plan、/sprint-status、/story-readiness、/story-done、/estimate |
| 審查與分析 | /design-review、/code-review、/balance-check、/content-audit、/scope-check、/perf-profile、/tech-debt、/gate-check、/consistency-check、/security-audit |
| QA 與測試 | /qa-plan、/smoke-check、/soak-test、/regression-suite、/test-setup、/test-helpers、/test-evidence-review、/test-flakiness、/skill-test、/skill-improve |
| 製作管理 | /milestone-review、/retrospective、/bug-report、/bug-triage、/reverse-document、/playtest-report |
| 發布 | /release-checklist、/launch-checklist、/changelog、/patch-notes、/hotfix、/day-one-patch |
| 原型與內容 | /prototype、/vertical-slice、/onboard、/localize |
| 團隊協作 | /team-combat、/team-narrative、/team-ui、/team-release、/team-polish、/team-audio、/team-level、/team-live-ops、/team-qa |
Agent 分工與任務協調
Agent 定義分成總監、部門主管與專家。角色層級決定責任與升級路徑；呼叫哪些 Agent，則依目前技能、團隊設定與任務需要決定。
| 層級或領域 | 代表角色 | 責任 |
|---|---|---|
| 總監 | creative-director、technical-director、producer | 遊戲方向、技術取捨與跨部門協調 |
| 部門主管 | game-designer、lead-programmer、art-director、qa-lead | 領域規劃、品質要求與委派 |
| 實作專家 | gameplay-programmer、ui-programmer、ai-programmer、network-programmer | 在指定檔案與驗收範圍內完成工作 |
| Godot | godot-specialist 與語言、Shader、GDExtension 專家 | 核對版本、語言與引擎特性 |
| Unity | unity-specialist 與 DOTS、Shader、Addressables、UI Toolkit 專家 | 使用 Unity 的程式碼與資產配置 |
| Unreal | unreal-specialist 與 GAS、Blueprint、Replication、UI 專家 | 使用 Unreal 的模組與引擎工作流程 |
creative-director、technical-director 與 producer 指定 Opus，部分主管及專家指定 Sonnet，其餘繼承目前會話模型。評估成本時應看實際呼叫、上下文與重試，不能把三層角色直接當成固定的模型費用分層。
協調規則要求垂直委派、同層諮詢與向共同上級處理衝突；跨部門變更由 producer 協調，跨領域改檔需要明確委派。prototyper 預設使用獨立 worktree，其餘角色的協作規則不會自動建立檔案鎖、全面隔離或發布佇列。
prototyper 的 worktree 從最後一次 commit 建立，可能看不到尚未提交的引擎設定或簡報。啟動前確認所需輸入已保存於可用版本；收到成果後，按代理回報的工作樹路徑與分支檢查，再決定合併或複製回主專案。
使用者與有效設定
確認遊戲方向、流程強度與可自主處理的範圍
- project.yaml 與個人覆寫
- 遊戲簡報或設計文件
規劃與任務契約
把需求整理成有邊界的 Story
- 驗收條件與檔案範圍
- 需要時連結需求與架構決策
委派與實作
程式 Agent 配合已設定的引擎專家
- 遊戲程式與相應測試
- 實際執行與保留畫面
驗收與交接
對照條件、證據與未完成項目後更新狀態
- Story 完成紀錄
- 會話檢查點與後續任務
這是技能之間的工作流程，並非一個另行部署的排程服務。
Story 開發與遊戲驗收
Story 是一個可實作的工作項目，包含驗收條件、範圍與必要的技術依據。/dev-story 先檢查依賴、ADR 狀態與工作流程要求，再選擇程式 Agent；Config/Data 類型可以直接處理資料值而不另開程式 Agent。
| 階段 | 應留下的紀錄 |
|---|---|
| 開始前 | Story 路徑、適用流程、前置條件與尚缺資料 |
| 委派 | 目標、驗收條件、排除範圍、可修改檔案與引擎專家 |
| 實作後 | 修改清單、測試與執行結果、未完成項目 |
| 關閉時 | 每個驗收條件的狀態、證據位置、偏離範圍與審查結論 |
/story-done 會檢查檔案、讀取證據並詢問無法直接判定的結果，但不會執行測試。「測試檔存在」只能證明有檔案；要主張測試通過，仍需實際執行的紀錄。
對玩家看得見的變更，執行與觀察程序要求開啟遊戲、到達受影響畫面、取得截圖並讀圖檢查。保留影像於 production/qa/evidence/，另以檔案雜湊紀錄證據對應的程式碼；之後修改程式碼時，舊圖不能直接當作新版本證據。
目前 /story-done 對過期或缺少的雜湊戳記只回報，不會因此改變驗收結論。使用者仍需確認受影響畫面已重新擷取；畫面手感、反應時間與音效同步也需要實際遊玩，不能只看靜態截圖。
| 條件 | 實際影響 |
|---|---|
qa.level: minimal | Logic／Integration 的自動測試證據可免除，玩家可見內容仍要求執行與截圖 |
qa.level: standard 或 full | 依 Story 類型與驗收條件要求相應證據；full 對未測條件更嚴格 |
testing.strict.visual 或 testing.strict.ui 明確為 false | 缺少相應觀察證據可降為附註，允許帶著缺口關閉 |
| 只有 parse、編譯或 headless 執行 | 不能證明實際遊戲畫面正確 |
README 對「有畫面才能關閉」的說法較簡化；實際門檻還受明確覆寫影響。查看完成紀錄中的 OBSERVED、N/A 或 NOT VERIFIED，並確認 N/A 有符合情境的理由。
Hook 與權限限制
Hook 的觸發與退出碼不同，不能把全部 Hook 都理解成強制阻擋。以下依腳本區分；本次另以隔離案例測試資料 JSON、整份與限範圍讀取、推送警告及覆寫警告：
| 機制 | 行為 | 操作上的含義 |
|---|---|---|
validate-commit.sh | 無效的暫存資料 JSON 可回傳阻擋結果 | commit 前先修正資料；缺少 Python 也不能略過這項驗證 |
validate-push.sh | 對受保護分支推送等操作發出警告 | 警告本身不等於拒絕推送，仍需儲存庫與工具權限控管 |
validate-read.sh | 在功能啟用時阻擋超過門檻的設計文件整份讀取；預設 40 KB，可由 features.read_guard_kb 調整 | 改讀特定章節或有限範圍 |
validate-write.sh | 遇到禁止覆寫或範圍衝突等情況發出警告 | 仍依賴執行 Agent 遵守，檔案不會因此上鎖 |
validate-registry.sh | 對刪除、重新編號或非法狀態發出警告 | 變更需求登錄時人工核對既有 ID 與狀態 |
validate-assets.sh | 寫入後檢查資料 JSON 與適用的命名規則 | 事後訊息不代表已自動還原檔案 |
| Agent 與 session Hooks | 記錄呼叫、完成、狀態與缺少產物等情況 | 用來追查工作，不證明交付內容已符合需求 |
.claude/settings.json 另有工具允許與拒絕規則，以及 permissions.defaultMode。範本的模式、Claude Code 會話權限與 GitHub 分支保護各自處理不同層面的操作；不要用提示詞中的「必須核准」取代實際權限控制。
Windows 的通知使用 PowerShell；macOS 與 Linux 的該通知腳本不會顯示桌面通知。部分 Git 拒絕規則以命令文字比對，連 commit 訊息中含有符合模式的文字也可能被攔截；先檢查命令與訊息，不要為了通過而移除整組規則。
操作原則
先取得可玩的最小結果
使用 minimal 的單頁簡報、工作項目、實作與驗收路徑。當跨系統依賴或交接需要增加，再提高流程強度；產生更多文件不能證明遊戲體驗改善。
把檔案交接寫進委派
指定 Story、可修改檔案與輸出位置。只收到敘述而沒有預期產物時，檢查 Agent 稽核紀錄與檔案；不要把代理回覆當成已完成。
恢復時先讀會話檢查點
production/session-state/active.md 保存目前任務。壓縮上下文、重啟或清除會話後，先讀它並比對實際檔案與 Git 狀態，再繼續。
按需讀取大型設計文件
依 Story 的需求 ID、ADR 摘要及相關章節取得上下文。來源版本不一致時再檢查差異，避免把整套設計文件反覆塞進每個 Agent。
分開記錄已測與未測
實際執行、畫面觀察、測試檔存在與使用者口頭確認分別記錄。缺少引擎、裝置或測試資料時，保留缺口，不改寫成通過。
最小遊戲操作範例
以下是以 Godot 製作小型收集遊戲的示範需求與操作順序，並非本次已執行的遊戲成果。引擎版本由使用者的環境與 /setup-engine 確認；每一步都依目前協作模式完成必要核准後，再執行下一步。
Create a small 2D collection game in Godot.
The player moves inside one room and collects items.
Show the collected count and a completion screen.
Allow restarting without restarting the app.
Use placeholder visuals.
Exclude combat, accounts, networking and monetization.
Keep the project at minimal rigor and collaborative automation.確認流程與引擎
執行 /start，確認 minimal 與 collaborative，接著用 /setup-engine godot 設定引擎、語言與實際版本。核對 project.yaml 與引擎參考文件。
建立單頁簡報
執行 /brainstorm，提供上方需求。確認 design/game-brief.md 記錄核心玩法、MVP 範圍與 Build order，並排除尚未要做的系統。
拆出 Story
執行 /create-stories。minimal 可從簡報建立 Epic，不必先跑完整的 /create-epics 流程；核對 production/epics/ 下實際產生的 Story 路徑、條件與順序。
逐項實作
將實際 Story 路徑交給 /dev-story。核對可修改檔案，完成移動、收集、介面與重新開始等已接受的工作項目；新增功能另開任務。
開啟與檢查遊戲
執行遊戲，確認角色可移動、收集數字正確、完成畫面可讀，且重新開始會清除前次狀態。保留受影響畫面的截圖與執行結果。
驗收並繼續下一項
把同一個 Story 路徑交給 /story-done，檢查每個條件及證據。阻擋項先修正，附註與未測項保留在紀錄；完成狀態不會自動授權 commit 或發布。
較完整的流程會加入系統設計、架構與 Epic；standard／full 的 Story 會先做 /story-readiness，實作後再依規則做 /code-review，才交由 /story-done。依有效設定選擇需要執行的技能。
框架自訂與測試
先保留自訂前的版本，再修改 Agent、技能、路徑規則或 Hook。選擇一個具體工作流程驗證，例如變更 /dev-story 後，檢查它是否仍能辨識未接受的 ADR、限制檔案範圍並回報缺少的證據。
/skill-test static dev-story
/skill-test category dev-story
/skill-test spec dev-story
/skill-test audit
/skill-improve dev-story/skill-test 的四種模式讀取技能與規格檔案，不會實際呼叫被測技能。/skill-improve 的分數變化也只涵蓋該檢查方式；要確認執行行為，仍需用受控任務驗證。框架的品質規格放在 studio-tests/，遊戲測試放在專案對應的測試根目錄。
本次在隔離副本完成 shell 語法、設定解析與部分 Hook 行為測試，未啟動 Claude Code 代理流程，也未建置或遊玩 Godot、Unity、Unreal 成品。這些檢查支持腳本行為的描述，不代表遊戲產出品質已獲驗證。
限制與故障排查
| 症狀或限制 | 檢查與處理 |
|---|---|
| 設定變更沒有生效 | 看 /settings 的來源；檢查本地覆寫、舊版文字檔、明確子設定與 Python |
改了 modes.rigor，部分值仍不動 | 明確寫入的六項子設定會蓋過展開值；保留有意的覆寫，移除誤寫項目前先確認影響 |
| 技能在前處理階段中止 | 檢查 Bash、技能的精確工具允許規則與設定解析路徑；不要直接放寬成所有 shell 指令 |
| 設定可保存但沒有行為效果 | 部分鍵僅預留，例如 strict_gate_checks、project.kind 與 features.token_budget_warn_at；核對 effects map 的實作狀態 |
| 推送、覆寫或登錄變更只出現警告 | 對應 Hook 可能回傳成功；檢查權限與流程，不要假設操作已被停止 |
| 已有截圖，但程式碼又改過 | 比對證據的檔案雜湊，重新擷取受影響畫面 |
| Story 顯示完成，遊戲仍有問題 | 檢查是否帶有附註、人工確認或未測項；重現問題並建立修復工作 |
| 多個 Agent 修改相同範圍 | 減少並行、明確分配檔案與整合責任；角色分工不會自動避免 Git 衝突 |
升級與後續操作
升級前建立可回復的 Git 版本，閱讀 UPGRADING.md。與範本共享 Git 歷史時，官方建議新增上游 remote 後合併；沒有共同歷史時，使用選擇性更新或人工合併，避免強行合併無關歷史。
| 檔案或變更 | 升級處理 |
|---|---|
CLAUDE.md 與 project.yaml | 保留已選引擎、平台、專案與模式設定，逐項合併結構變更 |
自訂 .claude/agents/、skills 與 rules | 先比較差異；整批取代會覆蓋同名檔案中的自訂內容 |
舊專案沒有明確設定 modes.rigor | 新預設 minimal 可能改變尚未明確設定的值；需要維持舊行為時明確指定 standard |
| 框架版本標記 | 與實際更新檔案核對；只保留舊 project.yaml 時，版本欄可能落後 |
首次採用時，先完成一個小型遊戲的可玩流程與證據，再決定哪些系統需要較完整的文件和審查。團隊已在使用其他 Agent Harness 時，可先借用 Story 契約、設定來源顯示及遊戲畫面證據，分別驗證後再整合更多角色。
官方來源與核對範圍
核對日期為 2026-10-20。社群入口為 GitHub Discussions 與 Issues。原始碼採 MIT License，散布相應內容時須保留授權要求的聲明。