5 Workflows That Change When Your AI Reads the GDD

Read Time: 7 minutes

Most AI coding tools only see your code. They can autocomplete functions, suggest refactors, and write tests --- but they have no idea what the game is supposed to do. They have never read the GDD. They do not know that the Mage has 80 HP, that the fire sword deals 2.5x damage to ice enemies, or that the quest "The Burning Keep" was cut in version 12.

When you connect your AI coding assistant to your design documents via MCP, that changes. Here are five workflows where the difference is night and day.

§Workflow 1: Implementing a New Feature#

Before: Copy-Paste From the GDD#

You open the GDD in one tab, your editor in another. You scan a three-page combat spec, mentally extract the relevant values, and start typing. You misremember that the Mage's mana regen is 3 per second (it is 2.5). You hardcode the Warrior's base armor as 15 (it was updated to 18 last sprint). Nobody catches it until QA files a bug two weeks later.

After: The AI Reads the Source of Truth#

You type: "Implement the mana regeneration system based on the combat GDD."

The AI calls read_document on your combat spec, extracts the per-class mana regen values from the entity data, and writes the implementation with the correct numbers. If the values change next sprint, you re-run the same prompt and get updated code. The GDD is the single source of truth, and the AI reads it directly.

What changes: Zero copy-paste errors. No stale values. The code matches the design by construction, not by human diligence.

§Workflow 2: Catching Design-Code Drift#

Before: QA Finds It Weeks Later#

A designer updates the balance spreadsheet: Warrior base HP goes from 120 to 100. The code still says 120. Nobody notices until a playtester reports that the Warrior feels too tanky compared to the patch notes. A bug is filed. A developer spends 30 minutes tracing the discrepancy. The fix is a one-line change.

After: The AI Cross-References Automatically#

You type: "Check if the character stat values in src/config/characters.ts match the balance spreadsheet."

The AI calls search_entities on the balance spreadsheet and reads the source file. It compares every value and reports: "Warrior.baseHP is 120 in code but 100 in the balance spreadsheet. Rogue.critChance is 0.15 in code but 0.18 in the spreadsheet." You fix both in one commit.

What changes: Drift is caught in seconds instead of weeks. You can run this check before every release, or even wire it into a pre-commit hook prompt.

§Workflow 3: Onboarding to a Codebase#

Before: Ask Marcus#

A new developer joins the team. They need to understand the combat system to fix a bug. They ask Marcus (the lead designer) to explain it. Marcus spends 45 minutes walking through the design. The new developer takes notes, misses some details, and asks Marcus again two days later. Marcus starts to resent the interruption.

After: The AI Becomes the Onboarding Guide#

The new developer types: "Summarize the combat system design. Include the core loop, damage formula, and status effects."

The AI reads the combat GDD, the balance spreadsheet, and the entity data. It produces a structured summary tailored to a developer's perspective: what the systems are, how they interact, what the key values are, and where the code that implements them lives. Marcus is not interrupted. The summary is accurate because it comes from the versioned design documents, not from someone's memory.

What changes: Onboarding time drops from days to hours. New team members get context from the actual documents, not from tribal knowledge that may be outdated.

§Workflow 4: Sprint Planning From the Quest Log#

Before: Context-Switch to the Browser#

Sprint planning starts. The lead pulls up the GameFrame quest log in the browser, reads through the open change requests, and manually maps them to code tasks. "The designer wants to rebalance ranged weapons --- that probably touches the damage calculator and the weapon config." This mapping happens in the lead's head and gets written into Jira tickets by hand.

After: The AI Maps Design Requests to Code#

The lead types: "Read the open change requests from the quest log and suggest which source files each one would affect."

The AI calls the quest log tools, reads each change request's description, and cross-references it with the codebase. It outputs a table: change request, affected files, estimated complexity. The lead reviews the table, adjusts where needed, and copies it into the sprint plan. The mapping is explicit and traceable.

What changes: Sprint planning is faster and more accurate. Design requests are connected to code impact before work begins, not after a developer starts digging.

§Workflow 5: Generating Tests From Design Specs#

Before: Write Tests From Memory#

You need to write unit tests for the damage calculator. You open the test file and start writing assertions based on what you think the damage formula is. You remember that base damage is multiplied by an element modifier, but you are not sure about the exact values. You write expect(calculate(fire, ice)).toBe(250) and hope it is right. It is not --- the element modifier for fire-vs-ice is 2.5x, not 2x, so the correct expected value is 312.5.

After: The AI Writes Tests With Real Values#

You type: "Generate unit tests for the damage calculator based on the combat GDD and the balance spreadsheet."

The AI reads the damage formula from the GDD, pulls the element modifier table and base stat values from the balance spreadsheet, and writes tests with correct expected values. Every assertion is traceable to a specific value in a specific document version. When the balance data changes, you regenerate the tests and get updated assertions.

What changes: Tests are grounded in the design spec, not in developer memory. The expected values are correct because they come from the same source of truth the designers maintain.

§Getting Started#

Connecting your AI coding tool to your GameFrame vault takes about two minutes. Add this to your .mcp.json:

{
  "mcpServers": {
    "gameframe": {
      "command": "npx",
      "args": ["-y", "@gameframe/mcp-server"],
      "env": {
        "GAMEFRAME_API_TOKEN": "your_token_here"
      }
    }
  }
}

For the full setup walkthrough, read Connect Your Game Design Docs to Claude Code.

For the complete tool reference and integration guides for Cursor, Windsurf, and other MCP-compatible editors, visit the Developers page.