Architecture

Two architectures shape every Playbook project: the underlying discipline of working with a non-deterministic model, and the four-surface deployment topology the code ships through.

Context engineering

The Playbook is a set of practices for working with Claude Code. The discipline underneath those practices is context engineering — the work of giving a stateless model with a finite context window the right information in the right shape at the right time.

Three constraints shape the discipline. Statelessness: Claude doesn’t remember anything between sessions, so everything it knows about your project has to be provided each time. Finite context window: there’s a fixed token budget per session, and every rule loaded eats into the budget the actual work runs against. Non-determinism: the same prompt with the same context can produce different outputs, so quality has to come from the inputs and the review process rather than from the assumption of a single correct answer.

Every primitive in this Playbook is a form of context engineering. CLAUDE.md decides what’s always loaded, memory.md records decisions for future sessions, skills load on demand, sub-agents work in their own window, and the Plan Gate forces re-grounding before code is written. The rest of these Foundations describes the primitives one at a time and when each earns its keep.

What Claude Code isn’t great at

The Playbook assumes Claude Code is the right tool for the work in front of you. Four shapes of work it consistently isn’t:

• Pixel-perfect visual work. Claude Code can describe layouts and write CSS, but it can’t see what it’s produced. If the gap between “the code looks right” and “the design looks right” is your bottleneck, you need a designer in the loop, not a model.
• Projects without clean folder organisation. The model relies on file paths to understand structure. A repo with arbitrary layout or unconventional naming forces every prompt to re-establish context. The cleaner your folders, the more useful the tool.
• Real-time multi-user collaboration. Claude Code works in your local repo, not a shared session. If you and a colleague need to edit the same files at the same time, that’s a tooling shape Claude Code doesn’t fit.
• Tasks that still need clear guidance. File access doesn’t substitute for knowing what you want. Vague instructions produce vague output even when the model can read everything. Writing the prompt is your job; executing it is the model’s.

If your work matches one of these, reach for a different tool.

The four surfaces

The deployment topology has four surfaces. Knowing what each one does keeps you oriented when a later step refers to “Vercel” or “the local machine”.

• Local machine. Your Mac. Where Claude Code runs. Where your editor opens project files. Where npm run dev happens.
• GitHub. Source of truth for code. The local repo pushes here; Vercel pulls from here.
• Vercel. Production hosting. Auto-builds and deploys on every push to main. Holds the production environment variables.
• Supabase. Managed Postgres + auth + storage (when the project needs a database). Holds production data.

External AI service APIs (OpenAI, Anthropic, Perplexity, etc.) sit outside this topology — they’re called from Vercel-hosted server code at runtime, never from the browser.

Runtime data flow

You write prompts in Claude Code → Claude Code generates files locally → you commit and push → GitHub triggers a Vercel build → Vercel deploys → users hit the live URL → the live app talks to Supabase and external APIs.

Why these four surfaces

This stack is opinionated for solo and small-team builds: minimal moving parts, generous free tiers, and tight integration between the layers. Vercel auto-deploys from GitHub. Supabase issues credentials your Next.js app reads from environment variables. Claude Code orchestrates the local development loop.

Substituting another tier (Cloudflare Pages, Neon, PlanetScale, Railway) is straightforward but every substitution adds setup cost. Stick with the defaults until you have a real reason not to.