diff --git a/README.md b/README.md index c08cec9..593f3c3 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,15 @@ + +> [!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

- Turn a single Claude Code session into a full game development studio. + 将一次 Claude Code 会话变成完整的游戏开发工作室。
- 49 agents. 73 skills. One coordinated AI team. + 49 个智能体。73 项技能。一支协同运作的 AI 团队。

@@ -20,47 +26,47 @@ --- -## Why This Exists +## 为何存在 -Building a game solo with AI is powerful — but a single chat session has no structure. No one stops you from hardcoding magic numbers, skipping design docs, or writing spaghetti code. There's no QA pass, no design review, no one asking "does this actually fit the game's vision?" +用 AI 独自做游戏很强大——但单次聊天会话没有结构。没人会阻止你硬编码魔法数字、跳过设计文档，或写出意大利面条式代码。没有 QA 环节，没有设计评审，也没有人会问「这真的符合游戏的愿景吗？」 -**Claude Code Game Studios** solves this by giving your AI session the structure of a real studio. Instead of one general-purpose assistant, you get 49 specialized agents organized into a studio hierarchy — directors who guard the vision, department leads who own their domains, and specialists who do the hands-on work. Each agent has defined responsibilities, escalation paths, and quality gates. +**Claude Code Game Studios** 通过为你的 AI 会话赋予真实工作室的结构来解决这一问题。你不再只有一个通用助手，而是获得 49 个按工作室层级组织的专业化智能体——守护愿景的总监、负责各自领域的部门负责人，以及动手执行的专业人员。每个智能体都有明确的职责、升级路径和质量关卡。 -The result: you still make every decision, but now you have a team that asks the right questions, catches mistakes early, and keeps your project organized from first brainstorm to launch. +结果是：你仍然做出每一个决策，但现在你有一支团队会提出正确的问题、及早发现错误，并让项目从最初头脑风暴到上线发布始终保持有序。 --- -## Table of Contents +## 目录 -- [What's Included](#whats-included) -- [Studio Hierarchy](#studio-hierarchy) -- [Slash Commands](#slash-commands) -- [Getting Started](#getting-started) -- [Upgrading](#upgrading) -- [Project Structure](#project-structure) -- [How It Works](#how-it-works) -- [Design Philosophy](#design-philosophy) -- [Customization](#customization) -- [Platform Support](#platform-support) -- [Community](#community) -- [Supporting This Project](#supporting-this-project) -- [License](#license) +- [包含内容](#whats-included) +- [工作室层级](#studio-hierarchy) +- [斜杠命令](#slash-commands) +- [快速开始](#getting-started) +- [升级](#upgrading) +- [项目结构](#project-structure) +- [工作原理](#how-it-works) +- [设计理念](#design-philosophy) +- [自定义](#customization) +- [平台支持](#platform-support) +- [社区](#community) +- [支持本项目](#supporting-this-project) +- [许可证](#license) --- -## What's Included +## 包含内容 | Category | Count | Description | |----------|-------|-------------| -| **Agents** | 49 | Specialized subagents across design, programming, art, audio, narrative, QA, and production | -| **Skills** | 73 | Slash commands for every workflow phase (`/start`, `/design-system`, `/create-epics`, `/create-stories`, `/dev-story`, `/story-done`, etc.) | -| **Hooks** | 12 | Automated validation on commits, pushes, asset changes, session lifecycle, agent audit trail, and gap detection | -| **Rules** | 11 | Path-scoped coding standards enforced when editing gameplay, engine, AI, UI, network code, and more | -| **Templates** | 41 | Document templates for GDDs, UX specs, ADRs, sprint plans, HUD design, accessibility, and more | +| **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 设计、无障碍等文档模板 | -## Studio Hierarchy +## 工作室层级 -Agents are organized into three tiers, matching how real studios operate: +智能体分为三个层级，对应真实工作室的运作方式： ``` Tier 1 — Directors (Opus) @@ -82,9 +88,9 @@ Tier 3 — Specialists (Sonnet/Haiku) live-ops-designer community-manager ``` -### Engine Specialists +### 引擎专家 -The template includes agent sets for all three major engines. Use the set that matches your project: +模板为三大主流引擎都提供了智能体组合。请选用与项目匹配的那一套： | Engine | Lead Agent | Sub-Specialists | |--------|-----------|-----------------| @@ -92,84 +98,83 @@ The template includes agent sets for all three major engines. Use the set that m | **Unity** | `unity-specialist` | DOTS/ECS, Shaders/VFX, Addressables, UI Toolkit | | **Unreal Engine 5** | `unreal-specialist` | GAS, Blueprints, Replication, UMG/CommonUI | -## Slash Commands +## 斜杠命令 -Type `/` in Claude Code to access all 73 skills: +在 Claude Code 中输入 `/` 即可访问全部 73 项技能： -**Onboarding & Navigation** +**入门与导航** `/start` `/help` `/project-stage-detect` `/setup-engine` `/adopt` -**Game Design** +**游戏设计** `/brainstorm` `/map-systems` `/design-system` `/quick-design` `/review-all-gdds` `/propagate-design-change` -**Art & Assets** +**美术与资源** `/art-bible` `/asset-spec` `/asset-audit` -**UX & Interface Design** +**UX 与界面设计** `/ux-design` `/ux-review` -**Architecture** +**架构** `/create-architecture` `/architecture-decision` `/architecture-review` `/create-control-manifest` -**Stories & Sprints** +**故事与冲刺** `/create-epics` `/create-stories` `/dev-story` `/sprint-plan` `/sprint-status` `/story-readiness` `/story-done` `/estimate` -**Reviews & Analysis** +**评审与分析** `/design-review` `/code-review` `/balance-check` `/content-audit` `/scope-check` `/perf-profile` `/tech-debt` `/gate-check` `/consistency-check` `/security-audit` -**QA & Testing** +**QA 与测试** `/qa-plan` `/smoke-check` `/soak-test` `/regression-suite` `/test-setup` `/test-helpers` `/test-evidence-review` `/test-flakiness` `/skill-test` `/skill-improve` -**Production** +**制作** `/milestone-review` `/retrospective` `/bug-report` `/bug-triage` `/reverse-document` `/playtest-report` -**Release** +**发布** `/release-checklist` `/launch-checklist` `/changelog` `/patch-notes` `/hotfix` `/day-one-patch` -**Creative & Content** +**创意与内容** `/prototype` `/onboard` `/localize` -**Team Orchestration** (coordinate multiple agents on a single feature) +**团队编排**（在单一功能上协调多个智能体） `/team-combat` `/team-narrative` `/team-ui` `/team-release` `/team-polish` `/team-audio` `/team-level` `/team-live-ops` `/team-qa` -## Getting Started +## 快速开始 -### Prerequisites +### 前置条件 - [Git](https://git-scm.com/) - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`npm install -g @anthropic-ai/claude-code`) -- **Recommended**: [jq](https://jqlang.github.io/jq/) (for hook validation) and Python 3 (for JSON validation) +- **推荐**： [jq](https://jqlang.github.io/jq/)（用于 hook 校验）以及 Python 3（用于 JSON 校验） -All hooks fail gracefully if optional tools are missing — nothing breaks, you just lose validation. +若缺少可选工具，所有 hook 会优雅降级——不会导致崩溃，只是失去校验能力。 -### Setup +### 安装配置 -1. **Clone or use as template**: +1. **克隆或作为模板使用**： ```bash git clone https://github.com/Donchitos/Claude-Code-Game-Studios.git my-game cd my-game ``` -2. **Open Claude Code** and start a session: +2. **打开 Claude Code** 并启动会话： ```bash claude ``` -3. **Run `/start`** — the system asks where you are (no idea, vague concept, - clear design, existing work) and guides you to the right workflow. No assumptions. +3. **运行 `/start`** — 系统会询问你当前处于哪一阶段（毫无头绪、模糊概念、清晰设计、已有作品），并引导你进入合适的工作流。不做任何假设。 - Or jump directly to a specific skill if you already know what you need: - - `/brainstorm` — explore game ideas from scratch - - `/setup-engine godot 4.6` — configure your engine if you already know - - `/project-stage-detect` — analyze an existing project + 若你已明确需求，也可直接跳转到特定技能： + - `/brainstorm` — 从零探索游戏创意 + - `/setup-engine godot 4.6` — 若已确定引擎则进行配置 + - `/project-stage-detect` — 分析现有项目 -## Upgrading +## 升级 -Already using an older version of this template? See [UPGRADING.md](UPGRADING.md) -for step-by-step migration instructions, a breakdown of what changed between -versions, and which files are safe to overwrite vs. which need a manual merge. +已在使用本模板的旧版本？请参阅 [UPGRADING.md](UPGRADING.md) +获取分步迁移说明、各版本间变更说明， +以及哪些文件可安全覆盖、哪些需要手动合并。 -## Project Structure +## 项目结构 ``` CLAUDE.md # Master configuration @@ -193,104 +198,104 @@ prototypes/ # Throwaway prototypes (isolated from src/) production/ # Sprint plans, milestones, release tracking ``` -## How It Works +## 工作原理 -### Agent Coordination +### Agent 协调 -Agents follow a structured delegation model: +Agent 遵循结构化的委派模型： -1. **Vertical delegation** — directors delegate to leads, leads delegate to specialists -2. **Horizontal consultation** — same-tier agents can consult each other but can't make binding cross-domain decisions -3. **Conflict resolution** — disagreements escalate up to the shared parent (`creative-director` for design, `technical-director` for technical) -4. **Change propagation** — cross-department changes are coordinated by `producer` -5. **Domain boundaries** — agents don't modify files outside their domain without explicit delegation +1. **纵向委派（Vertical delegation）** — 总监委派给负责人，负责人再委派给专家 +2. **横向咨询（Horizontal consultation）** — 同级 Agent 可以相互咨询，但不能做出具有约束力的跨领域决策 +3. **冲突解决（Conflict resolution）** — 分歧向上升级至共同上级（设计由 `creative-director` 负责，技术由 `technical-director` 负责） +4. **变更传播（Change propagation）** — 跨部门变更由 `producer` 协调 +5. **领域边界（Domain boundaries）** — 未经明确委派，Agent 不得修改其领域之外的文件 -### Collaborative, Not Autonomous +### 协作式，而非自主式 -This is **not** an auto-pilot system. Every agent follows a strict collaboration protocol: +这**不是**自动驾驶系统。每个 Agent 都遵循严格的协作协议： -1. **Ask** — agents ask questions before proposing solutions -2. **Present options** — agents show 2-4 options with pros/cons -3. **You decide** — the user always makes the call -4. **Draft** — agents show work before finalizing -5. **Approve** — nothing gets written without your sign-off +1. **提问（Ask）** — Agent 在提出方案前先提问 +2. **展示选项（Present options）** — Agent 展示 2-4 个选项及利弊 +3. **由你决定（You decide）** — 始终由用户拍板 +4. **起草（Draft）** — Agent 在定稿前展示工作成果 +5. **批准（Approve）** — 未经你签字确认，不会写入任何内容 -You stay in control. The agents provide structure and expertise, not autonomy. +你始终掌控全局。Agent 提供结构与专业知识，而非自主权。 -### Automated Safety +### 自动化安全保障 -**Hooks** run automatically on every session: +**Hooks** 会在每次会话中自动运行： -| Hook | Trigger | What It Does | -|------|---------|--------------| -| `validate-commit.sh` | PreToolUse (Bash) | Checks for hardcoded values, TODO format, JSON validity, design doc sections — exits early if the command is not `git commit` | -| `validate-push.sh` | PreToolUse (Bash) | Warns on pushes to protected branches — exits early if the command is not `git push` | -| `validate-assets.sh` | PostToolUse (Write/Edit) | Validates naming conventions and JSON structure — exits early if the file is not in `assets/` | -| `session-start.sh` | Session open | Shows current branch and recent commits for orientation | -| `detect-gaps.sh` | Session open | Detects fresh projects (suggests `/start`) and missing design docs when code or prototypes exist | -| `pre-compact.sh` | Before compaction | Preserves session progress notes | -| `post-compact.sh` | After compaction | Reminds Claude to restore session state from `active.md` | -| `notify.sh` | Notification event | Shows Windows toast notification via PowerShell | -| `session-stop.sh` | Session close | Archives `active.md` to session log and records git activity | -| `log-agent.sh` | Agent spawned | Audit trail start — logs subagent invocation | -| `log-agent-stop.sh` | Agent stops | Audit trail stop — completes subagent record | -| `validate-skill-change.sh` | PostToolUse (Write/Edit) | Advises running `/skill-test` after any `.claude/skills/` change | +| 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`, and `validate-skill-change.sh` fire on every Bash/Write tool call and exit immediately (exit 0) when the command or file path is not relevant. This is normal hook behavior — not a performance concern. +> **Note**：`validate-commit.sh`、`validate-assets.sh` 和 `validate-skill-change.sh` 会在每次 Bash/Write 工具调用时触发，当命令或文件路径不相关时立即退出（exit 0）。这是正常的 Hook 行为 — 并非性能问题。 -**Permission rules** in `settings.json` auto-allow safe operations (git status, test runs) and block dangerous ones (force push, `rm -rf`, reading `.env` files). +`settings.json` 中的**权限规则**会自动允许安全操作（git status、测试运行），并阻止危险操作（force push、`rm -rf`、读取 `.env` 文件）。 -### Path-Scoped Rules +### 路径作用域规则 -Coding standards are automatically enforced based on file location: +编码标准会根据文件位置自动强制执行： -| Path | Enforces | +| 路径 | 强制执行项 | |------|----------| -| `src/gameplay/**` | Data-driven values, delta time usage, no UI references | -| `src/core/**` | Zero allocations in hot paths, thread safety, API stability | -| `src/ai/**` | Performance budgets, debuggability, data-driven parameters | -| `src/networking/**` | Server-authoritative, versioned messages, security | -| `src/ui/**` | No game state ownership, localization-ready, accessibility | -| `design/gdd/**` | Required 8 sections, formula format, edge cases | -| `tests/**` | Test naming, coverage requirements, fixture patterns | -| `prototypes/**` | Relaxed standards, README required, hypothesis documented | +| `src/gameplay/**` | 数据驱动取值、delta time 用法、禁止 UI 引用 | +| `src/core/**` | 热路径零分配、线程安全、API 稳定性 | +| `src/ai/**` | 性能预算、可调试性、数据驱动参数 | +| `src/networking/**` | 服务端权威、版本化消息、安全性 | +| `src/ui/**` | 不持有游戏状态、支持本地化、无障碍 | +| `design/gdd/**` | 必需的 8 个章节、公式格式、边界情况 | +| `tests/**` | 测试命名、覆盖率要求、fixture 模式 | +| `prototypes/**` | 宽松标准、需要 README、记录假设 | -## Design Philosophy +## 设计理念 -This template is grounded in professional game development practices: +本模板植根于专业游戏开发实践： -- **MDA Framework** — Mechanics, Dynamics, Aesthetics analysis for game design -- **Self-Determination Theory** — Autonomy, Competence, Relatedness for player motivation -- **Flow State Design** — Challenge-skill balance for player engagement -- **Bartle Player Types** — Audience targeting and validation -- **Verification-Driven Development** — Tests first, then implementation +- **MDA Framework** — Mechanics、Dynamics、Aesthetics 分析，用于游戏设计 +- **Self-Determination Theory** — Autonomy、Competence、Relatedness，用于玩家动机 +- **Flow State Design** — 挑战与技能平衡，用于玩家参与度 +- **Bartle Player Types** — 受众定位与验证 +- **Verification-Driven Development** — 先测试，后实现 -## Customization +## 自定义 -This is a **template**, not a locked framework. Everything is meant to be customized: +这是一份**模板**，而非锁定的框架。一切均可自定义： -- **Add/remove agents** — delete agent files you don't need, add new ones for your domains -- **Edit agent prompts** — tune agent behavior, add project-specific knowledge -- **Modify skills** — adjust workflows to match your team's process -- **Add rules** — create new path-scoped rules for your project's directory structure -- **Tune hooks** — adjust validation strictness, add new checks -- **Pick your engine** — use the Godot, Unity, or Unreal agent set (or none) -- **Set review intensity** — `full` (all director gates), `lean` (phase gates only), or `solo` (none). Set during `/start` or edit `production/review-mode.txt`. Override per-run with `--review solo` on any skill. +- **增删 Agent** — 删除不需要的 Agent 文件，为你的领域添加新 Agent +- **编辑 Agent 提示词** — 调整 Agent 行为，添加项目专属知识 +- **修改 skills** — 调整工作流以匹配团队流程 +- **添加规则** — 为项目目录结构创建新的路径作用域规则 +- **调整 hooks** — 调整验证严格度，添加新检查 +- **选择引擎** — 使用 Godot、Unity 或 Unreal Agent 集（或不使用） +- **设置审查强度** — `full`（所有总监关卡）、`lean`（仅阶段关卡）或 `solo`（无）。在 `/start` 期间设置，或编辑 `production/review-mode.txt`。可在任意 skill 上用 `--review solo` 按次覆盖 -## Platform Support +## 平台支持 -Primary development and testing on **Windows 10** with Git Bash. All hooks use POSIX-compatible patterns (`grep -E`, not `grep -P`) and include fallbacks for missing tools, so they should run on macOS and Linux. The `notify.sh` hook uses PowerShell for Windows toast notifications and is a no-op elsewhere — desktop notifications on macOS/Linux are not yet wired. Cross-platform testing is ongoing; please file issues for any platform-specific breakage. +主要在 **Windows 10** 上使用 Git Bash 进行开发与测试。所有 hooks 使用 POSIX 兼容模式（`grep -E`，而非 `grep -P`），并包含缺失工具的降级方案，因此应可在 macOS 和 Linux 上运行。`notify.sh` hook 使用 PowerShell 实现 Windows 吐司通知，在其他平台上为 no-op — macOS/Linux 的桌面通知尚未接入。跨平台测试仍在进行中；如遇平台相关问题，请提交 issue。 -## Community +## 社区 - **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) --- -## Supporting This Project +## 支持本项目 -Claude Code Game Studios is free and open source. If it saves you time or helps you ship your game, consider supporting continued development: +Claude Code Game Studios 免费且开源。若它为你节省时间或帮助你发布游戏，欢迎支持后续开发：

Buy Me a Coffee @@ -301,12 +306,12 @@ Claude Code Game Studios is free and open source. If it saves you time or helps - **[Buy Me a Coffee](https://www.buymeacoffee.com/donchitos3)** — one-time support - **[GitHub Sponsors](https://github.com/sponsors/Donchitos)** — recurring support through GitHub -Sponsorships help fund time spent maintaining skills, adding new agents, keeping up with Claude Code and engine API changes, and responding to community issues. +赞助有助于投入时间维护 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).* -## License +## 许可证 MIT License. See [LICENSE](LICENSE) for details.