# Rescuing a Claude Code & Cursor Codebase: Extracting a 3,000-Line God-Component into a Vibe-Safe Handover

Canonical URL: https://aquarel.io/teardowns/claude-code-cursor-spaghetti-to-vibe-safe-handover
Author: Dositej Grbović (Founder & Principal Engineer)
Type: stack-teardown | Published: 2026-02-08 | Updated: 2026-02-20
Stack: Claude Code, Cursor IDE, CLAUDE.md & AGENTS.md, React & Next.js, TypeScript Refactoring

> 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-to-Fix Diagnostic Matrix

| Symptom | Root Technical Cause | 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 Guardrail: `CLAUDE.md`

Copy-pasteable Production CLAUDE.md / AGENTS.md Guardrail Template (Aquarel Vibe-Safe Handover).

```markdown
# 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//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.
```

## Diagnostic Walkthrough

## 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 `useEffect` hook into a single 3,000-line `dashboard/page.tsx` file with `as any` casts and zero architectural boundaries.
- **Surgical Engineering Fix**: Extract a 4-layer architecture—Frozen Core Auth/Billing (`src/server/billing/*`), typed Domain Services (`src/features//service.ts`), focused UI components (<250 lines), and a root `CLAUDE.md` / `AGENTS.md` guardrail 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.

## Related Services & Proof Assets

- [Service: claude-cursor-replit-rescue](https://aquarel.io/services/claude-cursor-replit-rescue)
- [Service: vibe-code-app-rescue](https://aquarel.io/services/vibe-code-app-rescue)
- [Service: saas-scaling-and-refactoring](https://aquarel.io/services/saas-scaling-and-refactoring)
- [Case Study: b2b-workspace-php-angular-websocket-modernization](https://aquarel.io/case-studies/b2b-workspace-php-angular-websocket-modernization)

## Frequently Asked Questions

### Can I copy and paste this CLAUDE.md template directly into my project?

Yes! Placing this `CLAUDE.md` (and mirroring it as `AGENTS.md` or `.cursorrules`) in your repository root immediately gives Claude Code and Cursor explicit boundaries on file size, RLS safety, and frozen billing modules.

### Why isn't adding CLAUDE.md alone enough if my app already has a 3,000-line file?

Instruction files prevent future drift, but if your existing codebase already mixes UI, auth, and billing inside a 3,000-line monolith, the AI still has to edit that dangerous file. We first split the monolith into clean modules, then lock those modules with CLAUDE.md.

### How long does it take Aquarel to untangle a Claude Code or Cursor codebase?

Most AI monolith extractions and Vibe-Safe Handover rescues complete in a fixed-scope 1 to 2 week Rescue Sprint ($1,000–$1,500+) following our free 48-hour Codebase Audit.

## Need Surgical Help With This Stack?

- [Book Free 20-Min Triage Call or Send Broken App Async](https://aquarel.io/triage?stack=claude,cursor-replit)