> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/Donchitos/Claude-Code-Game-Studios) · [上游 README](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
Claude Code Game Studios
将一次 Claude Code 会话变成完整的游戏开发工作室。
49 个智能体。73 项技能。一支协同运作的 AI 团队。
---
## 为何存在
用 AI 独自做游戏很强大——但单次聊天会话没有结构。没人会阻止你硬编码魔法数字、跳过设计文档，或写出意大利面条式代码。没有 QA 环节，没有设计评审，也没有人会问「这真的符合游戏的愿景吗？」
**Claude Code Game Studios** 通过为你的 AI 会话赋予真实工作室的结构来解决这一问题。你不再只有一个通用助手，而是获得 49 个按工作室层级组织的专业化智能体——守护愿景的总监、负责各自领域的部门负责人，以及动手执行的专业人员。每个智能体都有明确的职责、升级路径和质量关卡。
结果是：你仍然做出每一个决策，但现在你有一支团队会提出正确的问题、及早发现错误，并让项目从最初头脑风暴到上线发布始终保持有序。
---
## 目录
- [包含内容](#whats-included)
- [工作室层级](#studio-hierarchy)
- [斜杠命令](#slash-commands)
- [快速开始](#getting-started)
- [升级](#upgrading)
- [项目结构](#project-structure)
- [工作原理](#how-it-works)
- [设计理念](#design-philosophy)
- [自定义](#customization)
- [平台支持](#platform-support)
- [社区](#community)
- [支持本项目](#supporting-this-project)
- [许可证](#license)
---
## 包含内容
| Category | Count | Description |
|----------|-------|-------------|
| **Agents** | 49 | 覆盖设计、编程、美术、音频、叙事、QA 与制作等方向的专业化子智能体 |
| **Skills** | 73 | 覆盖各工作流阶段的斜杠命令（`/start`、`/design-system`、`/create-epics`、`/create-stories`、`/dev-story`、`/story-done` 等） |
| **Hooks** | 12 | 在提交、推送、资源变更、会话生命周期、智能体审计轨迹与缺口检测时自动校验 |
| **Rules** | 11 | 在编辑玩法、引擎、AI、UI、网络代码等时按路径强制执行的编码规范 |
| **Templates** | 41 | GDD、UX 规格、ADR、冲刺计划、HUD 设计、无障碍等文档模板 |
## 工作室层级
智能体分为三个层级，对应真实工作室的运作方式：
```
Tier 1 — Directors (Opus)
creative-director technical-director producer
Tier 2 — Department Leads (Sonnet)
game-designer lead-programmer art-director
audio-director narrative-director qa-lead
release-manager localization-lead
Tier 3 — Specialists (Sonnet/Haiku)
gameplay-programmer engine-programmer ai-programmer
network-programmer tools-programmer ui-programmer
systems-designer level-designer economy-designer
technical-artist sound-designer writer
world-builder ux-designer prototyper
performance-analyst devops-engineer analytics-engineer
security-engineer qa-tester accessibility-specialist
live-ops-designer community-manager
```
### 引擎专家
模板为三大主流引擎都提供了智能体组合。请选用与项目匹配的那一套：
| Engine | Lead Agent | Sub-Specialists |
|--------|-----------|-----------------|
| **Godot 4** | `godot-specialist` | GDScript, Shaders, GDExtension |
| **Unity** | `unity-specialist` | DOTS/ECS, Shaders/VFX, Addressables, UI Toolkit |
| **Unreal Engine 5** | `unreal-specialist` | GAS, Blueprints, Replication, UMG/CommonUI |
## 斜杠命令
在 Claude Code 中输入 `/` 即可访问全部 73 项技能：
**入门与导航**
`/start` `/help` `/project-stage-detect` `/setup-engine` `/adopt`
**游戏设计**
`/brainstorm` `/map-systems` `/design-system` `/quick-design` `/review-all-gdds` `/propagate-design-change`
**美术与资源**
`/art-bible` `/asset-spec` `/asset-audit`
**UX 与界面设计**
`/ux-design` `/ux-review`
**架构**
`/create-architecture` `/architecture-decision` `/architecture-review` `/create-control-manifest`
**故事与冲刺**
`/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` `/onboard` `/localize`
**团队编排**（在单一功能上协调多个智能体）
`/team-combat` `/team-narrative` `/team-ui` `/team-release` `/team-polish` `/team-audio` `/team-level` `/team-live-ops` `/team-qa`
## 快速开始
### 前置条件
- [Git](https://git-scm.com/)
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`npm install -g @anthropic-ai/claude-code`)
- **推荐**： [jq](https://jqlang.github.io/jq/)（用于 hook 校验）以及 Python 3（用于 JSON 校验）
若缺少可选工具，所有 hook 会优雅降级——不会导致崩溃，只是失去校验能力。
### 安装配置
1. **克隆或作为模板使用**：
```bash
git clone https://github.com/Donchitos/Claude-Code-Game-Studios.git my-game
cd my-game
```
2. **打开 Claude Code** 并启动会话：
```bash
claude
```
3. **运行 `/start`** — 系统会询问你当前处于哪一阶段（毫无头绪、模糊概念、清晰设计、已有作品），并引导你进入合适的工作流。不做任何假设。
若你已明确需求，也可直接跳转到特定技能：
- `/brainstorm` — 从零探索游戏创意
- `/setup-engine godot 4.6` — 若已确定引擎则进行配置
- `/project-stage-detect` — 分析现有项目
## 升级
已在使用本模板的旧版本？请参阅 [UPGRADING.md](UPGRADING.md)
获取分步迁移说明、各版本间变更说明，
以及哪些文件可安全覆盖、哪些需要手动合并。
## 项目结构
```
CLAUDE.md # Master configuration
.claude/
settings.json # Hooks, permissions, safety rules
agents/ # 49 agent definitions (markdown + YAML frontmatter)
skills/ # 73 slash commands (subdirectory per skill)
hooks/ # 12 hook scripts (bash, cross-platform)
rules/ # 11 path-scoped coding standards
statusline.sh # Status line script (context%, model, stage, epic breadcrumb)
docs/
workflow-catalog.yaml # 7-phase pipeline definition (read by /help)
templates/ # 41 document templates
src/ # Game source code
assets/ # Art, audio, VFX, shaders, data files
design/ # GDDs, narrative docs, level designs
docs/ # Technical documentation and ADRs
tests/ # Test suites (unit, integration, performance, playtest)
tools/ # Build and pipeline tools
prototypes/ # Throwaway prototypes (isolated from src/)
production/ # Sprint plans, milestones, release tracking
```
## 工作原理
### Agent 协调
Agent 遵循结构化的委派模型：
1. **纵向委派（Vertical delegation）** — 总监委派给负责人，负责人再委派给专家
2. **横向咨询（Horizontal consultation）** — 同级 Agent 可以相互咨询，但不能做出具有约束力的跨领域决策
3. **冲突解决（Conflict resolution）** — 分歧向上升级至共同上级（设计由 `creative-director` 负责，技术由 `technical-director` 负责）
4. **变更传播（Change propagation）** — 跨部门变更由 `producer` 协调
5. **领域边界（Domain boundaries）** — 未经明确委派，Agent 不得修改其领域之外的文件
### 协作式，而非自主式
这**不是**自动驾驶系统。每个 Agent 都遵循严格的协作协议：
1. **提问（Ask）** — Agent 在提出方案前先提问
2. **展示选项（Present options）** — Agent 展示 2-4 个选项及利弊
3. **由你决定（You decide）** — 始终由用户拍板
4. **起草（Draft）** — Agent 在定稿前展示工作成果
5. **批准（Approve）** — 未经你签字确认，不会写入任何内容
你始终掌控全局。Agent 提供结构与专业知识，而非自主权。
### 自动化安全保障
**Hooks** 会在每次会话中自动运行：
| Hook | 触发时机 | 作用 |
|------|---------|------|
| `validate-commit.sh` | PreToolUse (Bash) | 检查硬编码值、TODO 格式、JSON 有效性、设计文档章节 — 若命令不是 `git commit` 则提前退出 |
| `validate-push.sh` | PreToolUse (Bash) | 向受保护分支推送时发出警告 — 若命令不是 `git push` 则提前退出 |
| `validate-assets.sh` | PostToolUse (Write/Edit) | 验证命名约定与 JSON 结构 — 若文件不在 `assets/` 中则提前退出 |
| `session-start.sh` | Session open | 显示当前分支与最近提交，便于定位 |
| `detect-gaps.sh` | Session open | 检测新项目（建议 `/start`）以及存在代码或原型时缺失的设计文档 |
| `pre-compact.sh` | Before compaction | 保留会话进度笔记 |
| `post-compact.sh` | After compaction | 提醒 Claude 从 `active.md` 恢复会话状态 |
| `notify.sh` | Notification event | 通过 PowerShell 显示 Windows 吐司通知 |
| `session-stop.sh` | Session close | 将 `active.md` 归档至会话日志并记录 git 活动 |
| `log-agent.sh` | Agent spawned | 审计追踪开始 — 记录子 Agent 调用 |
| `log-agent-stop.sh` | Agent stops | 审计追踪结束 — 完成子 Agent 记录 |
| `validate-skill-change.sh` | PostToolUse (Write/Edit) | 在任何 `.claude/skills/` 变更后建议运行 `/skill-test` |
> **Note**：`validate-commit.sh`、`validate-assets.sh` 和 `validate-skill-change.sh` 会在每次 Bash/Write 工具调用时触发，当命令或文件路径不相关时立即退出（exit 0）。这是正常的 Hook 行为 — 并非性能问题。
`settings.json` 中的**权限规则**会自动允许安全操作（git status、测试运行），并阻止危险操作（force push、`rm -rf`、读取 `.env` 文件）。
### 路径作用域规则
编码标准会根据文件位置自动强制执行：
| 路径 | 强制执行项 |
|------|----------|
| `src/gameplay/**` | 数据驱动取值、delta time 用法、禁止 UI 引用 |
| `src/core/**` | 热路径零分配、线程安全、API 稳定性 |
| `src/ai/**` | 性能预算、可调试性、数据驱动参数 |
| `src/networking/**` | 服务端权威、版本化消息、安全性 |
| `src/ui/**` | 不持有游戏状态、支持本地化、无障碍 |
| `design/gdd/**` | 必需的 8 个章节、公式格式、边界情况 |
| `tests/**` | 测试命名、覆盖率要求、fixture 模式 |
| `prototypes/**` | 宽松标准、需要 README、记录假设 |
## 设计理念
本模板植根于专业游戏开发实践：
- **MDA Framework** — Mechanics、Dynamics、Aesthetics 分析，用于游戏设计
- **Self-Determination Theory** — Autonomy、Competence、Relatedness，用于玩家动机
- **Flow State Design** — 挑战与技能平衡，用于玩家参与度
- **Bartle Player Types** — 受众定位与验证
- **Verification-Driven Development** — 先测试，后实现
## 自定义
这是一份**模板**，而非锁定的框架。一切均可自定义：
- **增删 Agent** — 删除不需要的 Agent 文件，为你的领域添加新 Agent
- **编辑 Agent 提示词** — 调整 Agent 行为，添加项目专属知识
- **修改 skills** — 调整工作流以匹配团队流程
- **添加规则** — 为项目目录结构创建新的路径作用域规则
- **调整 hooks** — 调整验证严格度，添加新检查
- **选择引擎** — 使用 Godot、Unity 或 Unreal Agent 集（或不使用）
- **设置审查强度** — `full`（所有总监关卡）、`lean`（仅阶段关卡）或 `solo`（无）。在 `/start` 期间设置，或编辑 `production/review-mode.txt`。可在任意 skill 上用 `--review solo` 按次覆盖
## 平台支持
主要在 **Windows 10** 上使用 Git Bash 进行开发与测试。所有 hooks 使用 POSIX 兼容模式（`grep -E`，而非 `grep -P`），并包含缺失工具的降级方案，因此应可在 macOS 和 Linux 上运行。`notify.sh` hook 使用 PowerShell 实现 Windows 吐司通知，在其他平台上为 no-op — macOS/Linux 的桌面通知尚未接入。跨平台测试仍在进行中；如遇平台相关问题，请提交 issue。
## 社区
- **Discussions** — [GitHub Discussions](https://github.com/Donchitos/Claude-Code-Game-Studios/discussions) for questions, ideas, and showcasing what you've built
- **Issues** — [Bug reports and feature requests](https://github.com/Donchitos/Claude-Code-Game-Studios/issues)
---
## 支持本项目
Claude Code Game Studios 免费且开源。若它为你节省时间或帮助你发布游戏，欢迎支持后续开发：
- **[Buy Me a Coffee](https://www.buymeacoffee.com/donchitos3)** — one-time support
- **[GitHub Sponsors](https://github.com/sponsors/Donchitos)** — recurring support through GitHub
赞助有助于投入时间维护 skills、添加新 Agent、跟进 Claude Code 与引擎 API 变更，以及响应社区 issue。
---
*Built for Claude Code. Maintained and extended — contributions welcome via [GitHub Discussions](https://github.com/Donchitos/Claude-Code-Game-Studios/discussions).*
## 许可证
MIT License. See [LICENSE](LICENSE) for details.