Build It Without Losing Control

The failures are not theoretical. They follow a consistent pattern that I have seen across builds and that research confirms.

The first category is architectural mismatch.

AI generates code that solves the immediate problem without accounting for how your existing modules connect.

During the Control Beacon build, I documented over 35 specific issues in the troubleshooting section of the instructions file.

Many of them followed the same pattern: code that worked in isolation, passed a surface-level review, and broke when it interacted with the rest of the system.

One example - a database migration file existed on disk but was never actually applied, causing a 500 error that only surfaced when a user tried to create a team. The AI had generated the migration correctly. Nobody verified it was executed.

The second category is silent security gaps.

AI-generated code is significantly more likely to introduce hardcoded credentials, missing authorization checks, and data exposure patterns. These do not fail tests. They pass code review. They sit in production until someone finds them.

The third category is dependency drift.

AI recommends packages automatically without verifying they are legitimate, maintained, or compatible with your pinned versions.

During Control Beacon, I pinned every critical dependency with version numbers and added a rule: if unsure whether a method exists in the pinned version, say so - do not guess.

Without that rule, the AI would have introduced version conflicts on every third session.

What makes all three categories difficult to manage is that the standard code review process was not designed for them.

Architectural mismatch, security patterns, and dependency compatibility are not things a reviewer catches by reading 200 lines of AI-generated code quickly.

They are things that surface over time - at integration, at scale, or when someone runs a security audit six months after the code was written.

Each of these categories shares one trait...

They are invisible at the point of creation and expensive at the point of discovery.

It is not.

Architecture requires holding two things in balance simultaneously: what needs to happen right now and what that decision costs six months from now.

AI optimizes for the immediate request... it does not independently evaluate whether a shortcut today will create three new problems in the next quarter.

When I planned Control Beacon, the ARCHITECTURE.md document was 2,750 lines.

It covered domain strategy, authentication design with three layers of role-based access, token strategy, payment flow architecture, GDPR compliance, infrastructure decisions, and a four-phase implementation plan with specific test criteria for each phase.

Every one of those decisions affected every other one:

1. The authentication model shaped the database schema.
2. The payment provider choice shaped the webhook architecture.
3. The multi-tenant isolation rules shaped every single database query across every application.

AI did not make those decisions. AI questioned them. The planning process involved instructing the AI to review the architectural plan and ask questions - not to start building.

That process surfaced gaps that would have become bugs.

But the decisions themselves required understanding the product direction, the business model, the team capacity, and the long-term maintenance cost of every choice.

What happens when AI makes those decisions instead is not a single dramatic failure - it is a gradual accumulation.

• Each session AI fills in an undocumented gap with whatever is most common or most convenient.
• By week three of a build, the product is shaped by dozens of implicit decisions that nobody made explicitly, nobody documented, and nobody can easily trace when something later breaks against one of them.

The teams that get this wrong treat AI as both architect and builder.

The teams that get it right treat AI as a builder that operates inside an architecture defined by a human who understands the full system.

First, the instructions file was built before any code existed.

876 lines covering architecture, tech stack, hard rules, security guardrails, and session protocols.

The AI reads this file at the start of every session - it does not start from zero. It starts from complete context.

Second, every task was scoped before the AI touched it.

Not "build the billing page" but "build the billing page using Paddle checkout overlay, with these specific plan tiers, these specific price IDs, polling /api/billing/status every 3 seconds for up to 30 seconds after checkout completes, with a full-page loading overlay showing processing, success, and timeout states."

The scope defines the boundaries, and the AI executes inside them.

Third, the AI was never left to run unsupervised.

Every output was reviewed against the architecture, tested against the existing stack, and validated before integration. This is not optional. AI output is raw material. The quality layer comes from the human.

Fourth, the instructions file was updated at the end of every session.

What was built, what decisions were made, what issues were discovered. The next session starts with a current picture. Without this, each session starts with a degraded version of the project state and the AI makes assumptions based on incomplete information.

This is what "execution engine" means operationally.

The AI does not decide what to build or how the pieces fit together - it builds what it is told to build, inside boundaries it is given, and a human verifies the result before it moves forward.

The speed comes from AI handling implementation.

The reliability comes from a human handling every decision that determines what gets implemented and whether what was produced is correct.

