Nobody Is Designing Code Anymore... and then we rent

Every post on my feed is either a "who is better Claude or Codex" or "Vibe Coding sucks".. plain simple non productive debates.

I have been building with AI agents daily for months now, and the more I lean into vibe-coding the more i realize the importance of what we had before these new tools. We are assuming that, based on a detailed desire alone, an LLM can do magic. We stopped writing specs and then we blame the models or the paradigm.

The process existed for a reason#

Specs, design docs, architecture decisions are treated like bureaucratic leftovers from the waterfall era. Something you did because your manager made you!

These practices were invented because people built systems that broke, figured out why, and created processes to stop it from happening again. Decades of painful lessons, compressed into habits. All of it is getting thrown away because we are chasing speed. Well how is speed working out for you?

A prompt is not a spec. A functional PRD is not a design document, and a TDD approach as an instruction in the .md file is not a strategy. They describe what you want right now (and partially!). They say nothing about how the system should behave over time, at boundaries, under edge cases, or when two features need to talk to each other. They're consumed and forgotten. The code gets generated, and there's no artifact left that records why things were built that way.

You are left blind looking at a black box.

The source of truth problem#

This isn't just about discipline or best practices. This is also about how LLMs actually work and how you as an agent manager have visibility over the built product.

The agent has no persistent mental model. Every prompt is a blank slate plus whatever context you feed it/memory system. Ask it to build feature A, it makes choices. Data structures, patterns, naming, boundaries. All implicit. Nothing recorded. Then feature B. Different choices. Not because it's being inconsistent on purpose. It literally doesn't know what it decided last time.

By feature F or G, the codebase is a patchwork of locally reasonable but globally incoherent decisions. And the worst part? The code looks clean. Each piece works in isolation. The rot is structural, invisible until something breaks at scale.

The agent needs a source of truth. Without one, every feature is a guess and an attempt to achieve the outcome in the most efficient way possible and save tokens. Every prompt is a coin flip on whether it will align with what already exists or invent something new, because its faster.

This isn't just a big-team problem either. Solo developers feel it the same way. You think you can hold it all in your head. You can't. Not when the agent is generating code faster than you can internalize it.

And NO. Before you even tell me, I can add it to my .md file. That works for about five tickets. Then the .md is a bloated swamp nobody reads.

Design is cognitive, not documentary#

Designing a system is not writing a document. It's sitting down, drawing boxes, arguing with yourself about where the boundary goes, talking yourself into and out of three different shapes before you commit. That argument IS the design. Not the file. The argument. The file is just what falls out of it. Skip the argument, and you don't just lose the file. You lose the ability to review what the agent hands you, because you never built the thing in your head to begin with.

And you become a prompt operator using brute force, new sessions, and a bizillion attempts at it to solve the problem, because you dont know where that logic is or how to make sense of it in a decent time frame! You can't feel when the agent violated the architecture, because you never built the architecture. Not really. You described a vibe. The intent is gone. Not gone like deleted. Gone like never existed.

That's exactly the moment where you need to step in and think. A lot of people are noticing this. Entire threads about the right way to word a request, as if the bottleneck is communication clarity and not the absence of design.

Small spec, real spec#

No, I'm not talking about 50-page design docs nobody reads. That's the other failure mode, and it's equally bad.

What I'm talking about is the smallest thing you can actually maintain, that the agent will actually read, that will override the agent when it starts improvising. It records what you decided. The patterns, the boundaries, how data moves, and why you chose that shape over the other one you also considered.

Not documentation for the next developer. Documentation for the next prompt.

It has to do two jobs at once. It aligns the agent, AND it forces you to actually think. Drop either job and the whole thing breaks. The agent drifts without the spec. You atrophy without the design work. One without the other is worse than nothing.

We figured this out decades ago with human teams. Your shallow diagonal review is as good as no review if you don't know what you are reviewing. You will only review semantics. The same principles apply now.

Blueprints are your torch#

Stop shipping, start designing.

The spec exists before the code does. Chat, write, draw, research with/without LLM, whatever your process is, then construct the specs with the help of an agent. Use diagrams. An image speaks louder than a thousand words. Diagram syntaxes such as PlantUML and Mermaid are great tools. Text-based, they provide real structure, are easy for an LLM to follow, and visually make it easy to spot issues.

Use hierarchy. I am sorry to break it to you, but the zero shot is a myth. As we all know, no amount of specs will capture the full picture, and subsequent work is done to finalize and align the outcome. When you add specs, organize them as epic, features etc... and make the parent files/tickets hold the globally always up-to-date specs of that feature/epic. This will both serve as ticket orchestration/work dispatch and graph for the agent to read related work/specs and know where to update new modifications following subsequent changes.

Work flows down, specs stay fresh going back up. The agent reads the parent spec before touching a ticket, and the ticket updates the parent on the way out.

This is exactly how ticket hierarchy works in AgentsInFlow. Not because I planned it that way but because nothing else held and still improving on it.

A comprehension gate before ship. No code merges until a human can explain, out loud, what it does and why it does it that way. Not read the diff. Explain the diff. If you can't, don't ship. That's the signal to slow down, not to re-prompt harder.

Treat the spec as the cognitive artifact, not the compliance artifact. It's not there because process wants it. It's there because it's the only place your mental model lives outside your head. Writing it is the design work. Reading it is the review work. It doesn't have to be long. It has to be real.

None of this is a return to waterfall. It's the opposite. It's recognizing that the faster the agent gets, the more the design process has to be the thing that keeps pace.

Someone else landed here too#

I wrote the first draft of this a few days ago. Since then, Nate B Jones made a very similar argument from a different angle, calling the shipped-but-never-understood code "dark code." He frames it as an organizational capability problem, and his proposed fix, spec-driven development plus self-describing systems, lands in the same place I do. Worth watching if this resonates. He's @natebjones on X.