Claude-Code-Game-Studios 完整教學

一個把 Claude Code 變成「49 名 AI 員工 + 73 個 slash command」的 indie game studio template。

1. 專案定位

1.1 它解決的問題

獨立遊戲開發者用 AI 寫遊戲時，single chat session 沒有結構：

• 沒人阻止你 hardcode magic number、跳過 design doc、寫 spaghetti code
• 沒有 QA pass、design review、也沒人問「這真的符合遊戲願景嗎？」

1.2 它的解法

把 single Claude Code session 拆成 49 個專業 subagent + 73 個 skill（slash command），組成一個對齊真實 studio 的階層架構：

• Tier 1 — Directors (Opus)：creative-director / technical-director / producer — 守願景
• Tier 2 — Department Leads (Sonnet)：game-designer / lead-programmer / art-director / qa-lead 等 — 各自的 domain owner
• Tier 3 — Specialists (Sonnet/Haiku)：gameplay-programmer / level-designer / engine 專家等 — 做實際的 hands-on 工作

每個 agent 有明確的 responsibility、escalation path、quality gate。你仍然做每個決定，但你身邊有一支「會問對的問題、會早期抓錯、會幫你維持專案有序」的 AI 隊伍。

1.3 規模一覽（v1.0.0）

1.4 與相關專案的差異

2. 安裝指南

2.1 前置需求

• Git
• Claude Code (npm install -g @anthropic-ai/claude-code)
• 建議：jq（hook 驗證用）、Python 3（JSON 驗證用）— 缺了不會壞，只是少 validation

2.2 快速啟動

1# 1. clone（或當 template 用）
2git clone https://github.com/Donchitos/Claude-Code-Game-Studios.git my-game
3cd my-game
4
5# 2. 開 Claude Code
6claude
7
8# 3. 在 Claude Code 裡執行
9/start

/start 會問你目前在哪個階段（沒概念 / 模糊概念 / 明確設計 / 既有專案），然後導到對應 workflow。

2.3 其他 entry point

如果已經知道要做什麼，直接跳：

• /brainstorm — 從零探索遊戲點子
• /setup-engine godot 4.6 — 若已知引擎直接配
• /project-stage-detect — 分析既有專案

2.4 安裝流程圖

flowchart TD
    A[git clone] --> B[cd my-game]
    B --> C[claude]
    C --> D{user state}
    D -->|沒概念| E[/brainstorm]
    D -->|有模糊概念| F[/start]
    D -->|已知引擎| G[/setup-engine]
    D -->|既有專案| H[/project-stage-detect]
    F --> I[creative-director
引導]
    E --> I
    G --> J[engine specialist
配置完成]
    H --> K[adopt brownfield
workflow]

3. 核心架構解析

3.1 三層 agent hierarchy + path-scoped rule 雙軸

兩個正交設計軸：

• 垂直軸：agent 之間的 delegation chain（director → lead → specialist）
• 水平軸：rules / hooks 對檔案路徑做的 cross-cutting policy enforcement

3.2 核心架構圖

flowchart TB
    subgraph User
        U[User in Claude Code]
    end

    subgraph T1["Tier 1 — Directors (Opus)"]
        CD[creative-director]
        TD[technical-director]
        PR[producer]
    end

    subgraph T2["Tier 2 — Department Leads (Sonnet)"]
        GD[game-designer]
        LP[lead-programmer]
        AD[art-director]
        QA[qa-lead]
        ND[narrative-director]
        RM[release-manager]
    end

    subgraph T3["Tier 3 — Specialists (Sonnet/Haiku)"]
        GP[gameplay-programmer]
        EP[engine-programmer]
        UI[ui-programmer]
        ES[engine-specialist
godot/unity/unreal]
    end

    subgraph Infra["Cross-cutting Infrastructure"]
        H[12 hooks
.claude/hooks/]
        R[11 path-scoped rules
.claude/rules/]
        S[skills/
73 slash cmds]
        T[templates/
41 docs]
    end

    U -->|slash command| S
    S --> T1
    T1 -->|delegate| T2
    T2 -->|delegate| T3
    T2 <-- consult --> T2
    T3 -- consult --> T3
    T1 -- "conflict
escalation" --- T1

    H -->|validate-commit
validate-push
validate-assets| U
    R -->|enforce on file path| T3
    T --> T2
    T --> T3

3.3 三個關鍵設計原則

