Game Design Documents for Humans and AI Agents

Q: What is a game design document in 2026?

A game design document, or GDD, describes what your game is and why: the pitch, core loop, levels, rules, references and open questions. In 2026 it often has a second reader, the AI coding agents working on the project. That changes how you write it. I'd keep the GDD for intent and feel, and move hard rules and numbers into a short agent context file and data assets.

Q: How long should a GDD be for an indie game?

Long enough to explain the game, short enough that someone updates it. For a small mobile game I aim for roughly 3,000 to 6,000 words in the main GDD, written in sections you can rewrite independently. PawScooty's first GDD was 5,355 words. The bigger risk isn't length but staleness, so pair it with a dated decision log and fold that log back in every week.

Q: What should go in an AGENTS.md or CLAUDE.md file for a game project?

Only the things an agent must follow every session: scope and out-of-scope items, performance and polygon budgets, naming conventions, where tuning values live, which tool or person owns which files, and the commands to build and test. Keep it under about 1,500 words. Don't put session notes or status updates in it, because every agent session reads the whole file before doing anything.

Q: Why should game tuning numbers live in ScriptableObjects instead of the GDD?

Because a number written in two places will eventually disagree. If the GDD says 25 HP and the code says 30, nobody knows which is right. Put the actual value in a Unity ScriptableObject or Godot Resource, name it with its unit, and reference the GDD section in a header comment. The GDD then explains what the number means and why, without restating it.

Q: What went wrong with PawScooty's design documents?

Two things drifted. The memory.md context file also held a status line updated every session, so it grew to around 6,300 words, longer than the GDD, and every agent read it in full. And an image-generation style prefix marked use verbatim still asked for flat-shaded low-poly Ghibli-style art after the art direction had moved away from both. Agents follow literal lines like that.

Q: How do I stop a GDD from going out of date?

Treat the game as the truth. When a play-test changes something, write a dated decision log entry first: what changed, why and what it supersedes. Then change the data or code. Update the agent context file only if a rule changed. Once a week, fold the log entries back into the right GDD sections and delete the stale paragraphs so the document stays readable for new people.

Q: Can AI write my game design document for me?

It can write the words, but it shouldn't make the decisions. AI is useful for turning rough notes into numbered rules, finding contradictions between documents, generating tests from rules and checking code against the spec. It can't tell you whether a mechanic is fun or what to cut. A confident AI-written GDD for an unplayed game makes the design feel decided when it isn't.

Q: Should I use one design document or several files?

Several. One document can't be short enough for a human to skim and precise enough for an agent to follow. I'd use a GDD for intent, an agent context file for rules, a plan for tasks and owners, a decision log for dated changes, and data assets for the numbers. Link them with shared IDs, like PawScooty's asset prefixes, so every file points at the same things.

Satyam Kumar

Back to Blog

architecture

Your GDD Has Two Readers Now: Writing a Game Design Document for Humans and AI Agents in 2026

By Satyam KumarOctober 27, 202612 min read

game design document gdd template ai coding agents agents.md claude.md agent context file unity scriptableobject godot resources design decision log indie game production game documentation data-driven tuning pawscooty unity 6 solo game development game design process

Your GDD Has Two Readers Now: Writing a Game Design Document for Humans and AI Agents in 2026

Frequently Asked Questions

Share this article

Twitter LinkedIn WhatsApp

Satyam Kumar

Founder & AI Architect, AppScale LLP

AI & Cloud Architect. Helping teams build systems that scale to millions.

LinkedIn GitHub

Your GDD Has Two Readers Now: Writing a Game Design Document for Humans and AI Agents in 2026

Frequently Asked Questions

Share this article

Comments

Leave a comment