These are not process for the sake of process.

Each rule exists because the failure it prevents costs significantly more than the three seconds it takes the AI to check.

"Never answer state questions from memory - always read the relevant file first." This rule exists because AI context compresses over long sessions.

When asked what routes exist or what has been implemented, the AI reconstructs from degraded memory instead of reading the actual source file.

The result is confident, specific, wrong answers that lead to code written against a system state that does not exist. During Control Beacon, adding this single rule eliminated an entire category of session failures.

"Flag uncertainty - if you cannot point to a specific file and line confirming a claim, say so before stating it."

Without this rule, AI presents uncertain information as fact. A developer acts on it. The code ships.

Three sprints later someone discovers the assumption was wrong.

"No unnecessary additions - do not add features, refactor, or improve beyond what was requested." AI will proactively optimize, refactor, or add defensive code it thinks would be helpful.

Without this rule, a simple bug fix becomes a refactor that touches files unrelated to the original issue. Scope creep from AI is real and it happens in every session without an explicit boundary.

"Elaborate before implementing - always ask to clarify requirements before writing code."

The AI's instinct is to start building immediately. This rule forces a pause. It surfaces misunderstandings before they become code.

"Scope discipline - never fix unrelated issues in the same commit."

AI encounters something broken while working on a different task and fixes it in the same commit.

Now you have two unrelated changes bundled together. If either needs to be reverted, you cannot separate them. One commit, one purpose.

Every hard rule in the Control Beacon CLAUDE.md was added because the failure it prevents happened at least once.

The rules accumulate over the course of a build - you start with the minimum and add each new rule when a new failure mode appears.

After a full build, you have a set of rules that reflects the specific failure patterns of your codebase, your stack, and your team. That set carries into the next build and starts from a much higher baseline.

The instructions file needs security rules that the AI checks automatically, every session, without being reminded.

• General security documentation sits in your wiki and gets read once.
• The CLAUDE.md gets read at the start of every session.

That is the difference.

The Control Beacon CLAUDE.md has five categories of security guardrails:

Authentication rules: never implement custom auth logic, never create custom JWT handling, never store tokens in localStorage, never use getAccessToken() on the client side. Every file handling auth gets a comment marker: "AUTH-CRITICAL: Manual review required before deploy."

Payment rules: never process or store payment card data, never trust client-side subscription status, all webhook handlers must verify signatures and be idempotent. Every file handling payments gets: "PAYMENT-CRITICAL: Manual review required before deploy."

Data rules: PII lives only in the designated database, never log PII in application logs, never send user data to third-party analytics without consent. Every file handling personal data gets: "GDPR-CRITICAL: Manual review required before deploy."

Tenant isolation rules: every database query must include the organization filter, never use user-supplied IDs to look up resources without verifying ownership.

Deployment safety: never commit secrets to git, never push directly to main, never deploy auth or payment changes without running the full test suite.

The comment markers deserve specific attention. They exist because no set of rules guarantees that AI will follow all of them in every session.

• Context compresses.
• Rules that were followed correctly earlier in a session get missed later.

The comment markers are the second layer - a flag that tells a human reviewer to look at this file specifically before it ships, regardless of how confident AI was when it produced it. Rules govern what AI should do. Markers ensure a human checks what AI actually did.

These rules are not comprehensive security documentation.

They are the specific guardrails that prevent the most common and most expensive AI-generated security failures.

You already know the theory from Plan It Before You Build It:

• Context compresses as sessions run long,
• The end-of-session update keeps the instructions file current, one task per session prevents drift.

This lesson is about what that looks like when it goes wrong mid-build - because knowing the rules and catching the failure in real time are two different things.

Do you know what context degradation looks like during an active session? Early outputs are specific, architecturally aligned, and consistent with the guardrails. Then something shifts...

1. The AI writes a database query without the organization filter - a rule that was in the instructions file and was followed correctly an hour ago.
2. Or it recommends a package update without checking the pinned version constraint.
3. Or it reconstructs the state of a feature from memory instead of reading the file, and the reconstruction is slightly wrong.

None of this announces itself, and the output looks correct. It compiles. It is only when you compare it against the instructions file that you catch it.

