Read before starting!

• Last updated: February 2026 
• Purpose: Turn a raw idea into a working, deployed product using Claude Code and AI-first tooling.
• Audience: Any team member, regardless of experience level. If you can read, you can follow this

Important: Read this before anything else

This workflow is built entirely around Claude Code. Every prompt, plugin, hook, MCP configuration, and workflow step in this runbook assumes you are using Claude Code as your AI coding agent. That is a deliberate choice, not an accident.

Claude Code gives us things other AI coding tools do not: native subagent and agent team orchestration, lifecycle hooks we can customise, an MCP protocol layer for plugging in external tools, a plugin and skills ecosystem, and full control over context management. The autocomplete and inline-edit features in tools like Cursor and Windsurf are useful for different things, but they are not designed for the kind of structured, multi-phase, multi-agent product builds this workflow enables.

If you want to use a different AI coding tool as your primary agent, this is not the right runbook for you. The prompts will not transfer. The plugins will not exist. The context management strategy assumes Claude Code's specific behaviour. You would spend more time adapting this process than building your own.

Where to run Claude Code

Claude Code runs in your terminal, or as an extension inside VS Code, Cursor, and IntelliJ. Use whichever environment you prefer. The prompts, commands, and workflows in this runbook work identically regardless of where you run it. If you already use Cursor or VS Code with their own AI features, that is fine. You can have those running alongside Claude Code. This workflow simply does not use or depend on them. What matters is that Claude Code is the agent doing the work described in these pages.

What Claude Code actually does

Claude Code reads your codebase, writes code, runs shell commands, and creates git commits. It can spawn subagents for focused tasks and coordinate agent teams for parallel work. It loads a CLAUDE.md file at session start as its project memory, and connects to external tools and documentation sources through the Model Context Protocol (MCP).

If you have never used Claude Code before, that is fine. Part 1 (Prerequisites) and Part 2 (Machine Setup) walk you through installing and configuring everything from scratch.

This workflow requires a paid Anthropic account

Claude Code is not available on free Anthropic plans. You need a Pro, Max, Team, or Enterprise subscription. The recommended model configuration (opusplan) uses Opus for planning and reasoning, and Sonnet for code execution, which balances intelligence with cost. Budget for real token spend, especially when using agent teams which consume roughly 5x the tokens of a solo session. Part 10 covers cost management in detail.

What this process gives you (and what it costs)

Process optimises for quality and reliability, not initial speed. Someone using a looser process, prompting Claude with a vague idea and letting it rip, will ship a first version faster than you. But their first version will be the thing they spend the next three months debugging, rewriting, and apologising for.

This process front-loads the thinking. By the time you write your first line of code, you have a tested idea, a detailed spec with acceptance criteria you can actually verify, architecture decisions recorded so nobody asks "why did we do it this way?", a design system so the UI is consistent from day one, and a phased plan so Claude never tries to build everything at once and loses the plot.

The result: what you build works. It holds up under testing. It is deployable. It does not fall apart when someone pokes it. And when you need to change something three months from now, the decision trail is there.

The trade-off is real. The planning phases (Parts 4–6) take 2–4 hours before you write code. On a small prototype, that can feel like overhead. But that time comes back, in fewer rewrites, fewer "why is this broken" sessions, and fewer phases where you have to throw everything away and start again. On anything beyond a throwaway demo, the maths works out in your favour.

This process cannot protect you from a bad idea. If the Idea Pack describes something nobody wants, this system will build it beautifully and reliably. Product validation is outside the scope of this runbook, do that work separately before you invest build time.

How this runbook works

This is a step-by-step, print-it-out-and-follow-it guide. It is split into numbered parts. You do them in order. Each part tells you exactly what to type, what to click, and what the expected result looks like so you know it worked.

Do not skip parts. Do not jump ahead. Each part builds on the one before it.

The parts (do them in this order)

The tools we use (and what each one actually is)

Non-negotiable team rules

These rules apply to every project, every time. No exceptions.

1. Context is disk, not chat. If it matters, it is written into /docs/, tracked in Beads, or recorded in an ADR. If it is not in the repo, it does not exist.
2. Strong inputs before code. We do not build until we have an approved Idea Pack, PRD, acceptance checklist, and initial ADRs.
3. Beads is the task system. No "we'll remember it later." Multi-step work becomes Beads issues.
4. No guessing external APIs. Use Context7 for libraries and frameworks. If Context7 cannot confirm it, fetch official docs or ask a human and record the decision in an ADR.
5. AI does setup. Humans do not manually create folders, config files, or documents. The only manual filesystem step is creating an empty project folder.
6. One phase at a time. Never ask Claude to build the entire app. Break work into phases. Build one phase, test it, then move to the next.
7. Test after every change. Every build phase ends with running the test suite. No exceptions.
8. Git is your safety net. Commit after every successful phase. Use branches. Never work directly on main.
9. Watch your context. Never exceed 60% context utilisation. Use /clear between phases. Use /compact when context grows large.
10. Security first. Never commit secrets. Always deny Claude access to .env files. Review every command Claude wants to run before approving.

Quick reference: Claude Code commands you will use constantly

Ready? Open Prerequisites and start.