A Playbook for Building Real Apps with AI
Gate-Driven Development. The AI does the design, code, and tests. You judge behavior at each gate. Nobody has to read generated code to trust the result.
AI can now write a working app end to end. What it cannot do is know when the design is right, when the screens feel right, and when the result is safe to ship. Those calls are yours. GDD gives you a way to make them without reading a single line of generated code.
Why the usual way breaks
Prompt-and-hope produces demos, not products. The AI writes something that runs, you skim it, tweak the prompt, run it again. Every round loses a bit of the earlier context. Requirements drift. Failures hide behind code that "looks reasonable". Tests, if they exist, were written by the same model that wrote the bug they're meant to catch.
Reading the code to check does not scale. Modern AI writes faster than any reviewer can read, across languages and layers you may not know. What scales is checking behavior: input in, expected result out, one small step at a time, with the human on the hook only at named checkpoints.
The idea · gates, not vibes
A GDD project runs as five short loops, each ending at a gate. Inside a loop, you say what you want, the AI does the work and shows what it did, you ask questions or push back. When you approve, the loop closes and the next one opens.
What a gate actually is
A gate is a short, written checklist of what must be true for a phase to end. Every item on it is observable: a screen that behaves a certain way, a test that passes, a report that says so. No item on a gate is "the AI thinks it's good" or "the code looks clean". Nothing moves forward until every item is done and you sign off. That signature is the only thing that opens the next phase.
Why gates matter in AI development
A gate is the mechanism that lets a human stay accountable for AI output without reading AI output. Four specific problems it addresses:
AI writes faster than review scales. A model can generate a thousand lines across five files in the time it takes to read one function. Line-by-line review does not keep up. A gate replaces "read everything" with "inspect a fixed set of behaviors". The surface stays the same size no matter how much code was written.
AI is confidently wrong. Generated code often runs, passes shallow tests, and produces silently wrong results. "Looks reasonable" is the failure mode. A gate forces behavior evidence: the test either passed or it did not; the screen either does the thing or it does not. Judgment moves from surface reading to observable outcome.
Prompt drift is invisible. Without checkpoints, requirements shift across chat rounds. You said "under 60 seconds" three days ago; the current build assumes 90. A gate freezes the agreed items in writing. When drift happens, it is visible immediately because the gate no longer matches what was built.
Authority stays human. Automating engineering is not the same as authorizing a ship. A gate keeps the decision to move forward in a person's hands. The AI never advances itself past a gate, no matter how confident it is. Deferrals and open risks surface at the gate, not weeks later in production.
After launch, every new request re-enters at the right loop and closes at the same kind of gate. Ship is a gate, not the ending.
Why it works
Evidence over vibes
Every claim comes with proof you can read: test output, working screens, a plain report. "Looks fine" is not a gate.
One step at a time
You are never asked two things at once. The AI works small, checkpoints often, and never merges a batch you have not seen.
You own the decisions
What the app does, what it costs, who owns the account, the go to ship. Never the code, the tests, or the debugging.
How the process flows
Same three moves in every loop: you frame, the AI works, you decide. What changes each time is the artifact the loop produces.
Spec · frame the problem
A one or two page written plan: what the app does, who uses it, what stays out. Locked when you sign it.
Prototype · prove the flow
Clickable screens on fake data. Every use case listed and reviewable. Locked when the flows feel right. Two exits: KEEP (this becomes the app) or THROWAWAY (archived; the real app is built fresh from what you learned).
Design · plan what sits behind the screens
Every behavior turned into a testable checklist. Data model, rules, security, tech stack decided on paper. No code yet. The checklist becomes phase 4's test list.
Build · write real code with proof
One small step at a time, each landing with a passing test. A failing test can never be weakened. You read the coverage report: every checklist item done with proof, or openly deferred.
Deploy · verify and launch
Same scripted checks on your machine, on staging, on production. Deploy order is documented. Rollback is known before anything moves. You give the go.
Change · after launch
Every new request enters at the right loop. New feature returns to spec. Screen tweak returns to prototype. Behavior change returns to design. Bug returns to build, with a regression test.
What's in the playbook
The playbook is a set of plain markdown files. Common rules load every session. One phase file loads while you are in that phase. Support files (UX, sample data, API definitions) load when their trigger fires. Plug-ins are project-specific tokens the shared rules read (colors, fonts, size classes, tech-stack preferences); each project fills its own.
Every rule is written for the LLM to do the right thing. Same shape each time: definition, short explanation, one CORRECT example, one WRONG example. No filler prose, no marketing tone. The AI can cite the rule ID and knows exactly what "done" looks like. Humans can read the rules too, but they are not the primary audience.
The playbook also learns. When a project session hits a mistake whose root cause is a playbook gap, the AI logs a suggested rule change in that project. You rule on adoptions periodically. Real rules like "reconcile the prototype before building" and "verify external APIs with a live call" entered the playbook this way.
How the rules are earned
The playbook did not come from theorizing. It came from actually building. v1 was written across earlier AI projects with Claude Code and Codex, one mistake at a time. "Reconcile the prototype before building" came from a session where phase-4 code drifted from the phase-2 mock. "Verify external APIs with a live call" came from a session where an assumed OAuth flow turned out not to exist. "Grep before writing" came from a session where a duplicate helper was created next to an existing one nobody read. Each mistake got logged in mistakes/, discussed, and turned into a rule the next session had to honor.
Trovel is a real trip app built around three stages of a trip. Plan the trip: paste any itinerary (email, blog post, AI chat) and Trovel parses it into a day-by-day plan. Live it together: the itinerary, moments (a photo + a note), and expenses are all shared with your travel group during the trip. Keep it as a memory book you can hold private or publish. Trovel is also the app that took GDD v1 into a full end-to-end run.
v1 got Trovel through every gate. Spec locked at Gate 1 on 2026-07-08. Prototype locked at Gate 2 five days later on clickable screens with fake data. Design work through Gate 3 to lock the API contract, data model, storage, auth, and access rules. A Gate-4 build with tests per acceptance criterion. Gate 5 shipped the first version to trip.i80.com on 2026-07-15. Every change since (Explore feed, expense split, moments visibility, mobile viewport lock, iPhone footer polish, itinerary summary/note) re-entered the process at the right loop.
Trovel's real sessions then exposed gaps in v1's structure: rules scattered across one big file, no per-phase loading, no plug-in framework, no consistent CORRECT/WRONG pattern for the AI to pattern-match against. Those gaps became v2: five phase files that load only when their phase is active, support files that fire on trigger, 175 rules each written with a green CORRECT and a red WRONG example, plug-ins for per-project tokens. Same playbook, refined by using it.
Trovel · developed with GDD
What a token is. A token is a sub-word chunk the model uses as its unit of processing. Not a letter (too small), not a word (too big) — roughly a syllable. Common short words are one token (the, and, code); longer or rare words split into tokens (unbelievable → un + believ + able). Punctuation, spaces, and line breaks count too.
Rough ratio for English: about 4 characters per token, or three-quarters of a word per token. A 1,000-word article is roughly 1,300 tokens. Code, Chinese or Japanese text, and formatting-heavy content run higher.
| Token type | What it is | Example |
|---|---|---|
| Input | Text you send the model that is NOT stored in cache. | Your typed prompt on this turn. |
| Output | Text the model returns. | The AI's answer, code, or tool call. |
| Cache-write | Input the model reads AND stores in cache for later reuse. | System prompt + open files on the first turn. |
| Cache-read | Input pulled from cache instead of re-processed. | Same system prompt on turn 2 onwards. |
In long agentic sessions the same context is replayed on every turn, so cache-read volume balloons. That is not new work by the model, just re-reference. It is why generation cost stays a fraction of all-in cost.
The estimate is what these tokens would cost at API rates. The subscription is what actually got paid. Both numbers live in doc/usage_log.md, refreshed at every gate.
That is the closing loop of the playbook. GDD writes the rules. A real project surfaces a gap. The gap becomes a suggested rule. Adoption makes it official. The next project honors it. 175 rules today, most of them earned this way. GDD is still a work in progress. Rules keep getting added, and the next Trovel session may find another gap.
Who it fits
User-type builders without a coding background get the most from GDD. You describe the outcome and judge whether the working screens do what you asked. The AI handles everything technical: stack choice, data model, testing, deployment.
Engineer-type builders use GDD to move faster while keeping their standards. Every technical call is still yours to override; when you do, it becomes a binding constraint the AI honors from that point forward. The gates keep AI output aligned with the architecture you want.
Where GDD is not the right fit: payments, regulated data, and live production-data migrations. The AI stops and flags "engineer review recommended". Small apps are the target; being honest about that line is part of the design.
Try it
The playbook is public and versioned. Read the rules live, or download the ZIP and connect your first project.