Part 1: Why Vibe Coding Breaks Down
Last month, I spent an afternoon building a URL shortener with Claude.
The first prompt worked beautifully. Code appeared. Tests passed. I felt like a wizard.
By the fifth prompt, things got weird. The AI added features I did not ask for. It changed the database schema twice. It could not remember what the API endpoints were supposed to be.
By the tenth prompt, I was not coding. I was negotiating with a machine that had forgotten the conversation we had twenty minutes ago.
This is not a failure of AI. This is the failure of the method.
Most of us use AI the same way we use a search engine: we ask for something, we get an answer, we move on. That works for recipes and trivia. It does not work for building software.
Because AI has a hidden limit. Not a technical limit — a structural one. And once you see it, you cannot unsee it.
In this series, I will show you that limit. Then I will show you a simple way around it.
The solution is not a better prompt. It is a different way to think about the work.
What if the problem was never the AI?
1.1 The Pattern: It Starts So Well
You have felt this. Everyone who has built anything non-trivial with AI has felt this.
You sit down with Claude, GPT, or Copilot. You start a new project. The first few exchanges feel like magic.
"Build me a URL shortener API."
Code appears. Beautiful, working code. You test it. It works. You are elated.
"Now add analytics so I can see how many times each short link was clicked."
The AI adds it. Still works. Two features done.
"Add user accounts so people can manage their own links."
The AI adds it. But now things start breaking.
The database schema from feature 1 does not quite fit. The authentication logic from feature 3 conflicts with the analytics query from feature 2. The AI tries to fix it, but introduces regressions. You try to clarify. The context window fills up. The AI loses track of earlier decisions.
You are no longer coding. You are herding cats with a keyboard.
This is "vibe coding" — casually prompting an AI to generate code, hoping it all holds together. It works for tiny scripts. It works for demos. But for real projects? It collapses under its own weight.
Why?
1.2 The Hidden Limit You Have Probably Noticed But Never Named
Here is a simple experiment you can run yourself.
Task A (Small and Focused):
Write a Python function that takes a URL string and returns True if it is a valid URL, False otherwise. Handle edge cases like missing protocols, invalid characters, and malformed domains.
The AI will likely produce a clean, correct, well-commented function in seconds. Quality: Excellent.
Task B (Large and Ambiguous):
Build a complete URL shortener service with a web interface, a REST API, user accounts, click analytics, and a database. Use Python.
The AI will produce something. But the result will be fragile. The authentication piece might not integrate cleanly with the analytics piece. The database schema might be inconsistent. Quality: Poor to Mediocre.
Same AI. Same model. Same capabilities.
The only difference is the size and scope of the task.
LLMs have a context window — a limit to how much information they can hold in working memory at once. Give them a small, self-contained problem, and they operate within that window comfortably. Give them a large system design, and they spill over the edges. They forget earlier decisions. They contradict themselves.
But there is a deeper insight here. A more important one.
1.3 The New Design Method That Changes Everything
AI does not think like a system architect. It does not hold a complete mental model of your project, with all its interconnections and trade-offs.
AI thinks in functions.
It understands:
"Given input X, produce output Y"
"Validate this string"
"Query that database table"
"Format this response"
It does not naturally understand:
How the URL validator should coordinate with the key generator
Whether the storage manager should be called before or after analytics logging
What happens when the redirect handler cannot find a key
These are integration concerns — and they are not the AI's strength.
Most developers, when encountering AI's limitations on large tasks, do one of two things:
Give up — "AI is not ready for real projects"
Push harder — "Let me write a longer, more detailed prompt"
Both miss the point.
The correct response is to change how you structure the work:
Do not ask the AI to build the system. Ask the AI to build the functions. You connect the functions into the system.
1.4 What This Unlocks
An AI can write an excellent URL validator. An AI can write an excellent key generator. An AI can write an excellent storage manager. An AI can write an excellent redirect handler.
Each of these is a functional block — a self-contained unit with a clear input, a clear output, and no hidden dependencies.
The AI's job is to implement each block.
Your job — the human's job — is to:
Define what the blocks are
Specify how they connect
Validate that the connections work
This is not "AI does everything." This is AI and human working symbiotically. Each doing what they do best.
Before (Vibe Coding)
After (FBD)
One giant prompt for the whole system
Many small prompts, one per block
AI loses context, contradicts itself
Each block's context is small and focused
Integration happens accidentally
Integration is explicit and designed
Hard to debug (which block failed?)
Each block can be tested in isolation
Changes require regenerating large portions
Change one block, leave others untouched
1.5 What Is Coming in Part 2 and Part 3
In Part 2, we will introduce Functional Block Design — a simple, repeatable methodology that turns this insight into practice. You will learn:
How to decompose a system into functional blocks
How to write a Block Spec (Description for humans, Prompt for AI)
How to generate code from the Prompt
How to store everything in one .py file
In Part 3, we will build the complete URL shortener — all six blocks, integrated into a working system.
By the end of this series, you will have a repeatable way to turn AI-generated code into systems that actually work together.
No more herding cats.
-
, "Cover image generated with Grok / xAI".