Plan It Before You Build It

The cost of skipping planning rarely shows up on day one. That is exactly what makes it dangerous.

When you go straight to building, AI produces code that works, passes tests, and deploys cleanly. For the first few weeks everything looks like progress - and that appearance of progress is what makes the problem so hard to catch until it is already expensive.

Let me give you a concrete example from building Control Beacon.

During an early session, I had not fully documented the authentication configuration in my planning documents. AI followed what was available and configured the authentication service against the original tenant domain instead of the custom domain I was using. Everything worked fine in development...

When the build reached production, users started hitting 401 errors - tokens issued by the custom domain were being validated against a different one. The fix turned out to be a single environment variable.

Finding the cause took hours (P.S. if you don't have version control, the deeper AI goes into "fixing" the deeper it keeps digging itself in).

That kind of failure is not a coding error. AI did exactly what it was supposed to do - it followed the configuration it had. The failure was a planning failure. The domain decision should have been documented before a single session started.

This pattern repeats in different forms across almost every rushed build.

AI makes a reasonable assumption early on, subsequent sessions build on top of that assumption, and by the time the problem surfaces it is no longer one wrong decision. It is a structural issue that touches multiple parts of the codebase.

Rushed planning does not feel like a mistake when you make it… it feels like momentum. And then, the invoice for costs of you re-running deployments arrives later (does this sound too dramatic? trust me, I had to pay for this mistake few times).

The data on this is specific enough to be useful before you decide how seriously to take the planning phase.

45% of AI-generated code contains security vulnerabilities, and that figure has not improved across multiple testing cycles through early 2026 despite significant advances in model capability.

The vulnerabilities are not exotic edge cases - they are the fundamentals: cross-site scripting, SQL injection, improper authentication checks, hardcoded credentials.

These are not introduced because AI is careless...

They are introduced because AI optimizes for functionality. It builds what you asked for in a way that works, without awareness of the security context your product operates in. Without a planning layer that defines those constraints before code is written, AI has no way to apply them.

Beyond security, there is the structural cost.

Repositories with significant AI-generated code show a 322% increase in privilege escalation flaws and a 153% rise in architectural design flaws compared to human-written equivalents. These are architectural decisions AI made because no one defined the architecture first - not obscure edge cases, but the kind of structural problems that require a refactor to fix.

By the time these surface, they are rarely a single fix. They are a refactor.

And a refactor on a live product with paying users is one of the most expensive situations a technical founder can face - not just in engineering time, but in the trust you lose with users when something that should have been solid turns out not to be.

The planning layers in this course exist to address this before AI writes anything. Each one is a category of decision that belongs to you, not to AI.

The rest of this course is about making sure those decisions are made explicitly, documented clearly, and handed to AI as constraints - not left as gaps for AI to fill on its own.

Most founders plan some things before they build. They think through the core idea, sketch the main feature, and pick a rough tech stack. That is a start - but it leaves most of the decisions AI needs to do its job either undocumented or missing entirely.

Here is a practical way to think about it:

Imagine you are building a SaaS product and you hand your AI tool the following brief: "Build me a multi-tenant platform with subscriptions, user roles, and a dashboard." AI will build something. It will make hundreds of decisions along the way - about how tenants are isolated, how roles are enforced, how billing interacts with access, what happens when a subscription expires.

None of those decisions will be flagged.

All of them will be based on what is most common, not what is correct for your specific product.

The planning layers that most founders skip are the ones that answer exactly those questions before AI has a chance to guess:

Your ICP definition tells AI who the product is for. Without it, AI optimizes for a generic user - generic defaults, generic assumptions, generic security posture.

Your financial planning maps your actual costs against your pricing model before you build. I have seen founders complete technically solid builds only to discover the infrastructure costs make the pricing model unworkable. That is a planning failure, not a technical one.

Your guardrails define what AI must never do - what it must always verify, what it must never hardcode, how it should handle uncertainty. Without these, every undocumented decision gets made by AI, not by you.

Your QA and release protocol defines what good looks like before building starts. Defining it after means the patterns are already established and the debt is already accumulating.

And your marketing site - this one surprises most people. Writing what your product does in plain language before building it forces a precision that planning documents alone rarely achieve. If you cannot explain it clearly enough to put it on a page, the product is not defined clearly enough to build.

Each of these is a full stage in this course. Together, they are the difference between AI building what you intended and AI building what it assumed you intended.

A vision document that sits in a folder and gets opened occasionally is not the same as a vision document that governs every session.

The way I structured the Control Beacon vision was as a permanent reference inside the CLAUDE.md - the master instructions file that every Claude Code session loads automatically at the start. The vision was not a separate document that I remembered to attach sometimes. It was the first thing AI read before doing anything, every single time.

This matters more than it might seem.

AI has no memory between sessions. Every time you open a new session, it starts fresh.

Without a document that immediately re-establishes what you are building, who it is for, and what the boundaries are, the session defaults to whatever is in the immediate prompt.

Over a two-week build with dozens of sessions, that drift compounds into something significant.

There are a few things that make a vision document genuinely usable by AI rather than decorative:

• It needs to be specific enough that AI cannot interpret it multiple ways. "A platform for QA teams" leaves room for interpretation.
• "A multi-tenant SaaS platform where QA teams subscribe once and access multiple testing tools under a shared login" leaves much less.

Second, it needs to include the explicit constraints - what the product does not do, what decisions have already been made and are not up for discussion. These are the guardrails that prevent AI from suggesting alternatives to things you have already decided.

Third, it needs to be kept current.

As the build progresses and decisions get made, those decisions get added to the document. The vision at week two should reflect what you learned in week one. A static document that never gets updated stops being useful quickly.

The format matters less than the discipline. A well-maintained markdown file loaded at the start of every session is more valuable than a beautifully structured document that AI never sees.

Your ICP shapes more technical decisions than most founders expect.

Consider a hypothetical: you are building a project management tool. You know your customer is a freelance designer. But AI does not know that unless you tell it.

Left to its own defaults, AI will build for a generic user - which usually means a more complex role and permissions model than you need, a data structure optimized for team collaboration rather than individual use, and default assumptions about usage volume that do not match a solo freelancer's actual patterns.

None of those decisions are wrong in isolation. They are just wrong for your customer.

And because they get made in the first few sessions, before the product has any real shape, they influence everything built afterwards.

In the Control Beacon build, the ICP was a digital product team - specifically, a team where different members needed access to different tools with different roles.

• That single constraint shaped the entire multi-tenant architecture,
• The organization and member model,
• The way roles were structured at both the platform and app level,
• And the billing model.

Every one of those decisions traced back to a clear answer to the question: who is this for and how do they work?

When your ICP is documented in your planning files, AI applies it automatically. When it is only in your head, AI guesses - and the guess is rarely specific enough to match your actual customer.

Beyond the technical decisions, your ICP also affects the defaults AI sets for things like error messages, onboarding flows, and the language used throughout the product.

A tool built for developers reads differently from one built for non-technical users.

AI will default to one or the other based on what it can infer from your prompts. Documenting it explicitly removes the inference.

Writing your marketing site before building the product is the most underrated planning exercise in this course - not because you will publish it immediately, but because of what the process forces you to figure out.

A marketing site has to answer a specific set of questions in plain language: what is this, who is it for, what problem does it solve, why should I trust it, and what do I do next. Those are not marketing questions. They are product definition questions.

And the discipline of answering them in plain language - without falling back on technical descriptions or internal terminology - surfaces gaps in your thinking that planning documents alone often miss.

When I was planning Control Beacon, having to write the marketing site copy forced me to articulate the value of each app in a sentence that a non-technical buyer could understand.

• That exercise revealed which apps had a clear, differentiated value and which ones I was still thinking about too abstractly.
• The apps that were difficult to write a clear sentence for were the ones that needed more definition before I started building them.

The other thing a marketing site draft does is force a decision about positioning before you are too deep in the build to revisit it.

The architecture you build reflects the product you think you are building. If your idea of the product shifts after weeks of development, the architecture may not shift with it cleanly.

Defining the product clearly enough to market it before you build it means the build starts from the right foundation.

This does not need to be a finished site. A rough draft - even just the homepage copy and a pricing structure - is enough. The goal is the thinking it requires, not the output itself.

There is a category of stack decisions that feel irrelevant at MVP stage and become very relevant later.

The version of a package you pin, the ORM you choose, the way you structure your database schema, the authentication model you build around - none of these feel urgent when you are trying to ship something working.

All of them become expensive to change once you have real users and real data.

A concrete example from the Control Beacon build: during development, I was using the Neon serverless database driver pinned to version 0.10.x. At one point the driver released a version update with a breaking API change that was incompatible with the version of Drizzle ORM being used.

The CLAUDE.md had a specific note pinning the Neon driver to 0.10.x - not because this was obvious upfront, but because it had been discovered and documented as a decision.

That note meant AI would never silently upgrade to a version that broke the stack.

This is the kind of long-term thinking that belongs in your planning documents before you start building.

Not because you will anticipate every version conflict, but because documenting the reasoning behind your choices gives AI - and any future developer - the context to make compatible decisions rather than conflicting ones.

A separate example from the same build: during planning for Team Clarity - one of the project management apps in the Control Beacon platform - FullCalendar (great component by the way) appeared to be a viable open-source option for the calendar component.

AI suggested it, it looked fine, and it got used.

Several sessions later, it turned out that FullCalendar is not actually free for commercial use - the free-tier packages still require a commercial license. The entire calendar had to be removed and replaced with a custom React and Tailwind implementation. That rework cost sessions that a five-minute licensing check during planning would have prevented.

Long-term stack decisions are not about predicting the future.

They are about documenting your reasoning so that the reasoning survives beyond the session where it was made.

Every session starts from scratch.

Without a document that tells AI exactly what you are building with, it defaults to what it knows most about - which is usually the most popular option at the time of its training, not the specific tool you chose for your specific reasons.

In practice this means AI will suggest alternatives, reach for packages that conflict with your existing choices, or make assumptions about your infrastructure based on what it can infer from the code rather than what you actually decided.

None of this is malicious. AI is filling gaps you left open.

The way to close those gaps is a tech stack section in your CLAUDE.md that is specific enough to remove ambiguity.

• Not "we use Next.js" but "Next.js 15 App Router deployed on Vercel - do not suggest migration to Pages Router or alternative frameworks."
• Not "we use a PostgreSQL database" but "PostgreSQL via Neon serverless driver pinned to version 0.10.x - do not upgrade to v1.x, breaking API change incompatible with Drizzle ORM 0.36.x."

That level of specificity might feel excessive when you are writing it.

It becomes very obvious why it was necessary when AI suggests an upgrade that would break three apps simultaneously.

The tech stack section should cover every tool, every service, and every third-party integration - with the version where it matters and a one-sentence note on any constraints or decisions that are not up for revisiting.

This is also where you note what you are explicitly not using and why, if the alternative is something AI would commonly suggest.

When this section is current and loaded at the start of every session, AI operates inside the boundaries you set rather than the boundaries it assumes.

The difference in output quality - and in the number of suggestions you have to reject - is significant.

The short answer is that undocumented stack decisions get revisited - by AI, in sessions where you are focused on something else, in ways you do not always catch immediately.

During the Control Beacon build, recharts was used as the charting library for one of the apps.

It worked well initially.

Several sessions later, during the development of a separate feature in the same app, AI introduced code that was incompatible with React 19 - which recharts had a known issue with at the time.

The library had to be removed and all chart components replaced with CSS-based implementations. The replacement work was not complicated, but it was unplanned and it interrupted a build that had momentum.

The root cause was not AI making a bad suggestion.

It was that the constraint - recharts has React 19 compatibility issues, do not use it - was not in the CLAUDE.md.

AI had no way to know it was a decision that had already been evaluated and rejected. From AI's perspective, it was just reaching for a commonly used charting library.

This pattern repeats in different forms across almost every build that lacks a documented stack:

• AI suggests a package that conflicts with an existing dependency.
• AI upgrades a version that breaks a downstream integration.
• AI introduces a library that works fine in isolation and fails in the context of your specific setup.

Each instance is a small interruption in isolation. Across a two-week build, they accumulate into something that measurably slows you down.

The documentation discipline in Stage 3 of this course is not about covering every possible scenario. It is about capturing the decisions you have already made clearly enough that AI cannot unknowingly contradict them.

That is a much smaller surface area than it might seem - most builds have fewer than twenty decisions worth documenting at this level. The return on writing them down is immediate.

Most founders set a price and then figure out what the product needs to deliver at that price.

The more reliable approach is to start with the margin you need and work backwards to what the product must cost to deliver.

The calculation is not complicated:

1. Take your target monthly revenue at a realistic early user count - say, 50 paying customers.
2. Subtract your fixed infrastructure costs.

What remains is your gross margin per customer at that volume.

If that number is negative, or too thin to sustain the business, your pricing is wrong - and it is better to know that during planning than after you have built a product around a pricing model that cannot support it.

For Control Beacon, the pricing model went through multiple iterations during development - starting with a simple Free and Single App tier, moving to a bundle model, and eventually settling on a three-tier Pro and Team structure with org-wide usage pools.

Each iteration involved going back to the cost model and checking whether the new pricing still produced viable margins across different customer sizes.

That ongoing financial thinking is what made each pricing change deliberate rather than just a product decision.

The feature set question follows directly from the margin calculation.

If delivering a feature requires AI API calls at significant volume, that cost needs to be factored in before the feature is built.

In the Control Beacon build, the AI-powered features - Visual Check comparisons, Speed Audit analysis, Test Pilot case generation - all involve Anthropic API calls at a cost of roughly $0.002 to $0.25 per operation depending on the feature.

Those costs were planned into the usage limits and credit pack structure.

A user who runs 100 Visual Check comparisons a month generates AI API costs. The pricing model has to account for that, and it only can if you have mapped it during planning.

The outcome of this exercise is not a perfect financial model.

It is a documented set of assumptions and proposed calculations - margin targets, cost per user at different scales, feature cost estimates - that AI can reference when making decisions about how to implement usage limits, trial restrictions, and billing logic.

They end up in the same document because the decisions inform each other in ways that are not obvious until they collide during the build.

A billing model decision is also a database schema decision.

Whether you charge per seat, per usage, per organization, or some combination determines how your subscription table is structured, how your entitlement checks work, how your usage tracking is implemented, and how your pricing page needs to be presented.

These are technical decisions that flow directly from financial ones.

If the financial model is not documented alongside the technical architecture, AI builds the technical layer based on whatever billing model it assumes - and changing a billing model after the subscription infrastructure is built is one of the more painful refactors a SaaS product can go through.

For Control Beacon, the org-wide usage pool model - where usage limits are shared across all members of an organization rather than per seat - was a deliberate financial decision:

• More seats per organization means more revenue at the same infrastructure cost, because the usage ceiling stays fixed regardless of how many seats are added.

That decision shaped the entire entitlement and usage tracking architecture.

It was documented in the planning files as a financial decision, and the technical implementation followed from it consistently because AI had both the financial reasoning and the technical constraints in the same reference document.

The same principle applies to trial design:

• Offering a 14-day free trial with no credit card required is both a marketing decision and an infrastructure decision.

It means every trial user consumes real resources - database space, AI API calls, authentication operations - without generating revenue. The trial limits need to be calibrated against those costs.

If the financial model is not in the planning document, AI will implement whatever trial limits you describe without any awareness of whether they are economically sensible.

Keeping financial and technical planning in the same document is not about having a polished business plan. It is about making sure the decisions that depend on each other get made together, before the build locks them in separately.

AI hallucination in a development context does not usually look like a fabricated fact.

• It looks like a function call to a method that does not exist in the version of the SDK you are using.
• It looks like a database column name that was never created.
• It looks like a route that AI believes exists because it generated similar code three sessions ago.

These are not obvious errors.

They compile, or they look plausible, and they only surface when something breaks at runtime - often in production, often after other code has been built on top of the assumption.

The anti-hallucination rules I used in the Control Beacon build addressed this directly.

The key rules were:

1. Never answer a question about project state from memory - always read the relevant file first.
2. If calling an SDK method, verify it exists in the pinned version - if unsure, flag it explicitly.
3. When writing database queries, read the actual schema file first - never guess column names.
4. When calling an internal API endpoint, read the actual route file - never assume the endpoint exists.

These rules do not eliminate AI uncertainty. What they do is change how AI handles uncertainty.

Instead of filling the gap confidently, a well-governed AI session flags the gap and asks for verification. That shift - from confident wrong output to flagged uncertainty - is exactly what the rules are designed to produce.

The phrasing I used was specific: "If you cannot point to a specific file and line that confirms a claim, you must flag it before stating it. Do not present uncertain information as fact."

That instruction, loaded in every session, changed the character of the output in a way that was immediately visible. Sessions that ran with it active produced more cautious, more accurate code - and that caution can feel like slower progress. It is not. It is the control layer working as intended.

Hallucination is AI inventing something that does not exist.

Assumption is AI stating something that might exist, might be partially correct, or was correct at some point - without verifying it is still true right now.

In a long build, assumptions are often more dangerous than hallucinations because they are harder to catch.

A hallucinated function name fails visibly when the code runs.

An assumption about project state - "I believe we implemented rate limiting in session four" or "the migration for this table should already be applied" - sounds plausible, gets accepted, and only surfaces as a problem when the code that depended on it reaches production.

A specific example from the Control Beacon build:

• I added an explicit rule to the CLAUDE.md after catching Claude Code stating the status of a backlog item from memory rather than reading the backlog file.
• The rule read: "When answering any question about project state - what routes exist, what has been implemented, what environment variables are set, what is on the backlog - always read the relevant source file first. Never reconstruct from memory or conversation context."

That rule was added because the assumption had already caused a problem - not a catastrophic one, but a session where AI proceeded on the basis of something it believed to be true that was no longer accurate.

The rule was a direct response to observing the failure mode.

Anti-assumption rules are distinct from anti-hallucination rules because they address a different behaviour.

Anti-hallucination rules say: do not invent things.

Anti-assumption rules say: do not rely on what you think you remember - check the file.

Both are necessary. A session with only one set of rules will still fail in the way the other set prevents.

Session hygiene is a planning problem because the decisions you make about how to structure your sessions - what goes in one session, when to start a new one, what gets documented at the end of each one - need to be established before you start building, not discovered through trial and error during the build.

The core issue is context compression.

AI models have a finite context window. As a session runs longer, earlier content gets compressed - the initial instructions, the architectural decisions, the guardrails set at the start.

The model continues producing output, but that output is no longer anchored to the full context it started with. It drifts.

The drift is subtle enough that you often do not notice it until you review the output and realise something is inconsistent with a decision made two hours earlier in the same session.

What I found during the Control Beacon build was that disciplined session management produced a clear improvement in output quality - and that the discipline had to be explicit to hold.

The session hygiene rules in the CLAUDE.md included:

1. Start a new session when switching topics, because each new session reloads the full CLAUDE.md fresh.
2. If the session has been running long and context feels uncertain, flag it and suggest starting fresh rather than guessing.
3. At the end of every session, update the CLAUDE.md, commit, and push - so the next session starts with a complete and current picture of where the project stands.

These rules address a different problem from the anti-assumption rules in Lesson 5.3.

Anti-assumption rules govern what AI states within a session - don't claim what exists without reading the file first.

Session hygiene rules govern the session itself - when to end it, what to do at the boundary, how to ensure the next session starts clean. Both are necessary.

An AI that checks files before answering but runs in sessions that never end and never get updated will still accumulate drift, just more slowly.

That last rule - update and commit at the end of every session - is the most important one to establish during planning, because it shapes how you work from session one.

A team - or a solo founder - that builds the update-and-commit habit from the beginning ends up with a living document that accurately reflects the codebase. A team that does not - ends up with a CLAUDE.md that gradually diverges from reality.

Stop and revise. Every time.

The planning work in this course is designed to minimize planning mistakes, not eliminate them.

Real builds discover things that planning sessions miss:

• An architectural decision that seemed reasonable until you saw it interact with another system,
• A pricing assumption that held until you calculated actual API costs per user,
• A role model that made sense on paper but does not match how users actually work.

These are not planning failures. They are what happens when a plan meets reality.

The mistake is treating a discovered error as something to work around rather than correct. When the build reveals an early decision was wrong, the instinct is to keep moving and handle it later.

Later is three sprints deeper, with more code built on top of the wrong decision, and an eventual rework that costs far more than stopping now would have.

During the Control Beacon pricing migration, the billing model moved from per-seat limits to org-wide usage pools partway through the build. That touched the database schema, the entitlement checks, the usage tracking logic, and the pricing page.

Stopping to update the CLAUDE.md before continuing felt like lost time... it was not.

Continuing without updating it would have meant every subsequent session building on a documented model that no longer existed - precisely the condition that produces confident, wrong AI output at scale.

When a plan changes, three things happen before any new code is written:

1. Identify everything the changed decision touches downstream.
2. Update the CLAUDE.md, the relevant planning documents, and the backlog.
3. Add the old decision and why it changed to the decisions log - future sessions need to understand why the codebase looks the way it does, including the decisions that were reversed.

The planning documents are not a contract.

They are the current best picture of the system. Keeping them accurate when that picture changes is not overhead. It is the mechanism that keeps AI building the product you are now building, not the one you planned three weeks ago.

Defining metrics after a feature is built means retrofitting tracking into code that was not designed to expose the events you need.

It is possible, but it is slower, and it often produces instrumentation that is incomplete because the right data was never surfaced at the right point in the code.

Defining metrics before building means AI implements the feature with the tracking built in from the start.

The event fires at the correct moment, carries the correct properties, and goes to the correct destination - because all of that was specified before the feature was written rather than added afterwards.

For Control Beacon, the tracking setup was PostHog - chosen specifically because it is GDPR-compliant with data stored in Frankfurt, and because it supports cookieless analytics which removed the need for a cookie consent banner.

• Both of those constraints ruled out Google Analytics, which requires cookies and stores data outside the EU by default.

Those decisions were made during planning and documented in the CLAUDE.md as standing rules: never use Google Analytics, always use PostHog EU at eu.i.posthog.com.

• The result was that every app in the build used the same analytics setup consistently, because AI had no ambiguity about what to use or why.

Beyond the tooling decision, the more important planning question is what you actually want to measure.

For a SaaS product, the metrics that matter at early stage are usually the ones that tell you whether users are activating, whether they are hitting limits, and whether they are converting.

Those three categories should be defined before you build the features they track - not because you need a perfect analytics strategy, but because knowing what you want to measure changes how you build the feature that produces the measurement.

A product built without defined metrics is harder to improve because you cannot tell which parts are working.

Defining what you will measure during planning ensures the build creates the observability you need from day one rather than trying to add it later.

A staging release checklist has one job: to catch the problems that only appear in an environment that matches production without the risk of breaking production itself.

The problems staging catches are a specific category.

• Not logic errors - those get caught in development.
• Not type errors - those get caught in CI.

Staging catches integration failures:

1. The authentication service that works in isolation but fails when connected to the actual provider,
2. The payment webhook that processes correctly in tests but times out against the live sandbox,
3. The environment variable that is set in development but missing in the deployment configuration.

In the Control Beacon build, one of the more instructive staging failures was the double-commit trap.

When code changes and a CLAUDE.md update were pushed as two separate commits back-to-back, Vercel would only process the HEAD commit.

The build system compared HEAD to HEAD^ and saw only the CLAUDE.md change, cancelled the build, and the code changes never deployed (!).

Everything appeared to have worked - the commit went through, the pipeline ran - but the actual code never reached the environment.

• The fix was simple once understood: always combine code changes and CLAUDE.md updates into a single commit.

But finding it required a staging deployment that revealed the behaviour before it caused a problem in production.

A staging checklist for a SaaS product typically covers:

• environment variables present and correctly valued,
• external service connections active and authenticated,
• database migrations applied and verified,
• critical user flows working end-to-end,
• and the specific integration points between services confirmed.

The exact list depends on your stack, but the principle is the same - staging exists to validate the deployment itself, not just the code.

Defining this checklist during planning means AI can build with it in mind.

Deployments that need to be validated against a specific checklist are structured differently from deployments that are simply pushed and observed.

Staging validates that the deployment works.

Production protocol manages the risk of something that passed staging failing in ways that only real users and real data can reveal.

The difference is not a question of confidence - if staging is thorough, you should be confident.

It is a question of consequence.

• A failure in staging affects no one.
• A failure in production affects paying users, generates support tickets, and erodes trust in ways that are hard to recover from quickly.

The production protocol is what you do to contain that risk rather than eliminate it entirely.

In the Control Beacon build, the production validation test cases were organised into pre-deploy and post-deploy tiers for exactly this reason.

1. Pre-deploy checks run against the production API before any new code goes live - verifying that the current state of production is stable before introducing changes.
2. Post-deploy smoke tests run immediately after deployment to confirm the critical paths are working with real infrastructure.

The flows covered were authentication, billing, entitlement checks, user provisioning, and the core comparison functionality - the paths where a failure would be immediately visible to users.

A specific example of why this separation matters: during the pricing migration, a database migration file existed on disk but had never been added to the Drizzle migration journal.

The automated migration process skipped it silently.

The code that expected the new database column deployed successfully.

The first time a user triggered a route that touched that column, every related route in production returned a 500 error.

A pre-deploy check that verified the database schema against the expected state would have caught it before deployment.

The production protocol does not need to be elaborate. It needs to be specific and consistently followed.

A checklist of ten items run before every production deployment, and five smoke tests run immediately after, covers the majority of failure modes that staging alone does not catch.

The order matters significantly, and the principle that governs it is simple: build the infrastructure before the features that depend on it, and build the highest-risk items before the lowest-risk ones.

Infrastructure first means the shared components that every part of the product relies on get built and stabilized before anything builds on top of them.

In the Control Beacon build, this meant the monorepo structure, the shared packages, and the Central API came before any product app.

1. The authentication layer came before any access-controlled route.
2. The database schema for users and organizations came before any feature that stored per-user or per-organization data.

Each of those decisions was a sequencing decision, not just a technical one - and building in that order meant that when product features were built, they connected to a stable foundation rather than a foundation that was still changing underneath them.

Highest-risk items first is the other sequencing principle that the Control Beacon build reinforced.

The payment integration, the authentication SSO, the multi-tenant data isolation - these were the areas with the most potential to require architectural rework if the initial approach turned out to be wrong.

• Building them early meant discovering any fundamental issues before weeks of product features had been built on top of them.
• Building them late means discovering the same issues after most of the product exists and the cost of rework is much higher.

The sequencing trap to avoid is building what feels most exciting first.

The features that demonstrate the product idea most clearly are often not the ones that should be built first. They usually depend on infrastructure that needs to exist before they can work correctly.

Building them first means building them in a vacuum, then often rebuilding them once the infrastructure they depend on is in place.

A practical way to sequence a backlog is to group items into three layers: infrastructure and shared components, core product flows, and supplementary features.

Build the first layer completely before starting the second, and the second before the third.

Within each layer, build the highest-risk items first.

The way you hand the plan to Claude Code (or any other AI) shapes the entire quality of the build - and the most common mistake is handing too much at once.

The correct approach is to load the full CLAUDE.md at the start of every session - this is the permanent context that does not change, covering the vision, tech stack, guardrails, and rules.

• Then, for each session, you bring in one specific backlog item.

Not the entire backlog.

Not a phase of features.

One clearly defined item that can be completed in a single session.

The instruction I used consistently in the Control Beacon build was a variation of this: "Read the CLAUDE.md, then read this backlog item. Before writing any code, ask me clarifying questions about anything that is not clear, then describe your implementation plan. Wait for my confirmation before proceeding."

That instruction does three things:

1. It ensures AI has the full planning context before starting work.
2. It forces a planning step before any code is written, which surfaces misunderstandings before they become implemented.
3. And it gives you a checkpoint to catch anything AI has misinterpreted before it becomes a session worth of work to undo.

The section-by-section approach also keeps sessions focused enough that context compression is less likely to cause problems.

A session that builds one clearly defined feature from a stable starting point is less likely to drift than a session that tries to build three loosely defined features in sequence.

The CLAUDE.md update at the end of each session keeps the starting point for the next session accurate.

The FRAMEWORK.md in the Control Beacon repository captures this approach as a reusable document - a platform-agnostic specification, built from the Control Beacon architecture, that Claude Code can load in a fresh session for a new product and use to scaffold the entire platform structure without needing to rebuild the infrastructure thinking from scratch.

The principle is that the planning documents you produce in one build compound in value across future builds, because the hard thinking is already done.

This course has produced one artifact from every lesson action.

By this point, those artifacts should form a complete planning layer. Before the first coding session starts, it is worth checking that each one exists.

From Stage 2: a vision document covering what the product does, who it is for, what it does not do, and one key decision AI must never revisit. An ICP summary of two sentences. A marketing site draft - at minimum a homepage hero and a pricing structure.

From Stage 3: a tech stack section with every tool, version, and constraint note. A written rationale for why each service was chosen over the alternative.

From Stage 4: an expense map with costs at zero, 100, and 1,000 users. A margin calculation at 50 and 200 customers. A financial assumptions section with target price and gross margin.

From Stage 5: security guardrails with standing orders for auth, payments, and data. Anti-hallucination and anti-assumption rules. Session discipline rules. Any mid-build plan corrections already documented.

From Stage 6: a QA plan with manual test cases for the most critical flow. Defined metrics with event names and properties. A staging release checklist. A production release protocol.

From Stage 7: a phased build backlog with dependencies noted. A sequenced order with highest-risk items first within each phase. A session instruction template.

All of this belongs in a single document: your CLAUDE.md. If you built it incrementally across the course, you already have most of it.

If you are starting to assemble it now, the CLAUDE.md Starter Template that ships with this course gives you the structure - fill in what you have produced across each stage and you have a complete, loadable planning document.

The test of whether it is ready: could you hand this file to a developer who has never seen your product and have them understand exactly what they are building, what constraints apply, and what must never change?

If the answer is yes, the plan is ready. If not, the gap is the last thing to close before building starts.

The first session of a well-planned build feels different from the first session of an unplanned one - and the difference is worth understanding so you recognise it when it happens.

In an unplanned build, the first session feels fast.

AI produces scaffolding quickly, makes visible progress, and the session ends with something that looks like a working product taking shape.

That feeling of speed is partly real and partly an illusion, because AI is filling in all the decisions you have not made yet with its own assumptions.

In a well-planned build, the first session is slower to start.

• AI reads the CLAUDE.md, asks clarifying questions about the backlog item, and describes its implementation plan before writing a line of code.
• Some of those clarifying questions will feel obvious - they may be questions about things you thought were clear but that AI needs confirmed in writing before proceeding.

That is the control layer working as intended. The slower start is the sign that AI is working from your decisions rather than its own.

What a successful first session produces is not impressive - it is correct.

1. The foundation is in place, the structure matches the architecture you planned, and the code reflects the constraints in your CLAUDE.md.
2. There are no clever shortcuts that will cause problems in session four.
3. There are no assumptions that will need to be unwound in session eight.

One thing I came to value during the Control Beacon build was an AI that pushed back.

When the CLAUDE.md was detailed enough and the guardrails were specific enough, AI would occasionally flag a tension between what I had asked for in a session and something in the planning documents - a security rule that conflicted with a suggested shortcut, an architectural decision that the current backlog item would violate.

Those moments were not interruptions to the build… they were the build working correctly.

The first session that ends with a committed, clean foundation - however modest - and a CLAUDE.md that accurately reflects what was built is a better outcome than a first session that ends with a large amount of impressive-looking code and an AI that made dozens of undocumented decisions to get there.