infrastructure-claude-code-game-workflow

Claude Code Game Workflow

Purpose

How AI coding agents navigate this game development skill ecosystem — file conventions, which skills to read first, dependency order, and workflow patterns.

When to Use

Trigger: game dev workflow, skill navigation, which skill to use, game dev setup, project structure, skill dependencies, agent workflow, how to start, game dev ecosystem

Prerequisites

None — this is the entry point for the entire ecosystem.

Core Principles

Read skills before coding — always check if a relevant skill exists before implementing from scratch
Follow dependency order — skills have prerequisites; reading them out of order misses critical context
Coherence check is non-negotiable — any narrative content requires quest-narrative-coherence first
Genre-agnostic always — never assume a specific game genre in shared code
Schema first, logic second — start with postgres-game-schema before writing game logic

Feature Guides

Dedicated files for each Claude Code feature. Read the relevant one when setting up a new project or adding a capability.

File	Feature	When to Use
custom-agents.md	Custom Claude Code agents	Setting up game-engineer, narrative-writer, game-designer agents
worktrees.md	Git worktrees	Isolating a new game system or experimental change
mcp-setup.md	MCP servers (GitHub, Playwright, Context7)	Connecting external tools to Claude Code
plan-mode.md	Plan mode	Before implementing any new game system
todo-patterns.md	TodoWrite task tracking	Multi-step feature implementation
vision-multimodal.md	Screenshots + vision	Debugging UI, reviewing level design, game state
settings-full.md	Full `.claude/settings.json`	Permissions, hooks, and env vars for a game project
templates/game-agents/	Agent definition files	Copy to `.claude/agents/` in your project
templates/.mcp.json	MCP config	Copy to project root as `.mcp.json`
templates/claude-hooks-config.json	Hooks config	Copy hooks section into `.claude/settings.json`
templates/game-project-claude.md	Project CLAUDE.md	Copy to game project root

Skill Dependency Graph

                    [claude-code-game-workflow] (YOU ARE HERE)
                              |
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
     [postgres-game-schema] [game-design-fundamentals] [quest-narrative-coherence]
         |         |              |                         |
         ▼         ▼              ▼                         ▼
    [redis]  [bullmq]    [level-design]              [worldbuilding]
         |         |      [game-economy]             [story-structure]
         ▼         ▼      [ui-ux-game]              [character-design]
    [game-backend-architecture]  |                   [quest-mission-design]
              |                  |
              ▼                  ▼
    [game-state-sync]    [stripe-game-payments]
    [betterauth]         [elevenlabs-sound-music]

Workflow: Starting a New Game

Read claude-code-game-workflow (this skill)
Read game-design-fundamentals — define core loop, player motivation
Read postgres-game-schema — set up database
Read game-backend-architecture — set up Elysia server
Choose domain skills as needed (economy, quests, multiplayer, etc.)

Workflow: Adding a Feature

Identify which skill covers the feature
Read that skill's SKILL.md
Check prerequisites — read those first if not already done
Copy boilerplate/ files as starting point
Customize using templates/ for configuration

Workflow: Creating Narrative Content

ALWAYS read quest-narrative-coherence first
Read worldbuilding — load current world state
Read relevant narrative skill (story-structure, character-design, quest-mission)
Follow the 5-step coherence check
Register new content in quest-registry.md

Skill Quick Reference

Need	Skill	Domain
Database schemas	`postgres-game-schema`	Engineering
Job queues	`bullmq-game-queues`	Engineering
Game server + WebSocket	`game-backend-architecture`	Engineering
Caching + leaderboards	`redis-game-patterns`	Engineering
Authentication	`betterauth-integration`	Engineering
Payments / IAP	`stripe-game-payments`	Engineering
Sound / Music	`elevenlabs-sound-music`	Engineering
Netcode / State sync	`game-state-sync`	Engineering
Core game design	`game-design-fundamentals`	Design
Level / Area design	`level-design`	Design
Quests / Missions	`quest-mission-design`	Design
Economy / Currency	`game-economy-design`	Design
UI / UX	`ui-ux-game`	Design
World lore	`worldbuilding`	Narrative
Story / Plot	`story-structure-game`	Narrative
Characters / NPCs	`character-design-narrative`	Narrative
Narrative consistency	`quest-narrative-coherence`	Narrative
CI/CD	`ci-cd-game`	Infrastructure
Monitoring	`monitoring-game-ops`	Infrastructure
Cursor/Codex setup	`cursor-codex-integration`	Infrastructure

File Conventions

SKILL.md — knowledge document, read first
boilerplate/ — copy as starting code
templates/ — configuration and document templates
ARCHITECTURE.md — diagrams for infrastructure skills

