Rescuing a Claude Code & Cursor Codebase: Extracting a 3,000-Line God-Component into a Vibe-Safe Handover
When AI coding assistants (Claude Code, Cursor, Lovable, Replit) pass ~80% completion, they frequently collapse state, database mutations, and UI into 3,000-line monolithic files that break on every subsequent prompt. The fix is a two-step surgical extraction: decouple auth/billing into read-only service boundaries and enforce a root CLAUDE.md / AGENTS.md architecture contract.
Symptom → Root Technical Cause → Surgical Engineering Fix
| What You Experience | Why the AI Agent / App Is Stuck | Aquarel's Surgical Engineering Fix |
|---|---|---|
| Asking Claude Code or Cursor to change a button or table column breaks authentication or Stripe billing | UI layout, 25+ `useState` / `useEffect` hooks, and raw database mutations live inside one 3,000-line `dashboard/page.tsx` file. | Decompose the monolith into focused domain feature folders (<250 lines per file) with isolated service modules. |
| AI agent creates duplicate helper files (`auth2.ts`, `supabaseNew.ts`) and conflicting database schemas | Zero repository-level architectural map telling the LLM where canonical services, types, and migrations reside. | Consolidate duplicate utilities and commit a root `CLAUDE.md` and `AGENTS.md` architecture specification. |
| Fixing one TypeScript error triggers a cascade of `any` casts that crash at runtime | AI silenced compiler errors with `as any` and `@ts-ignore` instead of aligning database and API response types. | Generate canonical database types and enforce strict Zod/TypeScript contracts at every API boundary. |
# Copy-Pasteable Production CLAUDE.md / AGENTS.md Guardrail Excerpt (Aquarel Vibe-Safe Handover)
## 1. Frozen Core Boundaries (DO NOT MODIFY WITHOUT EXPLICIT HUMAN PR APPROVAL)
- `src/server/billing/stripe-webhook.ts`: Idempotent signature-verified Stripe handler. Never inline billing mutations in UI components.
- `supabase/migrations/*`: Never disable Row-Level Security (RLS) or expose `SUPABASE_SERVICE_ROLE_KEY` to `NEXT_PUBLIC_*`.
## 2. Module Size & State Rules
- Maximum component file length: 250 lines. Extract data fetching and mutations into `src/features/<domain>/service.ts`.
- Never use `as any` or `@ts-ignore` to silence type mismatches; import canonical types from `src/types/database.ts`.
## 3. Pre-Commit Verification Contract
- Run `npm test && npm run build` before completing any task. All changes must ship on a feature branch PR.Breaking Out of the 3,000-Line AI Monolith Trap
When non-technical founders build with Claude Code, Cursor, or Replit Agent, the fastest early workflow is prompting inside a single page file. By week three, src/app/dashboard/page.tsx is 2,800+ lines long, holds 30 state hooks, queries Supabase directly, and handles Stripe upgrades inline.
Broken AI Pattern vs. Surgical Engineering Fix
- Broken AI Pattern: Allowing Claude Code or Cursor to append every new feature, modal, Supabase query, and
useEffecthook into a single 3,000-linedashboard/page.tsxfile withas anycasts and zero architectural boundaries. - Surgical Engineering Fix: Extract a 4-layer architecture—Frozen Core Auth/Billing (
src/server/billing/*), typed Domain Services (src/features/<domain>/service.ts), focused UI components (<250 lines), and a rootCLAUDE.md/AGENTS.mdguardrail file that blocks regressions.
Our surgical extraction pattern separates that god-component into four clean layers—Read-Only Core Auth/Billing, Domain Services, Feature UI Components (<250 lines), and a root CLAUDE.md / AGENTS.md contract—so you can resume prompting with zero regression anxiety.