claude-code-game-studios

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Claude Code Game Studios

Skill by ara.so — Claude Code Skills collection.

由ara.so开发的技能——Claude Code技能合集。

What It Does

功能介绍

Claude Code Game Studios transforms a single Claude Code session into a complete game development studio with:

49 specialized agents organized in a 3-tier studio hierarchy (Directors → Department Leads → Specialists)
73 slash commands covering brainstorming, design, architecture, implementation, QA, and release
12 automated hooks for validation, session tracking, and quality gates
11 path-scoped rules enforcing coding standards per domain (gameplay, engine, AI, UI, network)
41 document templates for GDDs, ADRs, sprint plans, accessibility specs, and more

Instead of one general-purpose AI assistant, you get a coordinated team with clear responsibilities, escalation paths, and quality gates — while you stay in full control of every decision.

Claude Code Game Studios可将单个Claude Code会话转变为完整的游戏开发工作室，具备以下特性：

49个专业Agent：按照三层工作室架构组织（总监→部门负责人→专员）
73条斜杠命令：涵盖头脑风暴、设计、架构、开发、QA测试与发布全流程
12个自动化钩子：用于验证、会话跟踪与质量管控
11项路径范围规则：针对不同领域（游戏玩法、引擎、AI、UI、网络）强制执行编码标准
41份文档模板：包含GDD（游戏设计文档）、ADR（架构决策记录）、冲刺计划、无障碍规范等

你将不再使用单一通用AI助手，而是拥有一支职责明确、具备升级路径与质量管控的协作团队，同时你对所有决策拥有完全控制权。

Installation

安装步骤

Prerequisites

前置要求

bash

undefined

bash

undefined

Required

必需

npm install -g @anthropic-ai/claude-code

Optional (for hook validation)

可选（用于钩子验证）

brew install jq # or apt-get install jq python3 --version # should be 3.x

undefined

brew install jq # 或 apt-get install jq python3 --version # 需为3.x版本

undefined

Setup New Project

新建项目

bash

undefined

bash

undefined

Clone as template

克隆为模板

git clone https://github.com/Donchitos/Claude-Code-Game-Studios.git my-game-project cd my-game-project

Start Claude Code

启动Claude Code

claude

Run initial setup

运行初始设置

/start

undefined

/start

undefined

Add to Existing Project

接入现有项目

bash

cd your-existing-game

bash

cd your-existing-game

Clone template files

克隆模板文件

git clone https://github.com/Donchitos/Claude-Code-Game-Studios.git .ccgs-temp cp -r .ccgs-temp/.claude . cp .ccgs-temp/CLAUDE.md . rm -rf .ccgs-temp

Detect existing project structure

检测现有项目结构

claude /adopt

undefined

claude /adopt

undefined

Studio Hierarchy

工作室层级架构

Agents are organized in three tiers matching real studio structure:

Agent按照真实工作室结构分为三层：

Tier 1 — Directors (Opus Model)

第一层——总监（Opus模型）

yaml

creative-director:    # Guards game vision, resolves design conflicts
technical-director:   # Owns architecture decisions, performance targets
producer:            # Coordinates cross-department changes, manages scope

yaml

creative-director:    # 把控游戏愿景，解决设计冲突
technical-director:   # 负责架构决策与性能目标
producer:            # 协调跨部门变更，管理项目范围

Tier 2 — Department Leads (Sonnet Model)

第二层——部门负责人（Sonnet模型）

yaml

game-designer:        # Owns systems design, balance
lead-programmer:      # Code architecture, tech stack decisions
art-director:         # Visual style, asset pipeline
audio-director:       # Audio design, implementation strategy
narrative-director:   # Story structure, dialogue systems
qa-lead:             # Test strategy, quality gates
release-manager:     # Build pipeline, deployment
localization-lead:   # i18n strategy, text management

yaml

game-designer:        # 负责系统设计与平衡性
lead-programmer:      # 代码架构与技术栈决策
art-director:         # 视觉风格与资源管线
audio-director:       # 音频设计与实现策略
narrative-director:   # 故事结构与对话系统
qa-lead:             # 测试策略与质量管控
release-manager:     # 构建管线与部署
localization-lead:   # 国际化策略与文本管理

