Design documents
The game's intent in plain prose — written with the agent, before it writes code.
A game has two kinds of documentation. One is technical: file layouts, how the scene data is shaped, which SDK call does what. The agent keeps that for itself and you never need to read it.
The other is design — what the game is. Its pillars, how it should feel, what a run looks like, why the jump is floaty on purpose. That one is yours, and it lives in the Documents tool.
Why it exists
Anything worth building is worth agreeing on first. The most expensive way to use an AI agent is to let it build the wrong thing quickly, and the cheapest fix is a paragraph you both read before it starts.
So for a new game — or a substantial new feature — the agent's first move is not code:
It asks you two or three real questions. Style, controls, the one mechanic that matters.
It writes design.md from your answers and opens it in the Documents
tool.
You read it, change what's wrong, and say go.
Then it builds.
For a small change it skips all of that and just builds. You will not be made to approve a document to move a button two pixels.
Editing
The editor is a normal rich-text editor — headings, lists, bold, links. It autosaves about a second after you stop typing, and shows Saved / Saving / Unsaved in the header. ⌘S forces a write.
The file is plain Markdown on disk, alongside the game's code, so it is committed with the game and shows up in change history. Download is one click if you want it elsewhere.
The list view shows every document with a content preview, its tags and
when it changed. New games get design.md; bigger features get their own
spec under it.
What belongs here — and what doesn't
| In a design document | Not here |
|---|---|
| What the game is, and who it's for | Filenames and function names |
| The core loop, the pillars, the feel | Which SDK call to use |
| Why a decision was made, and what was rejected | Step-by-step implementation plans |
| A feature spec, in player-facing terms | Numbers you'll tune fifty times — use a data table |
Write it the way you'd explain the game to a person. The agent is the translator from that into code — if you find yourself writing code in prose, you are doing its job and it is doing nobody's.
Using it as you go
The document is a live contract, not a one-time ritual. The agent reads it before building a new feature, so keeping it current is what makes later turns land closer to what you meant:
Update the design doc — we dropped the hunger system and the day is now
four minutes, not two.Read design.md and tell me what we said about the boss fight.Both you and the agent write to the same files, so a design decision you type in the tool is one the agent will honor next turn.