During the Control Beacon build, I added a rule after catching this pattern twice: "If you feel uncertain about earlier context in this session, say so and suggest starting fresh rather than guessing." That rule changed the character of long sessions.

Instead of AI silently filling gaps with plausible content, it flagged uncertainty - which gave me the checkpoint to verify or start fresh.

The end-of-session update matters because of what happens without it.

A session that builds something without updating the instructions file leaves the next session starting from a picture that is already wrong. The AI reads the old state and makes decisions based on something that no longer exists.

The Control Beacon CLAUDE.md is explicit on this: partial updates cause regressions in the next session. Not sometimes - consistently.

Before closing any session: update the instructions file with what was built, what decisions were made, and what issues surfaced.

Update the backlog. Commit and push. The next session loads a current picture and starts from there.

In most cases this happens because the task was not scoped tightly enough.

AI fills gaps. If the scope has gaps, the AI fills them with assumptions. Those assumptions compound.

A weak scope looks like: "Build the billing page."

A strong scope looks like: "Build the billing page at /billing. Use Paddle checkout overlay, not redirect. Display three plan cards - Pro at $19/seat/month, Team at $39/seat/month, Enterprise as contact us. Pro and Team cards open Paddle overlay with customData containing orgId and plan name. After checkout completes, poll /api/billing/status every 3 seconds for up to 30 seconds. Show a full-page loading overlay with three states: processing spinner, success checkmark, and timeout message. On success, auto-refresh the page via router.refresh()."

The difference is not verbosity. It is specificity. The strong scope leaves nothing for the AI to decide on its own.

Every UI element, every behavior, every edge case is defined before a line of code is written.

During Control Beacon, every task in the backlog followed this pattern. The instructions file had an explicit rule: "Elaborate before implementing - always ask to clarify requirements before writing code."

If I gave the AI a scope that was too loose, it would ask questions before building. Those questions caught ambiguity that would have otherwise become wrong code.

What loose scoping produces specifically is not usually something obviously wrong:

• The billing page gets built. It looks correct.
• The Paddle overlay opens. The plan cards display.

But the polling interval is 5 seconds instead of 3, the timeout state shows a generic error instead of the specific message you had in mind, and the success state reloads the whole page instead of calling router.refresh().

None of those are bugs in the traditional sense. They are gaps that the AI filled with whatever was most common. Each one requires a correction session to undo.

The rule of thumb: if two developers could reasonably interpret your task description differently, the AI will pick one interpretation and build it without telling you. Scope it tightly enough that only one interpretation is possible.

Session structure prevents this. Not rules about what AI should do - but a workflow that physically limits where it can go.

My Control Beacon workflow has four stages per session.

Stage one: the AI reads the instructions file and the current backlog. It confirms what it understands about the current state. If anything is unclear, it asks before proceeding. This takes two minutes and prevents the entire session from building on a wrong assumption.

Stage two: the task scope is confirmed. The AI repeats back what it is going to build, including what it is NOT going to build. This is the boundary-setting step. If the AI's understanding does not match your intent, you correct it now - not after 200 lines of code exist.

Stage three: the AI builds. During this phase, the hard rules govern behavior. No unnecessary additions. No scope creep. No fixing unrelated issues. If the AI encounters something unexpected, it flags it and asks rather than making a judgment call.

Stage four: end-of-session update. The instructions file is updated with what was built, what was decided, and what issues surfaced. The backlog is updated. Changes are committed and pushed.

One critical structural rule: one task per session.

Mixing multiple tasks in a single session is where drift happens.

• The AI completes task one, carries residual context into task two, and makes decisions on task two that are influenced by the work it just did on task one.

Separate sessions, separate context, separate outcomes.

The stage two step - AI repeating back what it is going to build and what it is not - is the one most teams skip.

It feels redundant when the scope was already written down. It is not. The gap between what you wrote in the scope and what the AI understood from reading it is where almost all mid-session drift originates.

Thirty seconds to confirm the AI's understanding before it builds anything saves sessions of correction after.

Stop and update the plan. Always.

A planning document that no longer reflects the build is not a planning document - it is a source of future hallucinations.

Every session that loads it will make decisions based on architecture that no longer exists.

This happened multiple times during my Control Beacon build.

Early in the pricing migration, the billing model was structured around per-seat limits. Partway through the build it became clear that org-wide usage pools - shared across all members rather than per seat - were the right model for the product.

