Clean Code Is Dead. Long Live Clean Specs.
Your Code Has a New Audience, and It's Not Human
Steve Yegge shipped 225,000 lines of Go code he’s never read.
Let that sink in.
Beads — his coding agent memory system — is used by tens of thousands of developers daily. It’s 100% vibe coded. Yegge has never looked at a single line. Same with his new project, Gastown. Three weeks old, 100% vibe coded, never seen the code, never plans to.
His reaction to anyone uncomfortable with this? “Get out now.”
The Heresy
For two decades, we’ve been taught that code is literature. Uncle Bob’s Clean Code. Martin Fowler’s Refactoring. Elegant variable names. Single responsibility. Code should read like prose.
We optimized for human comprehension because humans had to maintain it.
But what if that’s no longer true?
Simon Hoiberg put it bluntly: “Half my code is now written by AI, and the other half is read by AI to fix bugs. Optimizing for human readability is becoming pointless.”
The audience for your code has changed. And it’s not you anymore.
The Other Day I Wrote About Comprehension Debt
I argued that vibe coding creates legacy code from day one. That velocity without comprehension isn’t velocity — it’s procrastination with extra steps.
I still believe that. Mostly.
But here’s the uncomfortable follow-up question: What if comprehension debt only matters when you have to pay it?
If AI writes the code and AI debugs the code and AI refactors the code... who exactly needs to understand it?
The New Contract
The old contract: Write clean code so humans can read it.
The new contract: Write code that produces correct outcomes, verified by tests that humans can understand.
This is a crucial shift. The code becomes disposable infrastructure. The tests become the spec. The behavior becomes the product.
Steve Yegge doesn’t need to understand 225,000 lines of Go. He needs to understand what Beads should do. The tests verify that it does it. The code is just... implementation detail. An artifact. A byproduct.
Clean Specs > Clean Code
Here’s the heretical thought experiment:
What if “clean code” principles should now apply to your specifications instead of your source code?
Think about it:
Readable intent: Your specs should be crystal clear. “Users can checkout with valid payment. Invalid cards show an error. Empty carts can’t checkout.”
Single responsibility: Each spec describes one behavior. Not implementation — behavior.
Self-documenting: Specs are the documentation that gets executed. They describe what the system should do, and you verify it actually does.
Easy to modify: When requirements change, you update the spec first. AI updates everything else.
The source code can be a tangled mess of AI-generated spaghetti. Who cares? If you can clearly specify what you want and verify you got it, the implementation is just a detail.
The Yegge Paradox
Here’s what’s wild. In the Vibe Coding book Yegge co-authored with Gene Kim, “Steve” is described as reviewing 10,000 lines of code a day, throwing away 10 lines for every line kept.
Wait. He reviews code? I thought he never looks at it?
The answer, I think, is this: He reviews outcomes. He reviews test results. He reviews whether the thing works. He’s not reading code for elegance or comprehension. He’s running it, breaking it, verifying it.
The code review has become a behavior review.
What This Means for You
I’m not saying burn your Clean Code book. (Okay, maybe I am. That thing is 400 pages of what could’ve been a blog post.)
But consider this workflow:
Specify the behavior — in plain language. “Users can checkout with valid payment. Invalid cards show an error. Empty carts can’t checkout.”
Let AI write the tests — it turns your specs into executable verification
Let AI write the implementation — who cares if it’s ugly
Verify the outcomes — does it do what you specified? Try to break it. Edge cases covered?
Ship it — the code is a means to an end
If something breaks, you don’t debug the code. You describe the broken behavior. AI writes a failing test. AI fixes the implementation. You verify the outcome. You never had to understand the implementation. You just had to understand what you wanted.
The Catch
There’s always a catch.
This only works if your specifications are actually good. If your specs are vague, incomplete, missing edge cases — you’re in the worst of both worlds. Incomprehensible code that doesn’t even do what you need.
That’s not vibe coding. That’s vibes-all-the-way-down coding. And that’s how you get 18 out of 20 CTOs reporting production disasters.
The discipline has to go somewhere. If you’re not putting it into clean code, you damn well better be putting it into clear specifications and ruthless outcome verification.
The Real Skill Shift
Old skill: Writing elegant, maintainable code that other humans can understand.
New skill: Specifying behavior precisely and verifying outcomes ruthlessly.
The developers who thrive won’t be the ones who write the cleanest code. They’ll be the ones who can articulate exactly what they want. Who can break their own systems. Who can look at a feature and immediately think of ten ways it could fail.
Code literacy is becoming specification literacy. The new “clean code” is clear intent.
The Uncomfortable Conclusion
We spent twenty years optimizing for human readers who are increasingly being replaced by AI readers.
Maybe Steve Yegge is right. Maybe the code doesn’t matter. Maybe it never really mattered — we just didn’t have anything better.
What matters is: Does it work? Can you prove it? Can you verify it still works after changes?
Clean code was a proxy for those questions. A good heuristic when humans had to debug.
Clean specs answer those questions directly.
The code is dead. Long live the specs.
This is a follow-up to my recent essay on comprehension debt. The tension is real: you need to understand the problem deeply enough to specify it clearly, but maybe not the implementation at all. Where that line is... I’m still figuring out.