Claude Code Setup

Quick setup for a new game project (4 steps):

Copy CLAUDE.md template: templates/game-project-claude.md → project root as CLAUDE.md. Fill in Core Loop, Genre, Platforms, Multiplayer.
Copy hooks: merge hooks from templates/claude-hooks-config.json into .claude/settings.json. See settings-full.md for the complete settings structure with permissions.
Copy MCP config: templates/.mcp.json → project root. Set GITHUB_TOKEN in shell env.
Copy custom agents: templates/game-agents/ → .claude/agents/ in your project.

For detailed configuration of each Claude Code feature, see the Feature Guides table above.

Skill @ Mentions

In any prompt, reference skill files directly to inject their context:

@skills/game-dev/engineering/postgres-game-schema/SKILL.md — add inventory table
@skills/game-dev/narrative/quest-narrative-coherence/SKILL.md — create merchant quest
@skills/game-dev/engineering/matchmaking-system/SKILL.md — implement ELO queue

Hooks for Game Dev

Copy the full hooks config from templates/claude-hooks-config.json. Four patterns:

Hook 1 — Skill Routing (UserPromptSubmit)

Detects keywords in the user's prompt and prints the relevant skill path before Claude responds. Runs on every prompt — zero false-negative cost.

Event: UserPromptSubmit
What it does: Scans prompt for domain keywords → prints the matching skill path as a hint
Keywords mapped:
- quest / character / NPC / story / lore / narrative → quest-narrative-coherence/SKILL.md
- schema / database / inventory / drizzle / migration → postgres-game-schema/SKILL.md
- matchmaking / lobby / ELO / rank / queue → matchmaking-system/SKILL.md
- analytics / retention / funnel / D1 / D7 / cohort → gameplay-analytics/SKILL.md
- redis / leaderboard / pubsub / cache / presence → redis-game-patterns/SKILL.md
- state / sync / netcode / delta / rollback / prediction → game-state-sync/SKILL.md
When to use: Always. Put in project .claude/settings.json.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "PROMPT=$(echo \"$CLAUDE_HOOK_INPUT\" | jq -r '.prompt // \"\"'); for kw in quest character NPC story lore narrative; do echo \"$PROMPT\" | grep -qi \"$kw\" && echo \"📚 Narrative skill: Read narrative/quest-narrative-coherence/SKILL.md first\" && break; done; for kw in schema database inventory drizzle migration; do echo \"$PROMPT\" | grep -qi \"$kw\" && echo \"📚 Engineering skill: Read engineering/postgres-game-schema/SKILL.md\" && break; done; for kw in matchmaking lobby elo rank queue; do echo \"$PROMPT\" | grep -qi \"$kw\" && echo \"📚 Engineering skill: Read engineering/matchmaking-system/SKILL.md\" && break; done; for kw in analytics retention funnel D1 D7 D30 cohort; do echo \"$PROMPT\" | grep -qi \"$kw\" && echo \"📚 Engineering skill: Read engineering/gameplay-analytics/SKILL.md\" && break; done; for kw in redis leaderboard pubsub cache presence; do echo \"$PROMPT\" | grep -qi \"$kw\" && echo \"📚 Engineering skill: Read engineering/redis-game-patterns/SKILL.md\" && break; done; exit 0"
          }
        ]
      }
    ]
  }
}

Hook 2 — Narrative Coherence Guard (PreToolUse: Write/Edit)

Blocks careless writes to narrative files by injecting a reminder before Claude touches them.

Event: PreToolUse
Matcher: Write|Edit
What it does: Checks if the target file path matches quest|character|story|narrative|lore|npc — if yes, prints a reminder
Behavior: Exit code 0 (reminder only, not a hard block — Claude can still proceed)
When to use: Any project with narrative content

{
  "matcher": "Write|Edit",
  "hooks": [
    {
      "type": "command",
      "command": "FILE=$(echo \"$CLAUDE_HOOK_INPUT\" | jq -r '.tool_input.file_path // .tool_input.path // \"\"'); echo \"$FILE\" | grep -qiE '(quest|character|story|narrative|lore|npc)' && echo \"[game-dev] ⚠️  Narrative file: ensure quest-narrative-coherence check is complete.\"; exit 0"
    }
  ]
}

Hook 3 — Biome Guard (PostToolUse: Write/Edit)

Auto-formats TypeScript after every file write. Game projects accumulate debt fast when formatting is skipped.

Event: PostToolUse
Matcher: Write|Edit
What it does: If biome.json or biome.jsonc exists in the project root, runs bunx biome check --write on the written file
When to use: Any TypeScript game project