Tier 3 — Specialists (Sonnet/Haiku Model)

第三层——专员（Sonnet/Haiku模型）

yaml

undefined

yaml

undefined

Programming

编程类

gameplay-programmer, engine-programmer, ai-programmer, network-programmer, tools-programmer, ui-programmer

Design

设计类

systems-designer, level-designer, economy-designer, live-ops-designer, ux-designer

Art & Audio

美术与音频类

technical-artist, sound-designer

Production & QA

制作与QA类

qa-tester, accessibility-specialist, performance-analyst, devops-engineer, analytics-engineer, security-engineer, community-manager

Content

内容类

writer, world-builder, prototyper

undefined

writer, world-builder, prototyper

undefined

Engine Specialists

引擎专属专员

yaml

undefined

yaml

undefined

Godot 4

godot-specialist:

gdscript-programmer
shader-programmer
gdextension-programmer

godot-specialist:

gdscript-programmer
shader-programmer
gdextension-programmer

Unity

unity-specialist:

dots-ecs-programmer
shader-vfx-programmer
addressables-programmer
uitoolkit-programmer

unity-specialist:

dots-ecs-programmer
shader-vfx-programmer
addressables-programmer
uitoolkit-programmer

Unreal Engine 5

unreal-specialist:

gas-programmer
blueprint-programmer
replication-programmer
umg-commonui-programmer

undefined

unreal-specialist:

gas-programmer
blueprint-programmer
replication-programmer
umg-commonui-programmer

undefined

Core Workflow Commands

核心工作流命令

Phase 1: Onboarding & Setup

阶段1：入门与设置

bash

/start                    # Guided onboarding (detects project stage)
/help                     # Show all available commands
/project-stage-detect     # Analyze existing project
/setup-engine godot 4.6   # Configure engine-specific settings
/adopt                    # Import existing project structure

bash

/start                    # 引导式入门（检测项目阶段）
/help                     # 显示所有可用命令
/project-stage-detect     # 分析现有项目
/setup-engine godot 4.6   # 配置引擎专属设置
/adopt                    # 导入现有项目结构

Phase 2: Game Design

阶段2：游戏设计

bash

/brainstorm              # Generate game concepts
/map-systems            # Map core game systems and interactions
/design-system combat    # Create detailed system GDD
/quick-design           # Lightweight design for small features
/review-all-gdds        # Audit all design documents
/propagate-design-change # Update docs after design pivot

Example: Design a combat system

bash

undefined

bash

/brainstorm              # 生成游戏概念
/map-systems            # 梳理核心游戏系统与交互
/design-system combat    # 创建详细的系统GDD
/quick-design           # 针对小型功能的轻量化设计
/review-all-gdds        # 审核所有设计文档
/propagate-design-change # 设计调整后更新相关文档

示例：设计战斗系统

bash

undefined

In Claude Code session

在Claude Code会话中

/design-system combat

Agent (systems-designer) asks:

Agent（systems-designer）会询问：

1. What's the core player fantasy?

1. 核心玩家体验定位是什么？

2. Turn-based or real-time?

2. 回合制还是即时制？

3. Complexity target (arcade/sim/hybrid)?

3. 复杂度目标（街机/模拟/混合）？

4. Key reference games?

4. 参考的标杆游戏？

After answers, creates:

回答后将生成：

design/systems/combat.md (GDD)

design/systems/combat.md（GDD文档）

design/systems/combat-flowchart.mermaid

design/systems/combat-flowchart.mermaid（流程图）

src/systems/combat/.design-manifest.json

src/systems/combat/.design-manifest.json（设计清单）

undefined

undefined

Phase 3: Architecture

阶段3：架构设计

bash

/create-architecture          # Design technical architecture
/architecture-decision        # Record ADR for tech choice
/architecture-review         # Review existing architecture
/create-control-manifest     # Map input/control schemes

Example: Architecture Decision Record

bash

/architecture-decision

bash

/create-architecture          # 设计技术架构
/architecture-decision        # 记录技术决策的ADR文档
/architecture-review         # 审核现有架构
/create-control-manifest     # 梳理输入/控制方案