That was not a small change. It touched the database schema, the entitlement checks, the usage tracking logic, and the pricing page.

Stopping to update the architecture document before continuing felt like lost time. Continuing without updating it would have meant building the rest of the platform on top of a documented model that was no longer accurate.

The update protocol for a mid-build architecture change has three steps:

First, stop the coding session. Do not continue building on an architectural assumption you are about to change. Everything built after the decision point will need to be revisited anyway.

Second, update the instructions file and any relevant planning documents to reflect the new decision. Be specific: what changed, why, and what the new rule is. If the change has downstream effects - other parts of the system that will need to be updated - document those too, even if the work is not happening yet.

Third, review what was already built that depends on the changed decision. Not to fix it immediately, but to add it to the backlog as a known item. Undocumented debt is the dangerous kind.

The discipline here is the same as the end-of-session update discipline from Lesson 2.4: the instructions file must reflect reality.

When the build and the document diverge, the document wins - update it until they match again.

Four questions close the gap.

Question one: has this been tested against the existing architecture, not just in isolation?

AI-generated code solves the immediate problem. It does not automatically account for how your existing modules connect, how your data flows, or what your stack handles at scale.

The Control Beacon CLAUDE.md that I've built includes a platform compliance review:

1. No direct database access to other app databases,
2. Central API calls use the typed client not raw fetch,
3. Authentication uses SDK methods not custom logic,
4. UI components imported from the shared package.

Question two: has the security review specifically checked for AI-generated patterns?

Hardcoded credentials, missing authorization checks, data in error responses, prompt injection vulnerabilities, dependencies that were hallucinated or typosquatted.

These are consistent, documented patterns in AI output. A review that does not check for them is not a security review.

Question three: is the instructions file current?

If the instructions file was not updated since the last session, the AI was operating without current context. The code it produced may not account for recent decisions.

An outdated instructions file is the single most common source of AI-generated code that does not fit the system.

Question four: have dependencies been verified? Is this a real, maintained package? Does it have known vulnerabilities? Is it licensed compatibly?

This check takes two minutes and catches a category of problem that has caused production incidents.

This is the pattern when these questions are not asked consistently:

• code passes review,
• ships,
• and surfaces problems two or three sprints later when a new feature touches the module that was reviewed without them.

By then, identifying the root cause requires understanding a decision made weeks ago by someone who is already three features ahead and does not remember the details.

The four questions are not overhead. They are the mechanism that keeps future sprints from paying for what the current one skipped.

"Has this passed all our processes?" replaces "does this work?" as the question that matters.

Automated tests verify that the code does what it was programmed to do. Manual validation verifies that the code does what the user needs it to do in the real environment.

Both are required. Neither replaces the other.

During the Control Beacon build, every phase ended with specific manual test criteria.

After Phase 1: sign up, log in, verify SSO works across the hub and all applications, verify role enforcement.

After Phase 2: verify trial access, verify entitlement gating redirects correctly, verify role-based UI.

After Phase 3: complete a full purchase flow end-to-end from Paddle checkout through webhook through entitlement creation through app access.

After Phase 4: the full lifecycle - signup, trial, expiry, upgrade, payment, access, cancel, revoke, data deletion.

These are not edge cases. They are the core user workflows tested against the real production environment.

AI-generated code that passes unit tests can still break at the integration points - where authentication meets provisioning, where payment webhooks meet entitlement creation, where session management meets multi-app SSO.

A manual test case has three parts:

1. Starting state,
2. Action,
3. Expected outcome.

Here is an example from the Control Beacon billing flow:

• Starting state: Trial user, 14 days elapsed, no payment method on file, logged into the hub.
• Action: Navigate to /billing. Select the Pro plan. Complete Paddle checkout with a test card. Wait for the success state.
• Expected outcome: Hub billing page refreshes automatically, plan status shows "Pro", all apps show as accessible, Paddle subscription created in sandbox dashboard, webhook received and logged in Central API.

That is one test case. It covers five systems - the billing page, Paddle checkout, the webhook handler, the Central API, and the entitlement layer - and it is the kind of test that only exists when a human walks through it in the real environment.

No unit test covers the chain between them.