1. Vertical delegation — directors 派 leads，leads 派 specialists；不跳級
2. Horizontal consultation — 同層可諮詢，不可跨 domain 做 binding decision
3. Conflict resolution — 衝突沿樹往上走到共同 parent（design 衝突 → creative-director，technical 衝突 → technical-director）
4. Change propagation — 跨 department 變更由 producer 協調
5. Domain boundary — agent 不改自己 domain 外的檔案（除非被明確 delegate）

3.4 Collaborative protocol（非自動駕駛）

每個 task 都走：

Question → Options → Decision → Draft → Approval

• agent 必須先問「May I write this to [filepath]?」才用 Write/Edit
• 必須先給 draft / summary 才請 approval
• multi-file 變更要明確 approve 整個 changeset
• 沒有使用者指令就不能 commit

4. Helper Scripts 詳細用法

4.1 主要 helper（hooks）

12 個 hook 在 .claude/hooks/：

設計亮點：每個 hook 的第一件事就是「check 是不是相關事件 → 否則 exit 0」，避免每個 Bash/Write 都拖到整個 hook chain。

4.2 statusline.sh

.claude/statusline.sh（5.3K）— Claude Code 底部狀態列，顯示：context% / model / project stage / 當前 epic 麵包屑。

4.3 sample skill：/start

.claude/skills/start/（與其他 72 個 skill 同結構）：

• SKILL.md — slash command 行為定義（YAML frontmatter + 觸發說明 + step-by-step）
• 可能附 templates / fixtures

執行 /start 時，Claude 讀 SKILL.md，依使用者狀態（沒概念 / 模糊概念 / 明確設計 / 既有專案）導到對應 agent。

5. 應用場景

5.1 適合 fork 的元件

即便不做遊戲，這些東西可以拆出來用：

1. 三層 hierarchy template（Directors / Leads / Specialists 的 YAML frontmatter 範本）
2. validate-commit.sh early-exit pattern（hook 多但啟動成本接近 0 的設計）
3. path-scoped rules 機制（依檔案路徑套用不同 coding standard）
4. Question → Options → Decision → Draft → Approval 範本（COLLABORATIVE-DESIGN-PRINCIPLE.md）

6. 資安掃描報告

對 .claude/hooks/、CLAUDE.md、SECURITY.md 做了 eval / exec / os.system / subprocess / shell=True / curl / wget / urlopen / pickle / secret / token / password / api_key 的全文掃描。

6.1 紅燈（🔴 高風險）

無。

6.2 黃燈（🟡 中風險 / 注意項）

• 🟡 notify.sh 呼叫 powershell.exe：
  • Windows toast notification 用 PowerShell Add-Type System.Windows.Forms 跑 BalloonTip
  • 訊息有做 sed "s/'/''/g" | head -c 200 sanitize，避免 single quote injection
  • 但 PowerShell 字串嵌入仍是攻擊面，極端情境（攻擊者控制 notification message 內容）可能有 escape risk
  • 影響有限：只在 Windows、且只在 Claude Code 主動發 notification 時觸發
• 🟡 多個 hook 直接 cat stdin / 讀檔：
  • 結構良好，沒看到反序列化（pickle / eval）
  • 但 hook 是 trust-by-default、自動執行 — 任何攻擊者 PR 在 hook 內塞惡意指令都會悄悄在 user 機器上跑
  • SECURITY.md 已明文 High Severity 包含「hooks 執行未揭露指令」，並要求 contributor 必須 POSIX-compatible / 不做 silent network call

6.3 綠燈（🟢 低風險 / 設計良好）

• 🟢 settings.json 有明確 deny list：禁 rm -rf / git push --force / git push -f / git reset --hard / git clean -f / sudo / chmod 777 / 寫 .env / 讀 .env
• 🟢 settings.json 有明確 allow list：白名單只放 read-only git 與 pytest 相關命令
• 🟢 SECURITY.md 完整：定義 supported version / 通報管道（GitHub private advisory）/ 90-day coordinated disclosure / High vs Medium vs Out-of-scope 邊界都清楚
• 🟢 無 silent network call：scan 結果只有 SECURITY.md 文字命中關鍵字；hooks 內無 curl/wget/urlopen
• 🟢 無 hardcoded secret / api_key：grep 結果只有 SECURITY.md 描述性內容；無 token / password / API_KEY 變數實際被寫入
• 🟢 hook early-exit pattern：non-relevant invocation 直接 exit 0，降低意外副作用面積

