Specsmaxxing: Why AI Coding Needs a YAML Contract Before a Single Line of Code

There’s a word quietly making the rounds in developer circles: Specsmaxxing. The pitch is simple — before you let an AI write a single line of code, you write a brutally detailed YAML spec first. It sounds like old-school waterfall cosplay. It’s actually a response to a very 2026 problem.

The new disease: “AI psychosis”

If you’ve spent serious time with Cursor, Claude Code, or Copilot, you know the arc. The first thirty minutes are magic. Then the agent starts editing files it shouldn’t, reverses a decision it made an hour ago, and fixes the same bug three different ways — none of them right.

Developers on Hacker News and X have started calling this AI psychosis: the shared dissociative state where both the human and the model lose the plot. The context window stretches, intent blurs, and you end up squinting at the screen wondering what you were even building. Natural-language prompting alone, it turns out, is not a load-bearing structure.

So what is Specsmaxxing, exactly

The core claim is blunt: finish the YAML (or Markdown) spec before writing any code. And not a vibes-document — a real one:

• What you’re building, and explicitly what you’re not
• Exact shapes of inputs and outputs
• Edge cases and failure behavior
• Dependencies and constraints
• Test scenarios

Why YAML? Because it’s the structured format LLMs read most consistently. “Build me a good auth flow” gets you a different result every time. A schema gets you something repeatable. Think of it as a contract between you and the model.

Prompts are ephemeral. Specs persist.

The interesting part is that proponents don’t frame this as a productivity hack. They frame the spec as the actual source of truth of the system. Code becomes a build artifact — one specific compilation of the spec.

Flip that around and something weird happens. For decades we wrote code and then documented it. Specsmaxxing says: write the document, then generate the code. In a world where models are good enough to implement competently, the asset worth a human’s careful attention isn’t the code anymore. It’s the specification.

There’s a portability bonus too. A well-written spec produces broadly equivalent results from Claude, GPT, and Gemini. You stop being locked into whichever tool you happened to start with.

Wait, isn’t this just… requirements docs

Honestly, yes. Specs, design docs, TDD — software engineering has been preaching this gospel for forty years. Plenty of senior engineers are rolling their eyes and muttering “we already did this.”

The motivation is what’s new. The old specs were written for human collaborators. These are written for non-human ones. AI ships code faster than any junior dev, which also means it ships wrong code faster. Without guardrails, you can generate five thousand lines of confident chaos in an afternoon.

So the irony lands hard: the more capable AI gets at coding, the more valuable upfront design becomes. The industry is rediscovering “spec-first” right after a year of “vibe coding” maximalism.

How to actually try it

Start small. Don’t try to spec your entire system on Monday — you’ll abandon it by Wednesday.

Pick one feature. Create a single .spec.yaml file with goal, inputs, outputs, edge cases. Hand that file to your agent as context and tell it to implement against the spec. When the model wanders, the spec pulls it back. It functions as an anchor — a fixed point in a session that otherwise drifts.

Worth doing: draft the spec with the model before coding starts. It’s surprisingly good at surfacing edge cases you’d have missed and would have hit at 2 a.m. in production.

The takeaway

Specsmaxxing isn’t a silver bullet, and the name is a little ridiculous. But if you’ve felt the limits of “prompt and pray,” it’s worth a weekend.

The deeper question it raises is the one worth sitting with: in an era where machines can type faster than us, what is the human actually for? The answer might not be in the hands on the keyboard. It might be in the head deciding what to build in the first place.