示例：架构决策记录

bash

/architecture-decision

Creates docs/adr/NNNN-network-architecture.md

将创建 docs/adr/NNNN-network-architecture.md

Prompts for:

会提示输入：

- Context: Why this decision is needed

- 背景：为何需要该决策

- Options considered (with pros/cons)

- 备选方案（含优缺点）

- Decision made

- 最终决策

- Consequences

- 影响

undefined

undefined

Phase 4: Implementation

阶段4：开发实现

bash

/create-epics               # Break project into epics
/create-stories combat      # Generate user stories for epic
/dev-story GAME-123        # Implement specific story
/story-done GAME-123       # Mark story complete (runs QA)
/sprint-plan               # Plan upcoming sprint
/sprint-status            # Show sprint progress

Example: Implement a story

bash

/dev-story GAME-45

bash

/create-epics               # 将项目拆分为史诗任务
/create-stories combat      # 为史诗任务生成用户故事
/dev-story GAME-123        # 实现指定用户故事
/story-done GAME-123       # 标记故事完成（自动运行QA）
/sprint-plan               # 规划下一个冲刺周期
/sprint-status            # 显示冲刺进度

示例：实现用户故事

bash

/dev-story GAME-45

Reads production/stories/GAME-45.md

读取 production/stories/GAME-45.md

Spawns appropriate agents (e.g., gameplay-programmer + systems-designer)

调用对应Agent（如gameplay-programmer + systems-designer）

Shows implementation plan for approval

展示实现方案待确认

Writes code in src/

在src/目录编写代码

Updates story status

更新故事状态

Runs story-level tests

运行故事级测试

undefined

undefined

Phase 5: Quality & Review

阶段5：质量与审核

bash

/code-review src/combat/    # Review code quality
/design-review combat       # Review design doc completeness
/balance-check             # Analyze game balance
/perf-profile             # Performance analysis
/tech-debt                # Identify technical debt
/security-audit           # Security review
/consistency-check        # Cross-system consistency

bash

/code-review src/combat/    # 审核代码质量
/design-review combat       # 审核设计文档完整性
/balance-check             # 分析游戏平衡性
/perf-profile             # 性能分析
/tech-debt                # 识别技术债务
/security-audit           # 安全审核
/consistency-check        # 跨系统一致性检查

Phase 6: Testing

阶段6：测试

bash

/qa-plan                  # Create test strategy
/smoke-check             # Quick sanity tests
/soak-test               # Long-running stability test
/regression-suite        # Run full regression
/test-setup              # Configure test environment
/test-helpers            # Generate test utilities
/test-evidence-review    # Validate test coverage

Example: QA workflow

bash

undefined

bash

/qa-plan                  # 创建测试策略
/smoke-check             # 快速 sanity 测试
/soak-test               # 长期稳定性测试
/regression-suite        # 运行完整回归测试
/test-setup              # 配置测试环境
/test-helpers            # 生成测试工具
/test-evidence-review    # 验证测试覆盖度

示例：QA工作流

bash

undefined

After implementing GAME-45

实现GAME-45后

/story-done GAME-45

Automatically:

自动执行：

1. Runs /smoke-check on affected systems

1. 对受影响系统运行/smoke-check

2. Checks test coverage (warns if <80%)

2. 检查测试覆盖度（低于80%时发出警告）

3. Updates production/stories/GAME-45.md status

3. 更新production/stories/GAME-45.md状态

4. Moves to "Ready for Review"

4. 移至“待审核”状态

undefined

undefined

Phase 7: Release

阶段7：发布

bash

/release-checklist        # Pre-release validation
/launch-checklist        # Launch day tasks
/changelog               # Generate changelog
/patch-notes             # Write player-facing notes
/hotfix                  # Emergency fix workflow
/day-one-patch           # Plan day-one update

bash

/release-checklist        # 发布前验证
/launch-checklist        # 发布当日任务
/changelog               # 生成变更日志
/patch-notes             # 编写面向玩家的更新说明
/hotfix                  # 紧急修复工作流
/day-one-patch           # 规划首日更新

Team Coordination Commands

团队协作命令

For features requiring multiple departments:

bash