{
  "matcher": "Write|Edit",
  "hooks": [
    {
      "type": "command",
      "command": "cd \"$CLAUDE_PROJECT_DIR\" && [ -f biome.json ] || [ -f biome.jsonc ] && bunx biome check --write . 2>/dev/null || true"
    }
  ]
}

Hook 4 — Quest Registry Reminder (Stop)

After every session, reminds the developer to update the narrative registry files.

Event: Stop
What it does: Prints a reminder to update quest-registry.md and world-lore.md
When to use: Any project with narrative content
Note: Fires unconditionally — cheap and hard to miss

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"[game-dev] Session ended. If you created narrative content, update quest-registry.md and world-lore.md.\""
          }
        ]
      }
    ]
  }
}

Subagent Patterns

Use parallel Claude Code agents when a feature spans multiple domains. Each agent reads its own skills, works in isolation, and produces a concrete output you merge at the end.

Pattern 1 — Design + Engineering in Parallel

When adding a major feature, split into two agents running simultaneously:

Agent A (Design): reads design skills → produces GDD section, economy balance, quest design
Agent B (Engineering): reads engineering skills → implements schema + backend routes

They work on separate concerns with no shared state. Use "worktree" isolation to give each agent its own git branch. Merge when both complete.

Prompt:

Use the Agent tool to run 2 parallel agents:
- Agent 1: Read skills/game-dev/design/game-economy-design/SKILL.md and design the currency economy for our idle game. Output: economy-design.md
- Agent 2: Read skills/game-dev/engineering/postgres-game-schema/SKILL.md and create the initial player schema. Output: modify db/schema.ts

Pattern 2 — Narrative Team

For a narrative-heavy session with multiple interconnected characters and quests:

Agent A: reads quest-narrative-coherence + creates new quest (loads world-lore.md, checks consistency)
Agent B: reads character-design-narrative + creates NPCs for that quest

Run in parallel. Then have the coherence agent review both outputs before merging to catch conflicts.

Prompt:

Use the Agent tool to run 2 parallel agents:
- Agent 1: Read narrative/quest-narrative-coherence/SKILL.md and narrative/worldbuilding/SKILL.md. Create a new merchant guild quest. Check world-lore.md for faction alignment. Output: quests/merchant-guild-q1.md
- Agent 2: Read narrative/character-design-narrative/SKILL.md. Create 2 NPCs for a merchant guild quest — a quest giver and antagonist. Output: characters/merchant-npcs.md

Pattern 3 — Full-Stack Feature

Breaking down "add matchmaking" into parallel workstreams:

Design agent: reads matchmaking-system + game-economy-design → produces matchmaking config doc
Backend agent: reads matchmaking-system + bullmq-game-queues → implements server-side queue logic
DB agent: reads postgres-game-schema + redis-game-patterns → creates tables + Redis key design

All three run in parallel. One integration agent (sequential, after all three complete) assembles the final feature.

When not to parallelize: When Agent B's output depends on Agent A's output. Keep those sequential.

Memory Patterns

What to persist across Claude Code sessions so agents never lose context.

What to Save in MEMORY.md

Write to ~/.claude/projects/<project>/memory/MEMORY.md after making significant decisions:

Architectural decisions: "Chose Glicko-2 over ELO for matchmaking — handles new players better"
Schema choices: "Player attributes use JSONB for flexibility — indexed on attributes->>'class'"
Economy parameters: "Gem earn rate: 10/day soft cap. First-time bonus: 200 gems."
World state summary: "3 factions: Merchant Guild (neutral), Iron Brotherhood (hostile), Arcane Circle (allied). Merchants control trade routes."
Active quest registry: link to quest-registry.md

Memory File Structure

~/.claude/projects/<your-project>/memory/
  MEMORY.md             # key decisions — loaded every session automatically
  world-state.md        # factions, geography, lore summary
  economy-state.md      # current balance parameters
  schema-decisions.md   # why each schema looks the way it does

Keep companion files (world-state.md, etc.) in the project repo under docs/memory/ and symlink or reference them from MEMORY.md so they travel with the codebase.

Rules for Memory

Write immediately after making a significant architectural or design decision
Never write temporary or session-specific context (e.g., "currently debugging X")
Review and update when a decision changes — stale memory is worse than no memory
Keep MEMORY.md under 150 lines (Claude truncates at ~200)
Use bullet points, not prose — agents scan memory, not read it

Sources

This ecosystem's own architecture
Claude Code documentation: hooks, memory, subagents
"Overwatch Gameplay Architecture and Netcode" — inspiration for subagent parallelism in game systems