18M Tokens to Fix Vibecoding Debt - And How to Avoid It

Fazm Team··2 min read

18M Tokens to Fix Vibecoding Debt

Someone spent 18 million tokens on a rebrand. That sounds wild, but I totally believe it. I had a similar experience building a macOS desktop app. The real cost is not the AI-generated code itself - it is letting AI write without specs.

How Vibecoding Debt Accumulates

When you prompt an AI to "build a settings page," it makes dozens of micro-decisions. Where to store preferences. How to structure the UI hierarchy. What validation to apply. Whether to use local storage or a database. Each decision is reasonable in isolation, but they compound into an architecture that nobody designed.

Three months later, you need to refactor the settings system. The AI made choices you never reviewed, and now those choices are load-bearing. Changing one thing breaks five others because the implicit architecture has no documentation and no tests.

That is vibecoding debt. It is not bad code - it is unreviewed decisions.

The System That Prevents It

Before generating any code, I write a one-page spec. Not a formal document - just bullet points covering: what this feature does, what it should not do, what data it touches, and how it connects to existing systems.

The spec becomes part of the prompt context. The AI generates code that fits within the boundaries I defined instead of inventing its own boundaries. When I review the output, I review it against the spec, not just against "does it look right."

The CLAUDE.md Approach

I keep a CLAUDE.md file in every project root with architectural decisions, naming conventions, and constraints. Every AI agent that touches the codebase reads this file first. It acts as a persistent spec that prevents drift across sessions and across agents.

This takes maybe ten minutes per feature to set up. Compare that to 18 million tokens of cleanup.

The Math

Writing specs upfront costs roughly 5% more time per feature. Not writing specs costs 10-50x more tokens when you eventually need to fix the accumulated drift. The math is not close.

Fazm is an open source macOS AI agent. Open source on GitHub.

More on This Topic

Related Posts