/team-combat             # Combat system (design + gameplay + VFX + audio)
/team-narrative          # Story content (narrative + world-builder + writer)
/team-ui                # UI feature (ux-designer + ui-programmer + accessibility)
/team-release           # Release prep (all leads)
/team-polish            # Pre-launch polish (art + audio + QA)
/team-level             # Level creation (level-designer + technical-artist)
/team-live-ops          # Live service (live-ops-designer + analytics)
/team-qa                # Quality push (qa-lead + all testers)

Example: Multi-agent feature

bash

/team-combat

针对需要多部门协作的功能：

bash

/team-combat             # 战斗系统（设计+玩法+特效+音频）
/team-narrative          # 故事内容（叙事+世界观构建+编剧）
/team-ui                # UI功能（UX设计+UI开发+无障碍适配）
/team-release           # 发布准备（所有负责人）
/team-polish            # 发布前优化（美术+音频+QA）
/team-level             # 关卡创建（关卡设计+技术美术）
/team-live-ops          # 运营服务（运营设计+数据分析）
/team-qa                # 质量攻坚（QA负责人+所有测试员）

示例：多Agent协作功能

bash

/team-combat

Spawns coordination team:

启动协作团队：

- systems-designer (mechanics)

- systems-designer（机制设计）

- gameplay-programmer (implementation)

- gameplay-programmer（开发实现）

- technical-artist (VFX)

- technical-artist（特效）

- sound-designer (audio)

- sound-designer（音频）

- qa-tester (combat-specific tests)

- qa-tester（战斗专项测试）

Creates shared context document

创建共享上下文文档

Coordinates work phases

协调工作阶段

Ensures integration testing

确保集成测试

undefined

undefined

Project Structure

项目结构

my-game/
├── CLAUDE.md                    # Master config (agent registry)
├── .claude/
│   ├── settings.json           # Hooks, permissions, safety rules
│   ├── agents/                 # 49 agent definitions
│   │   ├── creative-director.md
│   │   ├── gameplay-programmer.md
│   │   └── ...
│   ├── skills/                 # 73 slash commands
│   │   ├── start/
│   │   │   ├── SKILL.md
│   │   │   └── metadata.json
│   │   └── ...
│   ├── hooks/                  # 12 automation hooks
│   │   ├── validate-commit.sh
│   │   ├── session-start.sh
│   │   └── ...
│   ├── rules/                  # 11 coding standards
│   │   ├── gameplay-code.md
│   │   ├── engine-code.md
│   │   └── ...
│   └── docs/
│       ├── workflow-catalog.yaml
│       └── templates/          # 41 doc templates
├── src/                        # Game source code
├── assets/                     # Art, audio, data
├── design/                     # GDDs, narrative docs
├── docs/                       # ADRs, technical docs
├── tests/                      # Test suites
├── production/                 # Sprint plans, stories
└── prototypes/                 # Isolated experiments

my-game/
├── CLAUDE.md                    # 主配置文件（Agent注册表）
├── .claude/
│   ├── settings.json           # 钩子、权限、安全规则
│   ├── agents/                 # 49个Agent定义
│   │   ├── creative-director.md
│   │   ├── gameplay-programmer.md
│   │   └── ...
│   ├── skills/                 # 73条斜杠命令
│   │   ├── start/
│   │   │   ├── SKILL.md
│   │   │   └── metadata.json
│   │   └── ...
│   ├── hooks/                  # 12个自动化钩子
│   │   ├── validate-commit.sh
│   │   ├── session-start.sh
│   │   └── ...
│   ├── rules/                  # 11项编码标准
│   │   ├── gameplay-code.md
│   │   ├── engine-code.md
│   │   └── ...
│   └── docs/
│       ├── workflow-catalog.yaml
│       └── templates/          # 41份文档模板
├── src/                        # 游戏源代码
├── assets/                     # 美术、音频、数据资源
├── design/                     # GDD、叙事文档
├── docs/                       # ADR、技术文档
├── tests/                      # 测试套件
├── production/                 # 冲刺计划、用户故事
└── prototypes/                 # 独立实验项目

Configuration

配置说明

Engine Selection

引擎选择

Edit

CLAUDE.md

