wehub-resource-sync
318 lines
16 KiB
Markdown
318 lines
16 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!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 文件为准。
|
||
|
||
<p align="center">
|
||
<h1 align="center">Claude Code Game Studios</h1>
|
||
<p align="center">
|
||
将一次 Claude Code 会话变成完整的游戏开发工作室。
|
||
<br />
|
||
49 个智能体。73 项技能。一支协同运作的 AI 团队。
|
||
</p>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
|
||
<a href=".claude/agents"><img src="https://img.shields.io/badge/agents-49-blueviolet" alt="49 Agents"></a>
|
||
<a href=".claude/skills"><img src="https://img.shields.io/badge/skills-73-green" alt="73 Skills"></a>
|
||
<a href=".claude/hooks"><img src="https://img.shields.io/badge/hooks-12-orange" alt="12 Hooks"></a>
|
||
<a href=".claude/rules"><img src="https://img.shields.io/badge/rules-11-red" alt="11 Rules"></a>
|
||
<a href="https://docs.anthropic.com/en/docs/claude-code"><img src="https://img.shields.io/badge/built%20for-Claude%20Code-f5f5f5?logo=anthropic" alt="Built for Claude Code"></a>
|
||
<a href="https://www.buymeacoffee.com/donchitos3"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Support%20this%20project-FFDD00?logo=buymeacoffee&logoColor=black" alt="Buy Me a Coffee"></a>
|
||
<a href="https://github.com/sponsors/Donchitos"><img src="https://img.shields.io/badge/GitHub%20Sponsors-Support%20this%20project-ea4aaa?logo=githubsponsors&logoColor=white" alt="GitHub Sponsors"></a>
|
||
</p>
|
||
|
||
---
|
||
|
||
## 为何存在
|
||
|
||
用 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 免费且开源。若它为你节省时间或帮助你发布游戏，欢迎支持后续开发：
|
||
|
||
<p>
|
||
<a href="https://www.buymeacoffee.com/donchitos3"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black" alt="Buy Me a Coffee"></a>
|
||
|
||
<a href="https://github.com/sponsors/Donchitos"><img src="https://img.shields.io/badge/GitHub%20Sponsors-ea4aaa?style=for-the-badge&logo=githubsponsors&logoColor=white" alt="GitHub Sponsors"></a>
|
||
</p>
|
||
|
||
- **[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.
|