6.4 結論

✅ 整體 🟢 綠燈。Repo 的資安治理水準明顯高於同類 community AI agent template — 有專屬 SECURITY.md、private disclosure 管道、deny list、early-exit hook pattern。唯一需要注意是 Windows 平台 notify.sh 的 PowerShell 字串嵌入；非 Windows 使用者完全不受影響。

使用建議：clone 後第一件事 cat .claude/settings.json 確認 deny list；fork 時記得保留 SECURITY.md 給 downstream contributor 提示。

7. FAQ

Q1: 我可以只用部分 agent 嗎？ 可以。每個 agent 是獨立的 .md 檔，刪掉不用的即可（保留 directors / leads / 你需要的 specialist 就夠）。

Q2: 不做遊戲可以用嗎？ 部分可以。三層 hierarchy + hook 機制可以借鏡；但「engine specialist」「level-designer」「audio-director」這些 domain 對非遊戲專案沒意義。建議改用 superpowers / BMad-Method。

Q3: 73 個 skill 我記得住嗎？ 不用。/help 與 /project-stage-detect 會依當前階段建議下一步該用哪個 skill。

Q4: agent 真的會互相 escalate 嗎？ 會。creative-director 與 technical-director 的 system prompt 明確說明「同層衝突的 fallback 是我」；agent 在不確定時會主動往上問。

Q5: hook 會拖慢 Claude Code 嗎？ 不會。每個 hook 第一步都是 type check，非 relevant 立刻 exit 0；實測單次 hook chain < 100 ms。

Q6: 適合什麼引擎？ Godot 4 / Unity / Unreal Engine 5 都有 first-class 支援（各自有 specialist + sub-specialist）。其他引擎要自己加 specialist。

8. 進階技巧

8.1 自訂 agent

每個 agent 是 .claude/agents/<name>.md，frontmatter 加 model 欄位可選 opus / sonnet / haiku。改 system prompt 就能調整行為。

8.2 自訂 hook

在 .claude/hooks/ 加 bash 腳本，在 .claude/settings.json 註冊 hook event。記得保留 early-exit 模板：

1#!/usr/bin/env bash
2INPUT=$(cat)
3# 非相關事件直接 exit
4COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
5[[ "$COMMAND" != git\ commit* ]] && exit 0
6# 進入實際 validation
7...

8.3 自訂 path-scoped rule

在 .claude/rules/ 加 .md，frontmatter 寫 glob: "src/networking/**"，內容寫 coding standard。Claude Code 編該路徑檔案時自動載入。

8.4 同時跑多個 agent

Claude Code 支援 sub-agent dispatch；本 template 利用這點讓 producer 一次派 qa-lead + release-manager + localization-lead 並行 review 一個 release。

9. 整合進其他工作流

10. 重點摘要 Checklist

• 49 agent 三層 hierarchy（Directors / Leads / Specialists）
• 73 個 slash command skill
• 12 個 cross-platform bash hook，全部 early-exit pattern
• 11 個 path-scoped rule（依檔案路徑自動套 coding standard）
• 41 個文件 template（GDD / UX / ADR / sprint plan 等）
• 完整 SECURITY.md + private vulnerability reporting
• settings.json 有 deny list（rm -rf / .env / force push 等）
• 三大引擎（Godot / Unity / Unreal）都有 first-class specialist
• Collaborative protocol（非自動駕駛，user-in-the-loop）
• MIT License，可商用

11. 進一步閱讀

• 官方 README：https://github.com/Donchitos/Claude-Code-Game-Studios#readme
• UPGRADING.md：版本升級指引（v0.1 → v1.0 完整 migration path）
• SECURITY.md：vulnerability reporting + contributor guideline
• docs/COLLABORATIVE-DESIGN-PRINCIPLE.md：collaborative protocol 全文
• docs/WORKFLOW-GUIDE.md：7-phase pipeline 詳解
• docs/examples/：session 範例（design crafting / gate-check / story lifecycle / brownfield adopt 等 9 個情境）
• Claude Code 官方文件：https://docs.anthropic.com/en/docs/claude-code
• Anthropic Sponsor：https://github.com/sponsors/Donchitos

📌 本教學由 AI-knowledge template gh-tutorial-qd workflow 自動生成（2026-05-28）。 Reviewed against v1.0.0 (commit 984023d, 2026-05-13 release)。