to activate your engine's specialists:

markdown

undefined

编辑

CLAUDE.md

以激活对应引擎的专属专员：

markdown

undefined

Active Specialists

激活的专员

Godot 4

godot-specialist (tier-2-lead)
- gdscript-programmer
- shader-programmer
- gdextension-programmer

<!-- Disable unused engines:

godot-specialist (tier-2-lead)
- gdscript-programmer
- shader-programmer
- gdextension-programmer

<!-- 禁用未使用的引擎：

Unity

unity-specialist (tier-2-lead) ... -->

undefined

unity-specialist (tier-2-lead) ... -->

undefined

Hook Configuration

钩子配置

Edit

.claude/settings.json

json

{
  "hooks": {
    "session.open": [".claude/hooks/session-start.sh"],
    "session.close": [".claude/hooks/session-stop.sh"],
    "preToolUse": {
      "Bash": [
        ".claude/hooks/validate-commit.sh",
        ".claude/hooks/validate-push.sh"
      ]
    },
    "postToolUse": {
      "WriteFile": [".claude/hooks/validate-assets.sh"],
      "EditFile": [".claude/hooks/validate-skill-change.sh"]
    }
  }
}

编辑

.claude/settings.json

：

json

{
  "hooks": {
    "session.open": [".claude/hooks/session-start.sh"],
    "session.close": [".claude/hooks/session-stop.sh"],
    "preToolUse": {
      "Bash": [
        ".claude/hooks/validate-commit.sh",
        ".claude/hooks/validate-push.sh"
      ]
    },
    "postToolUse": {
      "WriteFile": [".claude/hooks/validate-assets.sh"],
      "EditFile": [".claude/hooks/validate-skill-change.sh"]
    }
  }
}

Permission Rules

权限规则

json

{
  "permissions": {
    "allowed_commands": [
      "git status",
      "git log",
      "pytest tests/",
      "npm test"
    ],
    "blocked_paths": [
      ".env",
      "secrets/",
      "production/credentials/"
    ]
  }
}

json

{
  "permissions": {
    "allowed_commands": [
      "git status",
      "git log",
      "pytest tests/",
      "npm test"
    ],
    "blocked_paths": [
      ".env",
      "secrets/",
      "production/credentials/"
    ]
  }
}

Common Patterns

常用模式

Start New Game from Scratch

从零开始创建新游戏

bash

/start

bash

/start

Choose: "No idea, just exploring"

选择："还没想法，先探索"

/brainstorm

Discuss concepts, pick one

讨论概念，选定一个

/map-systems

Define core systems

定义核心系统

/design-system [system-name]

Detail each system

细化每个系统

/create-architecture

Plan tech stack

规划技术栈

/setup-engine godot 4.6

Configure engine

配置引擎

/create-epics

Break into epics

拆分为史诗任务

/create-stories [epic-name]

Generate user stories

生成用户故事

/sprint-plan

Plan first sprint

规划第一个冲刺周期

undefined

undefined

Import Existing Project

导入现有项目

bash

/adopt

bash

/adopt

Scans src/, assets/, design/

扫描src/、assets/、design/目录

Detects gaps (missing GDDs, ADRs)

检测缺口（缺失的GDD、ADR）

Suggests next steps

建议下一步操作

/reverse-document src/combat/

Generates design doc from code

从代码生成设计文档

/architecture-review

Analyzes current structure

分析当前架构

Recommends improvements

See current sprint progress

查看当前冲刺进度

/dev-story GAME-67

Implement next story

实现下一个用户故事

/story-done GAME-67

QA + mark complete

执行QA并标记完成

/code-review src/inventory/

Periodic quality check

定期质量检查

undefined

undefined

Pre-Release Workflow

发布前工作流

bash

/gate-check alpha

bash

/gate-check alpha

Validate alpha criteria

验证Alpha版本标准

/regression-suite

Full test pass

完整测试

/perf-profile

Performance validation

性能验证

/release-checklist alpha

Final checks

最终检查

/changelog

Generate changelog

生成变更日志

/patch-notes

Write player-facing notes

编写面向玩家的更新说明

undefined

undefined

Real Code Examples

真实代码示例

