The problem nobody talks about

AI will write you working code almost instantly. It will also write you unmaintainable, inconsistent, security-naive code just as fast — and it will do so cheerfully, confidently, and without a word of warning.

The problem isn't that AI can't write clean code. It can. The problem is that it won't unless you build a system that makes it.

Here's what happens without a system: you start a session, describe what you want, get code that works. Next session, different conventions. Third session, the AI sees the patterns already in the codebase and mirrors them — including the bad ones. By month three, you have a codebase that looks like it was written by six different developers with six different opinions, because effectively it was.

This isn't a criticism of AI. It's a description of how AI works. It has no persistent memory. It optimises for satisfying the current request. It defers to whatever it sees in context. The fix is a system.

Why AI code quality degrades over time

Three forces work against you:

None of this is malicious. It's the default behaviour of a tool optimising for the wrong thing. The system below changes what it optimises for.

The methodology: four steps before you write code

The CLAUDE.md file

CLAUDE.md is the most important file in your repository. It lives at the repo root. Every AI session reads it before doing anything. It is how you get consistent behaviour from a tool that has no memory.

A good CLAUDE.md contains:

What the project is — one table, each module, who uses it, what it does. Two minutes to read, eliminates ten minutes of context-setting per session.

Import rules — where things live, and what is allowed to import from what. This is the rule that makes modularity actually work:

# The rule that makes plug-and-play possible
packages/shared/   ← imports from nowhere else
apps/client/       ← imports from shared only
apps/api/          ← imports from shared only

# Apps never import from each other. Ever.
# If app A needs something from app B, it belongs in shared.

The explicit prohibitions table — this is more effective than positive rules alone. A table that says "use any" in one column and "defeats the type system, define a proper type" in the next is harder to ignore than a style guide paragraph.

Before every commit checklist — a literal checklist the AI runs before finishing any task. Zero TypeScript errors. No hardcoded values. No empty catch blocks. No imports across app boundaries. This is the gate.

The clean code rules

These go verbatim into CLAUDE.md. They are not a style guide — they are enforced by the commit checklist.

The single test for any line of code

What this actually changes

With this system in place, every AI session opens by reading CLAUDE.md. It knows the structure, the rules, the prohibited patterns. It knows what shared means and why apps don't import from each other. It knows that any is a blocker, that empty catch blocks are bugs, that sensitive data doesn't get hardcoded.

It still makes mistakes. You still need to review. But the mistakes are smaller, the patterns are consistent, and the codebase accumulates quality instead of debt.

The methodology is the memory the AI doesn't have. You build it once per project. It compounds across every session after that.

Getting started

Every codebase accumulates debt. Not the big architectural decisions — those get debated in PRs. The quiet stuff. The function that does three things. The variable named d. The catch block that swallows errors silently. The magic number buried in a conditional.

Martin's Clean Code has been the standard reference for over fifteen years. Most developers have read it — or at least know they should have. But reading the book and consistently applying its principles across a 50,000-line codebase are very different things.

clean-vibe closes that gap.

How it works

Connect any GitHub repository — public or private — paste in your GitHub token and Anthropic API key, and clean-vibe fetches the full file tree. It estimates scan time per directory so you can run in batches rather than waiting for a monorepo to finish overnight.

Three levels of severity

Not all violations are equal. A magic number in a config file is not the same as a catch block that silently swallows errors in a health data platform. clean-vibe sorts accordingly.

What it actually finds

Here's a real example of what the tool surfaces. A function that looks fine at a glance:

async function proc(d, t) {
  // process the data
  if (d && t === true) {
    try {
      await save(d);
    } catch(e) {
      console.error(e);
    }
  } else {
    return -1;
  }
}

async function saveIfActive(
  record: Record,
  isActive: boolean
): Promise<void> {
  if (!isActive) return;
  try {
    await saveRecord(record);
  } catch (error) {
    showError('Could not save record.');
    throw error;
  }
}

The violations: cryptic parameter names (d, t), a flag argument, a silent catch, an error code return, and a comment describing what the code already says. Five violations in eight lines — none of them obvious without a systematic review.

The two-pass model

Speed matters when you're scanning hundreds of files. clean-vibe uses Claude Haiku for the first pass — fast, cheap, covering every file. The cost for a 200-file repo is roughly $0.15.

After the Haiku pass, any file with blocker-level violations gets a second pass with Claude Sonnet. Sonnet does what Haiku can't: root cause analysis, code smell categorization from Martin's taxonomy, and a concrete refactored example showing the correct approach. This is where the report goes from a list of complaints to an actionable improvement plan.

Zero dependencies. Zero build step.

clean-vibe is a single index.html file. No npm install, no webpack, no server. Open it locally or serve it from any static host. Your API keys stay in your browser — they never pass through any server except Anthropic's and GitHub's directly.

# Clone and open — that's it
git clone https://github.com/Triple-Moon-Goddess/clean-vibe.git
open clean-vibe/index.html

Free for non-commercial use

If you're using clean-vibe for personal projects, learning, or open source work — it's free, forever, no account required. Bring your own Anthropic API key and GitHub token.

Commercial use — at a company, in client work, or as part of a product — requires a license. Three tiers: Individual ($100/year), Team up to 10 developers ($500/year), and Organization unlimited seats ($1,500/year).