Game Design Document

Agent Prompt Snippet

Ensure the project has a game design document covering core mechanics, player experience goals, progression systems, game economy, and platform requirements.

Purpose

A Game Design Document (GDD) is the central design specification for a game. It describes what the game is, how it plays, why players engage with it, and what systems govern its behavior. The GDD communicates design intent to every member of the development team—programmers, artists, sound designers, QA—so that each person’s contribution reinforces the same player experience.

Games are systems of interacting rules. Without a GDD, those rules exist only in the game designer’s head, and every other team member must guess at intent or interrupt the designer constantly for clarification. A GDD makes design intent explicit, testable, and criticizable. “Does this feature match the GDD?” is a question every team member can answer.

The GDD is not a complete specification of every feature. It is a living document that captures the core design decisions—the mechanics that define the player experience, the progression systems that create long-term engagement, the economy that governs resources—and establishes design principles that guide all future decisions. Details are added as features are designed in depth.

Game design documents come in many forms, from exhaustive wiki-style systems to brief vision documents. The approach here emphasizes the minimum viable GDD: the document that, without existing, would cause the most expensive misalignment in the team. For solo developers, the GDD is a design journal. For teams, it is the shared reference that prevents everyone from building a different game.

Who needs this document

Persona	Why they need it	How they use it
Sam (Indie Dev)	Clarifies the core loop before over-building peripheral systems; prevents scope creep by defining what is in scope	Writes GDD before writing code; uses it to evaluate every feature: “does this serve the core loop?”
Claude Code (AI Agent)	Cannot generate game systems that fit together without understanding design intent, economy constraints, and player progression	Reads GDD before implementing any game system; validates that generated mechanics match documented game feel
Priya (Eng Lead)	Coordinates across art, programming, and sound to ensure all contributions reinforce the same experience	References GDD in sprint planning; uses design principles to evaluate feature requests

What separates a good version from a bad one

Criterion 1: The core loop is described in terms of player action, feedback, and motivation

✓ Strong: “Core loop: Player explores a dungeon (action) → encounters enemies (challenge) → defeats enemies to earn XP and gold (reward) → levels up and buys equipment (power growth) → explores deeper dungeon levels (escalated challenge). The loop repeats every 3–7 minutes at tutorial pace. The emotional beat is: tension → mastery → reward → anticipation. Every mechanic must reinforce at least one beat of this loop.”

✗ Weak: “Players fight enemies and level up. The game is fun.” (No loop structure, no timing, no emotional design intent. Two programmers reading this will implement different games.)

Criterion 2: Progression system is quantified with concrete milestones

✓ Strong: “Progression: 20 player levels. Level 1–5: tutorial zone, enemies deal 5–20 damage, player health 100. Level 10: mid-game, enemies deal 50–100 damage, player has unlocked 3 skill trees. Level 20: endgame, enemies deal 300+ damage, player has 400 health and full skill tree. XP curve: level N requires N² × 100 XP. Each level takes approximately 15 minutes of active play.”

✗ Weak: “Players level up as they defeat enemies. Higher levels have better stats.” (No numbers, no milestones, no time investment per level. Game balance cannot be designed from this description.)

Criterion 3: Economy is specified with production/consumption rates

✓ Strong: “Economy: single currency (Gold). Production rate: tutorial zone yields 50–150 Gold/hour. End-game zone yields 800–1200 Gold/hour. Sink rates: basic equipment 200–500 Gold, rare items 2000–5000 Gold. Economy goal: a player spending 10 hours per week should be able to purchase 1 rare item per week. Inflation target: real purchasing power of Gold must not change more than ±20% across patches.”

✗ Weak: “Players earn gold and spend it on equipment.” (No production/consumption balance, no inflation analysis, no designer intent. Economy will drift to either trivial or grind-heavy without this specification.)

Criterion 4: Platform requirements constrain design decisions

✓ Strong: “Target platforms: PC (Steam, 1080p/60fps minimum spec), Nintendo Switch (720p/30fps handheld). UI must be navigable with gamepad (no mouse-required interactions). Text must be readable at 720p on a 6-inch screen. Session length target: PC 30–120 minutes, Switch 10–30 minutes (commute-friendly). These constraints affect ability system design — no more than 8 active abilities to fit gamepad layout.”

✗ Weak: “Will release on PC and console.” (No resolution targets, no frame rate targets, no session length assumptions. UI and control design will contradict each other across platforms.)

Common mistakes

Designing systems without a core loop. Games that add features before establishing the core loop end up with a collection of systems that don’t reinforce each other. Every feature request in the GDD should answer the question: “how does this serve the core loop?” before being added to scope.

GDD as feature list, not design intent. A GDD that says “feature: inventory system” without specifying how many items the player can hold, whether items are categorized, what the player does with excess items, and what emotional role the inventory plays (scarcity vs. abundance) communicates nothing about design intent. Specify intent, not just features.

Not updating the GDD after design decisions. Games change constantly during development. A GDD that freezes the design at kickoff and is never updated actively misleads the team. Designate a GDD owner and require that design decisions are reflected in the document within one sprint.

Missing the “what makes this fun” section. Every GDD should articulate, explicitly, what player motivations the game addresses. Curiosity? Mastery? Social interaction? Collection? Without this, teams cannot evaluate whether a feature serves the game’s fun or just adds complexity.

How to use this document

When to create it

Write the GDD before building any core systems. A 5-page GDD written before the first commit is more valuable than a 50-page GDD written after the prototype is done. Start minimal: core loop, core mechanic, platform, and player experience goals. Expand iteratively.

Who owns it

The game director or lead designer owns the GDD. All team members can propose changes via a design review process. Major GDD changes require a design meeting with all department leads present.

How AI agents should reference it

get_standard_docs(type="video_game", features=[])
→ gdd in documents[]
→ agent reads GDD before designing or implementing any game system
→ agent validates that proposed mechanics serve the documented core loop
→ agent flags features that contradict documented design constraints

The prompt_snippet — “Ensure the project has a game design document covering core mechanics, player experience goals, progression systems, game economy, and platform requirements” — tells the agent to verify all five dimensions are covered.

How it connects to other documents

The GDD is the parent of the Technical Design Document (which specifies how each system is implemented), the Art Bible (which establishes visual direction in service of the design), the Audio Design (which establishes sound direction in service of the design), and the Networking Specification (for multiplayer games, which implements the session model defined in the GDD).