fcsouza/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

1. Read skills before coding — always check if a relevant skill exists before implementing from scratch
2. Follow dependency order — skills have prerequisites; reading them out of order misses critical context
3. Coherence check is non-negotiable — any narrative content requires quest-narrative-coherence first
4. Genre-agnostic always — never assume a specific game genre in shared code
5. 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

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

Workflow: Adding a Feature

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

Workflow: Creating Narrative Content

1. ALWAYS read quest-narrative-coherence first
2. Read worldbuilding — load current world state
3. Read relevant narrative skill (story-structure, character-design, quest-mission)
4. Follow the 5-step coherence check
5. 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):

1. Copy CLAUDE.md template: templates/game-project-claude.md → project root as CLAUDE.md. Fill in Core Loop, Genre, Platforms, Multiplayer.
2. 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.
3. Copy MCP config: templates/.mcp.json → project root. Set GITHUB_TOKEN in shell env.
4. 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:

1. Design agent: reads matchmaking-system + game-economy-design → produces matchmaking config doc
2. Backend agent: reads matchmaking-system + bullmq-game-queues → implements server-side queue logic
3. 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