What is Vibe Coding Technical Debt: A Guide for Vibe Coders
When code vibes, debt accrues. If you’ve ever spun up a shiny MVP in a weekend using Cursor/Lovable/bolt.new and woke up a month later wondering why adding a simple button requires spelunking through six files and three AI prompts—welcome to vibe coding technical debt.
This post unpacks what technical debt looks like in the vibe‑coding world, why it sneaks up faster than you think, and how to avoid (or pay down) the mess without killing your momentum. Grab coffee; we’ll keep it crisp, practical, and a little cheeky.
What is Technical Debt in Vibe Coding?
Traditional technical debt is the trade‑off of speed now for complexity later. In vibe coding—where AI copilots scaffold architecture, generate modules, and “just‑ship‑it” is the ethos—debt compounds faster because:
AI accelerates scaffolding: You can birth an entire codebase before you’ve named the repo.
Patterns drift: Each new prompt can introduce a different architecture or styling system.
Hidden decisions: Key design choices live in chat logs, not documents.
Lucky paths: Everything works until it doesn’t, and then you don’t know why it ever did.
Think of vibe coding as compound interest: your first week feels magical; week three feels like a collections agent calling about your monorepo.
The Greatest Hits: Common Vibe Coding Debts
Below are recurring debt patterns unique to or amplified by vibe coding. For each, you’ll see what it is, the symptoms, and how to avoid/fix it.
1) Prompt Rot
What it is: Your original prompts (and assumptions) age out as the project evolves. You reuse old prompts and get subtly wrong output.
Symptoms: New components don’t match earlier conventions; AI outputs use different folder names, route patterns, or state managers.
Avoid: Maintain a living System Prompt (project brief) at the repo root. Include the tech stack, naming conventions, folder structure, style tokens, API conventions, and “non‑negotiables.” Pin it in your IDE.
Pay down: Refactor recent divergences to match the system prompt; re‑generate your “golden prompts” and store them in /docs/prompts with version tags.
2) Tool Drift
What it is: Jumping between AI tools or model versions that generate incompatible patterns.
Symptoms: Detect mismatched ESLint/Prettier configs, two UI kits, or both Zod and Yup validations.
Avoid: Establish a Toolchain Lockfile (just a doc) listing IDE, model, UI kit, state manager, router, test runner, and CSS strategy. Freeze for the sprint.
Pay down: Consolidate duplications (one validator, one UI kit). Add rules to lint for banned imports and conflicting packages.
3) Scaffolding Sprawl
What it is: Multiple generated starters layered together: app/ and src/, duplicate env.ts, conflicting .env.example.
Symptoms: Two vite.config.* files, pages/ and app/ routing, dead directories.
Avoid: Adopt a “Scaffold Once” rule. If you need a second scaffold, start a clean branch, extract only what’s missing, and merge deliberately.
Pay down: Run a directory audit. Delete dead roots. Move to a single router and config. Update the System Prompt with the final structure.
4) Schema Entropy
What it is: Database shape changes via ad‑hoc AI suggestions with no migration log.
Symptoms: Fields like user_id, uid and ownerID coexist; seed scripts fail; prod and dev schemas drift.
Avoid: All schema changes must go through migrations (Prisma/Drizzle/Flyway). Write an ADR (Architecture Decision Record) for any breaking change.
Pay down: Create baseline migrations from the current prod schema; backfill a minimal ADR history; add CI checks that fail on manual schema edits.
5) Styling Doppelgängers
What it is: Multiple styling systems (Tailwind + CSS Modules + inline) and two design languages (Material + shadcn/ui) fighting for custody.
Symptoms: Inconsistent spacing, color tokens, and radii; components impossible to theme.
Avoid: Choose one design system and one styling strategy. Publish design tokens (colors, space, radius, shadow) and enforce with ESLint and codegen.
Pay down: Create a ui/ library of normalized components; progressively migrate pages; add codemods to replace old patterns.
6) API Shape Drift
What it is: Endpoints generated on the fly with inconsistent naming and contracts.
Symptoms: GET /api/user returns {users: []} in one place and {data: []} elsewhere; 200/201/204 semantics are random.
Avoid: Maintain an OpenAPI/JSON Schema spec. Generate server stubs and client types from the spec.
Pay down: Document actual current responses; refactor endpoints behind a compatibility layer; ship a v1 stable contract.
7) Auth Spaghetti
What it is: A patchwork of magic links, OAuth, and role checks sprinkled everywhere.
Symptoms: Conditionals like if (user && user.role !== 'admin') across the UI; confusion between server and client auth.
Avoid: Centralize auth in a server‑first guard (middleware). Define explicit roles/permissions. Export helpers; ban inline role checks in components.
Pay down: Move checks to middleware/API layer; add integration tests for critical paths.
8) Test Brittleness by Autogen
What it is: AI‑generated tests that mirror implementation details rather than behavior.
Symptoms: One refactor breaks 20 tests; tiny layout changes cause snapshot avalanches.
Avoid: Write behavioral tests (user flows, API contracts). Prefer less snapshot, more semantics.
Pay down: Replace fragile tests with higher‑level flows. Add contract tests against the OpenAPI spec.
9) Context‑Window Amnesia
What it is: The AI forgets earlier decisions because your prompt exceeds its context window.
Symptoms: New code ignores conventions, re‑introduces older patterns, or invents names.
Avoid: Keep a North Star README and reference it in every prompt. Chunk work: “Generate this component per README, not a new app.”
Pay down: Extract conventions from chat history into the README/system prompt; add one‑page “Architecture in 15 bullets.”
10) Silent TODO Debt
What it is: AI inserts TODOs (“wire up auth here”) that never get surfaced.
Symptoms: Hidden traps that only appear in production.
Avoid: Enforce TODO linting (fail CI on untracked TODOs). Open issues for each TODO with acceptance criteria.
Pay down: Triage TODOs weekly. Close, schedule, or implement.
A Simple Operating Model to Avoid Debt (Without Killing Vibes)
You don’t need heavyweight processes. You need lightweight guardrails that scale as you ship.
1) The North Star README (1 page)
Problem, audience, elevator pitch
Tech stack (locked for this sprint)
Folder structure and naming conventions
Design tokens and component library
API contract source of truth (OpenAPI link)
Non‑negotiables (auth pattern, validation, router)
Treat this as the single most important artifact. Every prompt starts with: “Follow /README and /docs/prompts/system.md.”
2) System Prompt & Golden Prompts
- /docs/prompts/system.md: Guidelines the AI must follow
- /docs/prompts/generate_component.md: How to request a component
- /docs/prompts/refactor.md: How to safely refactor without pattern drift
Tip: Version them (v0.1, v0.2). When conventions change, update the prompts first, then code.
3) Weekly Rituals (45 minutes total)
Monday (15m): Lock the toolchain and goals for the week
Wednesday (15m): Debt surfacing stand‑down—scan TODOs, flaky tests, schema diffs
Friday (15m): Refactor tiny; merge small PRs; release notes
4) CI Guardrails (Set and forget)
Lint & format on commit
Typecheck must pass
Fail on un‑migrated schema changes
Fail on banned imports (duplicate UI kits/validators)
Test minimums: run flows, not just snapshots
5) ADRs That Don’t Suck (3 bullets max)
Decision: e.g., “Move from Fetch to tRPC for type‑safe calls”
Why now: impact, trade‑offs
Migration plan: steps, owners, rollback
6) “Scaffold Once” Rule
If you must regenerate, do it in a throwaway branch, copy the minimal deltas, and document the rationale.
7) Design Token First
Publish tokens (/styles/tokens.ts) and derive components from them. Guard against introducing second systems.
Paying Down Existing Debt: A 5‑Day Sprint
If you already feel the interest piling up, run this quick‑fix sprint:
Day 1 — Inventory & Freeze
Freeze toolchain for 7 days
Generate a Repo Health Report: duplicate deps, multiple UI kits, dead folders, TODO count
Promote a North Star README
Day 2 — Structure & Styles
Collapse to a single router and directory layout
Publish design tokens; normalize the top 5 shared components
Day 3 — Data & API Contracts
Snapshot current DB; create baseline migrations
Write (or extract) OpenAPI schema from live endpoints; scaffold client types
Day 4 — Auth & Permissions
Centralize guards (middleware/server)
Replace inline role checks with helpers
Day 5 — Tests & Prompts
Replace brittle snapshots with 3–5 happy‑path flow tests
Publish System Prompt + Golden Prompts; add to PR template
Ship a minor release with clear changelog and debt items converted into issues with owners.
Metrics That Actually Matter
Lead Time for Change: PR open → merge. If it’s creeping, debt is winning.
Schema Change Recovery Time: Minutes to generate and apply a migration across envs.
Contract Stability: Breaking changes per release (aim: near‑zero post‑v1).
Prompt Reuse Rate:/docs/prompts/ vs ad‑hoc.of prompts sourced from
Duplicate Package Count: Keep at 0 (no Yup+Zod, no Tailwind+CSS‑in‑JS unless deliberate).
Use these as scoreboard, not shame board.
Real‑World Anti‑Patterns (and Better Moves)
Bad: “Add Stripe quickly” → copy‑paste 3 different tutorials.
Better: One integration guide + ADR; test sandbox → live with a toggle.
Bad: “Just one new model” → inline SQL in three places.
Better: Migration + repository pattern; types derived from schema.
Bad: “Small styling tweak” → introduce second UI kit via AI suggestion.
Better: Extend the existing component; if blocked, add token and update the shared component.
Bad: “AI says use Zustand here, Redux there.”
Better: Choose one state manager; document when to use server vs client state.
A Lightweight PR Template for Vibe Projects
### What & Why
Short summary and user impact.
### Linked Docs
- ADR / Issue / OpenAPI diff
### Checkboxes
- [ ] Matches North Star README conventions
- [ ] No new UI kit or validator introduced
- [ ] Schema change has a migration
- [ ] Tests cover the user flow (not just snapshots)
- [ ] Prompts updated if conventions changedCopy this into .github/pull_request_template.md. It prevents 80% of vibe debt at near‑zero cost.
Conclusion: Keep the Vibes, Cut the Interest
Vibe coding is a superpower. You can go from idea to working prototype before lunch. The catch is that unbounded generation equals unbounded entropy. Technical debt isn’t failure—it’s the bill for speed. Pay it intentionally.
If you:
Keep a North Star README and System Prompt,
Lock your toolchain per sprint,
Enforce contracts (DB migrations + OpenAPI),
Consolidate design tokens and a single UI library,
And use CI guardrails with a tiny PR checklist
—you’ll ship fast and sleep well. Your code will still vibe, but now it’ll groove on‑tempo instead of free‑jazzing your deadlines.
Keep shipping. Keep the vibes. Kill the interest.