Godot 4 Combat System (GDScript)

Godot 4战斗系统（GDScript）

gdscript

undefined

gdscript

undefined

Generated by /dev-story GAME-12 (gameplay-programmer)

Design: design/systems/combat.md

ADR: docs/adr/0003-combat-state-machine.md

class_name CombatController extends Node

Combat state machine following design/systems/combat.md

Manages turn order, damage resolution, status effects

signal turn_started(combatant: Combatant) signal turn_ended(combatant: Combatant) signal combat_ended(victor: Team)

enum CombatState { SETUP, PLAYER_TURN, ENEMY_TURN, RESOLUTION, ENDED }

@export var turn_time_limit: float = 30.0 # From combat.md: 30s turn timer @export var damage_formula: DamageFormula # Injected, see ADR-0003

var _state: CombatState = CombatState.SETUP var _turn_queue: Array[Combatant] = [] var _active_combatant: Combatant

func _ready() -> void: assert(damage_formula != null, "DamageFormula required") _initialize_turn_queue()

func execute_action(action: CombatAction) -> void: # Validates action legality (design constraint: one action per turn) assert(action.actor == _active_combatant, "Not active combatant's turn")

var result := damage_formula.calculate(action)
_apply_damage(result)
_check_status_effects()
_end_turn()

undefined

signal turn_started(combatant: Combatant) signal turn_ended(combatant: Combatant) signal combat_ended(victor: Team)

enum CombatState { SETUP, PLAYER_TURN, ENEMY_TURN, RESOLUTION, ENDED }

@export var turn_time_limit: float = 30.0 # From combat.md: 30s turn timer @export var damage_formula: DamageFormula # Injected, see ADR-0003

var _state: CombatState = CombatState.SETUP var _turn_queue: Array[Combatant] = [] var _active_combatant: Combatant

func _ready() -> void: assert(damage_formula != null, "DamageFormula required") _initialize_turn_queue()

func execute_action(action: CombatAction) -> void: # Validates action legality (design constraint: one action per turn) assert(action.actor == _active_combatant, "Not active combatant's turn")

var result := damage_formula.calculate(action)
_apply_damage(result)
_check_status_effects()
_end_turn()

undefined

Unity DOTS Combat (C#)

Unity DOTS战斗系统（C#）

csharp

// Generated by /dev-story GAME-23 (dots-ecs-programmer)
// Design: design/systems/combat.md
// ADR: docs/adr/0005-dots-combat-architecture.md

using Unity.Entities;
using Unity.Mathematics;
using Unity.Collections;

[UpdateInGroup(typeof(SimulationSystemGroup))]
public partial struct CombatResolutionSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        // Process all pending combat actions (batched per design/systems/combat.md)
        var ecb = new EntityCommandBuffer(Allocator.TempJob);
        
        foreach (var (action, entity) in 
            SystemAPI.Query<RefRO<CombatAction>>()
                .WithEntityAccess())
        {
            // Calculate damage using formula from combat.md
            var damage = CalculateDamage(
                action.ValueRO.AttackerPower,
                action.ValueRO.DefenderArmor,
                action.ValueRO.CriticalChance
            );
            
            // Apply damage to target (buffered to avoid structural changes)
            ecb.SetComponent(action.ValueRO.Target, new Health 
            { 
                Current = math.max(0, GetHealth(action.ValueRO.Target) - damage)
            });
            
            // Remove processed action
            ecb.DestroyEntity(entity);
        }
        
        ecb.Playback(state.EntityManager);
        ecb.Dispose();
    }
    
    private float CalculateDamage(float power, float armor, float critChance)
    {
        // Formula from design/systems/combat.md section 3.2
        var baseDamage = power * (100f / (100f + armor));
        var isCrit = UnityEngine.Random.value < critChance;
        return baseDamage * (isCrit ? 1.5f : 1.0f);  // 150% crit multiplier per design
    }
}

csharp

// Generated by /dev-story GAME-23 (dots-ecs-programmer)
// Design: design/systems/combat.md
// ADR: docs/adr/0005-dots-combat-architecture.md

using Unity.Entities;
using Unity.Mathematics;
using Unity.Collections;

