Start with a simple prompt describing the problem you want to solve. GDD guides the AI through five phase loops while you stay in control of every gate.
Get the playbook Read the concept article
Plain Markdown playbook · Tested with Claude Code and Codex
Describe what you want to build in a simple prompt.
Asks questions, drafts, prototypes, builds, and tests.
Approve the evidence or send the work back.
The GDD Playbook grew out of months of using AI to build new applications and improve existing ones. Along the way I hit the recurring problems: lost context, scope drift, untested fixes, unclear handoffs. I turned what I learned into a process with practical rules and human sign-off gates, and organized it into this playbook to share with other app builders. It remains a working playbook that I keep improving as I build, test, and learn.
Each phase is its own loop - you and the AI iterate until the work is proven. The gate is the human checkpoint: work moves forward only when the named outcome has evidence.
Tell the AI what you want to build via a few rounds of conversation. The AI drafts a short spec (a written plan): what the app is for, who will use it, and what stays out of scope. One or two pages, no design yet.
✓ Gate 1 · Spec lockedBased on the spec, the AI selects the tech stack, scaffolds the project in a fresh GitHub repository, then builds the app's first interface on sample data - usually clickable screens, but it can be chat, voice, or even another AI agent. You try every flow and ask for changes until it feels right. Changes cost minutes, because nothing real is built behind the interface yet. Testing here is by use: the sample data deliberately includes the ugly cases (empty lists, long names, errors), a review page lists every screen in every state so nothing goes unseen, and the AI runs a full UX review before the gate.
✓ Gate 2 · Prototype lockedThe AI turns every behavior into pass/fail acceptance criteria, then designs everything behind the screens: the headless Core API that every interface - human or machine - calls, the UI API, the data model, failure handling, and security. Tech stack and hosting are locked here too. Testing here is on paper but strict: every criterion must be concretely testable (input in, expected result out), and the locked criteria become phase 4's test list - testing is designed before any code exists.
✓ Gate 3 · Design lockedThe AI replaces the mock with the real backend, built to the frozen contract - one small step at a time, each landing with its own passing test, covering both the headless Core API and the UX. Every acceptance criterion from the design becomes an automated test, and a failing test can never be deleted or weakened. Your part is light: answer the occasional question, then read the coverage report - every spec item marked done with proof, or openly deferred.
✓ Gate 4 · Build completeThe AI walks the same checks up the ladder: smoke-test the golden path on the local build first, then on staging, then on production - the same scripted checks at every step, output shown. Deploys are automated and follow a documented order (database changes, code, caches, rebuilds), and the rollback command is known before anything moves. You give the go; the AI ships, re-verifies the live path, and shows the evidence.
✓ Gate 5 · ShipEvery change re-enters at the right phase: new feature → spec; screen tweak → prototype; behavior change → design; bug → build with a regression test. Ship is a gate, not an ending.
Testing is not phase six - evidence is created throughout the prototype, design, build, and deploy loops.
One file is for you. The rules file governs every AI session. Each of the five phases - and the change loop after ship - has exactly one file, so only the active phase's rules spend the AI's context.
The human-facing overview: how to install the playbook once, connect projects to it, and work with the AI without reading generated code.
The always-on control layer: STATUS protocol, explicit GO, visible evidence, decision and mistake logs, usage tracking, all five gates, and the universal gate-exit checklist.
Inside: the question-at-a-time spec loop, what a locked spec must contain, and the Gate 1 checklist.
Inside: contract-before-mock, ugly sample data, the use-case index, a two-lens UX review, 22 UX rules, and API design rules. The app's contract is born here.
Inside: design pressure-tests, architecture, security and failure rules, data modeling, stack selection criteria, contract freeze, and the design-lock checklist.
Inside: scope and code-quality rules, test execution (every step lands with its test; a failing test is never weakened), commit discipline, and the Gate 4 checklist.
Inside: local smoke tests, the documented deploy order, rebuild and count verification, rollback known before anything ships, and secrets hygiene.
Inside: routing each change to the right phase door, bugfix and hotfix protocols, adopting existing apps, and next-version batching.
Download the playbook once, keep it in one central folder, and connect each project with the instruction file for your coding agent.
One ZIP with everything: the eight Markdown files, the lessons inbox (the playbook improves from use), and the two project instruction templates - CLAUDE.md for Claude Code, AGENTS.md for Codex. Unzip into one central playbook folder.
Adapt the user, scale, problem, and desired outcome to your project.