The launch checklist in the Control Beacon framework has nine steps, and "automated tests pass" is only the first one.

The remaining eight involve testing each app individually, confirming performance, confirming UI quality on mobile, verifying pricing consistency across marketing and billing pages, testing the full end-to-end lifecycle, and verifying DNS and SSL.

Automated tests catch regressions. Manual validation catches the failures that no test was written for - because they only exist at the intersection of multiple systems.

AI output quality within a session is not constant. It degrades. The question is - will you notice that before the degraded output enters your codebase?

The degradation follows a pattern:

Early in a session, when context is fresh and the instructions file is fully loaded, outputs are specific and architecturally aligned.

An hour in, when the context window is filling and earlier instructions are being compressed, something shifts.

A query gets written without the organization filter that the instructions file explicitly requires and that was followed correctly in the same session thirty minutes earlier.

A package recommendation appears that conflicts with a pinned version.

A route handler gets built without the auth check that every other handler in the session included.

None of this is flagged. The output continues with the same structure, the same apparent confidence. It compiles. It looks right.

During the Control Beacon build, I caught one of these mid-session when reviewing a database query that the AI had just generated...

The organization filter was missing - a rule that was not just in the instructions file but had been applied correctly in the previous three queries in the same session.

When I flagged it, the AI acknowledged the gap and corrected it. But the more important question was: had it happened before in this session without me catching it?

That question led to a specific rule being added to the CLAUDE.md: "After generating any database query, verify the organization filter is present before moving to the next task."

Not a general reminder - a specific, per-output check for the failure mode that had just appeared.

The broader principle: degradation is caught by checking outputs against specific rules, not by trusting that the session is still on track.

The further into a session you are, the more actively you need to compare what AI just produced against what the instructions file requires.

When a rule is violated that was followed correctly earlier - stop, update the file, start fresh.

That observation is correct. The conclusion most people draw from it is wrong.

A disciplined AI session includes (and 90% of this can be automated properly):

1. Reading the instructions file,
2. Confirming the task scope,
3. Building within boundaries,
4. Running self-verification checks,
5. Reviewing output against the architecture,
6. Updating the instructions file,
7. Committing with documentation.

A session without discipline includes: prompting, accepting, committing.

The second approach produces more commits per hour. The first approach produces more reliable code per sprint.

The Control Beacon instructions file that I've built includes explicit rules that slow individual sessions down.

• "Elaborate before implementing."
• "Read before stating."
• "Re-read before editing."
• "Flag uncertainty."

Each rule adds seconds to minutes to a session. Each rule prevents hours to days of rework.

The developer who reads the database schema before writing a query takes 30 seconds longer than the developer who lets the AI guess the column names.

But the developer who guesses spends 45 minutes debugging a query that references a column that does not exist - in a session where the AI confidently stated the column was there.

The challenge is that disciplined and undisciplined sessions look similar from the outside until something breaks.

• Both produce commits.
• Both show activity.

The difference only becomes visible in the rework column - which most teams do not track separately from forward progress.

That is the measurement gap that lets undisciplined velocity look like productivity for weeks longer than it should.

The metric to watch is not output per session. It is rework per sprint.

A team where disciplined sessions produce less output but zero rework will outpace a team where fast sessions produce more output and recurring integration failures.

If a developer on your team is following proper discipline and appears slower, that is the developer whose code you can trust in production. Speed without discipline is debt with a delayed invoice.

The degradation follows a predictable pattern:

Early in a session, responses are specific, well-structured, and closely aligned with the instructions file.

As the session runs longer, responses become subtly less specific.

Edge cases that were handled earlier get missed. Code that was architecturally aligned at the start drifts toward generic patterns.

The AI does not announce this shift - it continues producing output with the same apparent confidence.

The signals to watch for:

1. Responses that are slightly less specific than earlier outputs.
2. Code that handles the immediate requirement but ignores constraints from the instructions file.
3. Documentation that restates the question rather than answering it.
4. The AI filling gaps with plausible content instead of asking for clarification.

A concrete example of what catching it looks like: during the Control Beacon build, late in a session building the team management flow, the AI generated a database query without the organization filter.

Earlier in the same session, the same type of query had been written correctly - and, the rule was in the instructions file.