[UpdateInGroup(typeof(SimulationSystemGroup))]
public partial struct CombatResolutionSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        // Process all pending combat actions (batched per design/systems/combat.md)
        var ecb = new EntityCommandBuffer(Allocator.TempJob);
        
        foreach (var (action, entity) in 
            SystemAPI.Query<RefRO<CombatAction>>()
                .WithEntityAccess())
        {
            // Calculate damage using formula from combat.md
            var damage = CalculateDamage(
                action.ValueRO.AttackerPower,
                action.ValueRO.DefenderArmor,
                action.ValueRO.CriticalChance
            );
            
            // Apply damage to target (buffered to avoid structural changes)
            ecb.SetComponent(action.ValueRO.Target, new Health 
            { 
                Current = math.max(0, GetHealth(action.ValueRO.Target) - damage)
            });
            
            // Remove processed action
            ecb.DestroyEntity(entity);
        }
        
        ecb.Playback(state.EntityManager);
        ecb.Dispose();
    }
    
    private float CalculateDamage(float power, float armor, float critChance)
    {
        // Formula from design/systems/combat.md section 3.2
        var baseDamage = power * (100f / (100f + armor));
        var isCrit = UnityEngine.Random.value < critChance;
        return baseDamage * (isCrit ? 1.5f : 1.0f);  // 150% crit multiplier per design
    }
}

Unreal Engine 5 GAS Ability (C++)

Unreal Engine 5 GAS技能（C++）

cpp

// Generated by /dev-story GAME-34 (gas-programmer)
// Design: design/systems/combat.md
// ADR: docs/adr/0007-gas-ability-system.md

#pragma once

#include "CoreMinimal.h"
#include "Abilities/GameplayAbility.h"
#include "MeleeAttackAbility.generated.h"

/**
 * Melee attack ability implementing design/systems/combat.md
 * Uses GAS for damage calculation, status effects, cooldowns
 */
UCLASS()
class MYGAME_API UMeleeAttackAbility : public UGameplayAbility
{
    GENERATED_BODY()

public:
    UMeleeAttackAbility();

    virtual void ActivateAbility(
        const FGameplayAbilitySpecHandle Handle,
        const FGameplayAbilityActorInfo* ActorInfo,
        const FGameplayAbilityActivationInfo ActivationInfo,
        const FGameplayEventData* TriggerEventData
    ) override;

protected:
    /** Base damage (modified by GE_DamageCalculation) */
    UPROPERTY(EditDefaultsOnly, Category = "Combat")
    float BaseDamage = 10.0f;

    /** Attack range in cm (from combat.md: 200cm melee range) */
    UPROPERTY(EditDefaultsOnly, Category = "Combat")
    float AttackRange = 200.0f;

    /** Damage calculation gameplay effect */
    UPROPERTY(EditDefaultsOnly, Category = "Combat")
    TSubclassOf<UGameplayEffect> DamageEffectClass;

private:
    void ApplyDamageToTarget(AActor* Target);
    bool IsInAttackRange(AActor* Target) const;
};

cpp

// Generated by /dev-story GAME-34 (gas-programmer)
// Design: design/systems/combat.md
// ADR: docs/adr/0007-gas-ability-system.md

#pragma once

#include "CoreMinimal.h"
#include "Abilities/GameplayAbility.h"
#include "MeleeAttackAbility.generated.h"

/**
 * Melee attack ability implementing design/systems/combat.md
 * Uses GAS for damage calculation, status effects, cooldowns
 */
UCLASS()
class MYGAME_API UMeleeAttackAbility : public UGameplayAbility
{
    GENERATED_BODY()

public:
    UMeleeAttackAbility();

    virtual void ActivateAbility(
        const FGameplayAbilitySpecHandle Handle,
        const FGameplayAbilityActorInfo* ActorInfo,
        const FGameplayAbilityActivationInfo ActivationInfo,
        const FGameplayEventData* TriggerEventData
    ) override;

protected:
    /** Base damage (modified by GE_DamageCalculation) */
    UPROPERTY(EditDefaultsOnly, Category = "Combat")
    float BaseDamage = 10.0f;

