The Vibe Coding Trap — When Easy Makes Things Harder
As you grow a project with vibe coding, a mounting misunderstanding of your own project builds up. This is a story about the frustration that brings, and how to work through it.
The first few days are genuinely amazing. You describe an idea, code appears, the screen changes. Every time a feature gets added, you feel a real sense of accomplishment. But once the project grows past a certain point, this process gradually starts to get harder.
For example, you say “add a login feature,” and code you’d spent a while building conflicts with the existing code, breaking the project itself. The AI service spends all day analyzing where the conflict is — but despite its “found it” verdict, every fix keeps throwing errors, tokens and time drain away, and the problem stubbornly refuses to resolve.
This is the trap of vibe coding — and of AI services that seem to know everything, and that phrase their messages to make you believe it too.
There are two reasons your project structure falls apart as you keep adding features with vibe coding.
The AI sees less than you’d think
An AI service writes code by referring to the files currently open, the conversation in the current session, and maybe your CLAUDE.md. You remember what you built or changed earlier, and you assume the AI — the very one that made it — remembers too. But in reality it only grasps what it strictly needs; it doesn’t perfectly take in everything each time it writes new code.
If the AI service did parse the entire codebase and every spec on every message and edit, it would be far less efficient than it is now — so this is actually a sensible design. The problem is that, because of it, when you order a design that conflicts with older code in particular, the AI doesn’t realize it and works focused solely on doing the current request well. Behind that upbeat, confident tone, it’s working without knowing very much.
You don’t know the structure either
Vibe coding being easy is only true in the realm of “ordering.” If anything, the code itself has been written countless times in a style you don’t know, without you really looking at it — so you often have no idea how it’s put together or what risks it was built with.
So when a problem arises, you end up depending on the AI’s code analysis after all. And when that analysis is a misjudgment, you circle around the problem while it sits right beside you — code fixed on a wrong diagnosis breeds new problems, and you fall into an endlessly repeating loop of errors.
| Stage | Symptom |
|---|---|
| Project start | Features get built anew; things come together smoothly, just as you say them. |
| Project growth | The project grows and gets complex, gradually becoming a black box whose state you no longer know. |
| Problem appears | Adding a new feature breaks an existing one. The AI analyzes the cause — but misjudges it. |
| Problem grows | Fixes made on that misjudgment create new bugs. |
| Infinite loop | Bugs pile on bugs until analysis itself becomes hard; rebuilding from scratch would be better. |
How Not to Fall into the Error Trap
The direct solution to this problem may well be coding skill and experience. But since falling into this trap is itself the problem, preventing it is what matters — and for that, what you need is understanding your project’s structure and passing along, in your prompts, the things the AI service needs to watch out for.
If you know what’s been built, what’s connected to what, and when each feature was added — and how a new structure will slot in and what risks lurk there — you can give the AI the context it needs: “When you add this new feature, take into account these points in our current project structure.” That way you can see the traps in advance and avoid them.
Several Ways to Understand and Record Structure
The approaches below are widely used for understanding and recording structure.
Documentation files inside your project — Markdown files like CLAUDE.md or ARCHITECTURE.md, covered back in part 3, record your folder structure and conventions and help head off conflicts that can arise during edits. You can start right away without any extra tools, and Claude Code reads them automatically at the start of a conversation. The downsides: because they’re just documents, there’s no tool to verify them — if they drift from reality they can actually cause problems — and there’s a limit to how well a person can read and absorb them.
Note-taking tools — Keeping a log of feature additions and structural notes in something like Notion or Obsidian. You can write freely without worrying about format, but since the record lives apart from your code, it can go “stale.” You have to manage it meticulously and diligently, and pass along exactly what’s needed in your prompts.
Diagramming tools — Drawing your structure with Mermaid or Excalidraw. This is the easiest form for a person to understand, and great for grasping the whole picture at a glance — but every structural change means reworking the drawing, and it ends up duplicating what’s in your CLAUDE.md, which makes it less efficient.
Umtri.io — Umtri.io is a project-tracking tool BEPULJANG built to solve exactly these problems. It connects directly to AI services via MCP (Model Context Protocol), recording the project the AI builds and showing it visually through a UI; when you plan new work, it analyzes the nodes and relationships being added and automatically flags points where errors could arise. Once your project has grown beyond a certain point, adopting it can reduce risk and deepen your understanding of the project.
When and How to Start Recording
You don’t need to define the perfect structure right from the start. A good time to begin is once your first core feature is complete. At that point, write down your current folder structure and the role of your main files in CLAUDE.md once, and then just append whatever changes each time you add a feature.
The key is consistency, not volume. One line when you make a new component, one line when your data structure changes. As these small records pile up, a few weeks later you can hand the AI context by saying, “Here’s what our project structure looks like now.”
In the next post, we’ll cover how to connect external tools to Claude Code — that is, MCP. It came up briefly while introducing Umtri.io; in the next post, we’ll take a closer look at what MCP actually is.