DEV-103-1.1
Planning with GSD
Verified current as of November 14, 2026
Most thrash in a build doesn't come from hard code. It comes from code you wrote against a target nobody pinned down. You implement a feature, the requirement shifts under you, and you rewrite it twice. The fix is a planning loop that forces the decisions out of your head and onto disk before an agent touches the keyboard. The mental model: an autonomous coding agent is only as good as the spec you hand it. Vague spec, vague output. A precise, version-controlled blueprint turns Claude from a guesser into an executor.
Call the loop what it does: Understand → Plan → Write the Spec → Define "Done" → Build. The first four are cheap and the last one is where you'd otherwise bleed days, so the trade is lopsided in your favor.
Understand, then write two files
Understanding is interrogation, not prose. Pin down the problem, the actual user, what already exists and why it falls short, your constraints, and the scariest unknown. One or two sentences each. Claude Code's Plan mode is built for this stage: it reads and researches but changes nothing until you approve a plan (start with claude --permission-mode plan, or press Shift+Tab until the status line shows plan mode).
Then you produce two artifacts, and the split matters: PRD.md is for humans: what, who, why, and what "done" means. spec/plan.md is for the builder: architecture, schema, route map, ordered steps, and risks. Keep them separate because they change for different reasons. A stakeholder edits the PRD; you edit the plan when the implementation order shifts.
The single highest-leverage section is the implementation order. Make every step a day or less, and front-load the skeleton so the agent can run something end-to-end early:
## Implementation Order
1. Next.js (App Router) + Tailwind skeleton, deploys to Vercel preview
2. Supabase project + `profiles` table, RLS enabled, explicit grants
3. Dashboard route with hard-coded fake data
4. Swap fake data for a Supabase server-side query
5. Build the create-record server action
Write the spec, then define "done"
The spec isn't real until it's committed. One git commit gives the plan history, lets it survive a bad refactor, and makes it something a teammate, or tomorrow's you, can read. Don't skip it.
Defining "done" is where most specs go soft. "Works well" isn't checkable; a passing test, a rendered screen, or a queryable number is. Bake the baseline straight into the PRD:
## Done When
- [ ] No horizontal scroll at 375px width
- [ ] Browser console clean across every screen (zero red errors)
- [ ] Primary flow completes unattended: sign up → create → edit → delete
- [ ] Dashboard aggregates match the underlying Supabase rows
- [ ] RLS verified: logged-in users see only their own rows
- [ ] `.env` is gitignored; no secrets in history
- [ ] One push to `main` produces a clean Vercel build
Note the Supabase-specific teeth: "auth works" becomes "RLS verified, users see only their own rows." That's a check you can actually run.
The engineered planning prompt
Plan a habit tracker app for me.
We're in Plan mode. Don't write code. I want to build a habit tracker for one user type: people who check in once a day on their phone. Interview me first: ask up to 6 questions, one at a time, about the problem, the user, constraints, and the riskiest unknown. Then write two files: - PRD.md: problem, user, exactly 3 core features (put everything else under Out of Scope), and a "Done When" list where every item is observable (a test, a screen, a query, a number). - spec/plan.md: stack (Next.js App Router, Supabase with RLS and explicit grants, Vercel), schema, routes, and an implementation order where every step is one day or less and step 1 deploys a skeleton. Include in Done When: RLS verified by a signed-in test user, no secrets in git history, and a clean production build. Flag any requirement you had to assume, under "Assumptions to confirm".
What each element changes: "Interview me first" makes Claude pull decisions out of you rather than invent them. "Exactly 3 core features" forces cuts. "Observable" Done-When items become your acceptance tests. "Assumptions to confirm" surfaces what Claude guessed.
Pitfalls
- Scope creep in the PRD. If the core feature list grows past three to five items, you haven't finished deciding. Tell Claude to cut to three and shove the rest into Out of Scope.
- Security as a bolt-on. Auth model, secret handling, and input validation belong in Done When now. Retrofitting RLS or moving keys to
.envafter the build is far more expensive than five minutes up front. - A plan that drifts from reality. If you started building without one, don't fake a clean spec: have Claude read the current tree and write the PRD to match what exists plus where you're headed.
- Treating the plan as frozen. It's version-controlled precisely so you can amend it. When reality contradicts the spec, update the spec and commit; don't let code and plan silently diverge.
- Claude can't know your users. It will propose plausible requirements; the interview and "Assumptions to confirm" are how you catch the wrong ones.
- Plan mode reads, it doesn't verify. A plan can reference a library version or API that has changed; check versions against current docs before building, as of November 2026.
- Day-sized steps are estimates. Re-slice any step that takes Claude more than one session.
⌨️ Exercise
Pick a real tool you'll actually build. In its repo, start Claude in Plan mode and send the engineered prompt with your own idea (or write PRD.md and spec/plan.md by hand). Constrain the core feature list to exactly three. Break the implementation order into steps no longer than a day each, with step 1 being a deployable Next.js skeleton. Rewrite every "Done When" item until it's observable, and include at least one Supabase RLS check phrased as something you can query. Commit both files, then confirm with git log --oneline -5. Done means zero remaining [brackets] in either file.
- Understand → Plan → Spec → Done → Build; do the first four in Plan mode.
- PRD.md is for humans, spec/plan.md for the builder; commit both.
- Every step a day or less, skeleton first; every Done-When item observable.
- Security items (RLS, secrets, build) go in Done When from day one.