It had been followed. Then it was not. The output looked correct. The only reason it was caught was a habit of comparing each query against the tenant isolation rule before accepting it - not because anything looked wrong on the surface.

The protocol when you notice degradation:

Step one: stop the session. Do not continue building on degraded output. Everything produced after the quality drop carries compounding risk.

Step two: update the instructions file with what was built in the current session. Mark anything produced after the quality drop as requiring full review.

Step three: start a new session. The new session reloads the instructions file fresh, with full context, and no accumulated compression from the previous session.

Step four: review the output from the degraded portion of the previous session against the instructions file and architectural standards before integrating any of it.

The Control Beacon CLAUDE.md includes two rules that address this directly:

• The AI must proactively flag when context compression risk is high.
• It must suggest starting a new session rather than guessing when it feels uncertain about earlier context.

These rules exist because the failure they prevent - silent drift compounding across dozens of outputs - is one of the most expensive patterns in AI-assisted development.

It is the single highest-leverage activity in your entire AI-assisted development workflow.

The Control Beacon CLAUDE.md has an explicit update protocol:

When the user asks to "update CLAUDE.md and memory," this means a COMPLETE update - not just the items worked on in this session.

The protocol has six steps:

1. Update implementation status,
2. Update environment variables,
3. Update troubleshooting,
4. Update the backlog,
5. Update any other reference documents, and commit.

The critical instruction: "Do NOT assume an item is captured elsewhere. If in doubt, write it down. Omissions here cause the next session to hallucinate, make wrong assumptions, or redo completed work."

That last sentence is why this matters.

An instructions file that is 80% current is an instructions file that is 20% wrong. The AI reads it as 100% accurate.

It makes decisions based on the 20% that is no longer true. Those decisions produce code that does not fit the current system. The developer does not notice until integration.

What a stale instructions file looks like in practice:

1. A session opens,
2. The AI reads the file,
3. Sees a backlog item marked as not yet started - but that item was actually completed two sessions ago and just never updated.
4. The AI starts building it again from scratch.
5. Or it reads an environment variable listed as pending setup that was configured last week, and spends the first ten minutes of the session asking questions about something that is already resolved.

These are not catastrophic failures. They are invisible tax on every session that runs from a file that does not reflect the build.

Over the course of the Control Beacon build, the instructions file was updated at the end of every session.

It grew from roughly 200 lines to 876 lines. That growth represents 35+ troubleshooting entries, dozens of architectural decisions, security discoveries, deployment gotchas, and implementation details that would have been lost without the update protocol.

The file is not documentation in the traditional sense.

It is operational context that makes every future AI session productive from the first prompt.

Without it, each session spends its first 10-15 minutes reconstructing context that could have been loaded instantly from a current file.

It does not have to. The instructions file you maintained across this build is not just a project document... it is the raw material for a reusable framework that makes every future build faster.

After Control Beacon reached production, I extracted the entire platform architecture into a standalone document called FRAMEWORK.md. It is 1,747 lines.

It covers the full monorepo structure, shared packages, the Central API backbone, an 11-file app blueprint that every new application copies, pricing and billing integration, security patterns, an external services setup guide, Claude Code working rules, and a launch checklist.

The framework uses placeholders - {platform}, {domain}, {app}, {prefix}, {port} - so it applies to any product, not just Control Beacon.

Load it into a new Claude Code session, specify your product name and applications, and AI scaffolds the entire platform using proven, tested patterns rather than starting from scratch and guessing.

This is not a boilerplate generator.

It is a documented set of architectural decisions with the reasoning behind each one.

• Why Auth0 over alternatives.
• Why Paddle over Stripe.
• Why per-app databases instead of a shared schema.
• Why the lazy-init Proxy pattern for Auth0 and database clients.
• Why webhook handlers must never throw.

Every pattern includes the failure it prevents.

The extraction process is simple. Go through your instructions file and identify every decision that is not product-specific:

1. Stack choices,
2. Service selections and the reasoning behind them,
3. Security rules that apply regardless of what you are building,
4. Deployment gotchas that will be true on the next project too.

Those items belong in a framework document. The next build loads it as a starting point. The project-specific instructions file adds only what is new.

The second build inherits hundreds of hours of debugging, architectural iteration, and production validation. It does not start from zero. It starts from proven.