    /** Attack range in cm (from combat.md: 200cm melee range) */
    UPROPERTY(EditDefaultsOnly, Category = "Combat")
    float AttackRange = 200.0f;

    /** Damage calculation gameplay effect */
    UPROPERTY(EditDefaultsOnly, Category = "Combat")
    TSubclassOf<UGameplayEffect> DamageEffectClass;

private:
    void ApplyDamageToTarget(AActor* Target);
    bool IsInAttackRange(AActor* Target) const;
};

Troubleshooting

故障排查

Hooks Not Running

钩子未运行

bash

undefined

bash

undefined

Check hook permissions

检查钩子权限

ls -l .claude/hooks/

Should be -rwxr-xr-x (executable)

权限应为 -rwxr-xr-x（可执行）

Make executable if needed

若需设置可执行权限

chmod +x .claude/hooks/*.sh

Test individual hook

测试单个钩子

.claude/hooks/validate-commit.sh

undefined

.claude/hooks/validate-commit.sh

undefined

Agent Not Found

Agent未找到

bash

undefined

bash

undefined

Verify agent exists

验证Agent是否存在

ls .claude/agents/ | grep gameplay-programmer

Check CLAUDE.md registry

检查CLAUDE.md注册表

grep "gameplay-programmer" CLAUDE.md

If missing, agent was removed — restore from template or create custom

若缺失，说明Agent已被移除——从模板恢复或创建自定义Agent

undefined

undefined

Skill Fails to Load

技能加载失败

bash

undefined

bash

undefined

Validate skill metadata

验证技能元数据

cat .claude/skills/dev-story/metadata.json | jq .

Check for syntax errors

检查语法错误

python3 -m json.tool .claude/skills/dev-story/metadata.json

Test skill in isolation

单独测试技能

/skill-test dev-story

Fix issues, then re-test

修复问题后重新测试

/skill-improve dev-story

undefined

/skill-improve dev-story

undefined

Validation Errors on Commit

提交时验证错误

bash

undefined

bash

undefined

Hook found issues — read output

钩子检测到问题——查看输出

git commit -m "Add combat system"

❌ Validation failed: Hardcoded magic number in src/combat/damage.gd:42

❌ 验证失败：src/combat/damage.gd:42存在硬编码魔法值

Fix the issue

修复问题

Replace: var damage = power * 1.5

替换：var damage = power * 1.5

With: const CRIT_MULTIPLIER = 1.5; var damage = power * CRIT_MULTIPLIER

改为：const CRIT_MULTIPLIER = 1.5; var damage = power * CRIT_MULTIPLIER

Commit again

重新提交

git commit -m "Add combat system"

✅ Validation passed

✅ 验证通过

undefined

undefined

Context Limit Warnings

上下文超限警告

bash

undefined

bash

undefined

Project grew too large for context window

项目过大超出上下文窗口

Compact session history (preserves active.md)

压缩会话历史（保留active.md）

claude compact

Or work in focused mode (single epic)

或使用聚焦模式（仅处理单个史诗任务）

/sprint-plan

Select subset of stories to minimize loaded context

选择部分故事以最小化加载的上下文

undefined

undefined

Engine Specialist Not Available

引擎专属专员不可用

yaml

undefined

yaml

undefined

Check CLAUDE.md for active specialists

检查CLAUDE.md中的激活专员

If godot-specialist is commented out:

若godot-specialist被注释：

Active Specialists

激活的专员

<!--

Godot 4

godot-specialist -->

godot-specialist -->

Uncomment to activate:

取消注释以激活：

Godot 4

godot-specialist (tier-2-lead)
- gdscript-programmer
- shader-programmer

undefined

godot-specialist (tier-2-lead)
- gdscript-programmer
- shader-programmer

undefined

Support & Community

支持与社区

Documentation: Full workflow catalog
Issues: GitHub Issues
Discussions: GitHub Discussions
Support the project: Buy Me a Coffee or GitHub Sponsors

文档：完整工作流目录
问题反馈：GitHub Issues
讨论交流：GitHub Discussions
支持项目：Buy Me a Coffee 或 GitHub Sponsors

License

许可证

MIT License — see LICENSE file for details.

MIT许可证——详见LICENSE文件。