The Vibe Coding Trap — The Faster You Go, The More Structure You Lose
Introduces the structural collapse problem you're bound to run into when building fast with vibe coding, and how to solve 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 after two or three weeks, this happens.
You ask, “Add a login feature,” and the code the AI generates conflicts with your existing code. You open the file to find where the conflict is, only to discover the file is over 500 lines long, and it’s hard to tell what any of the code is even doing.
This is the most common trap in vibe coding.
Why Vibe Coding Breaks Down Structure
There are two reasons your project structure falls apart when you’re rapidly adding features with vibe coding.
The AI only remembers the current conversation
Claude Code writes code based on the files you currently have open and the conversation you’re having right now. Even if you decided three weeks ago that “components must always go in the components/ folder,” the AI won’t know that unless you bring it up again in the new conversation.
As a result, code that does similar things ends up scattered across multiple places, and your folder structure gets more and more tangled.
Feature requests outpace structural design
The speed of vibe coding is both its strength and its weakness. Because you can build features so quickly, you end up implementing before you’ve really thought through the design.
| Timeframe | Symptoms |
|---|---|
| Weeks 1–2 | Everything works great as you add features. Productivity is at its peak |
| Weeks 3–4 | You start wondering, “Why isn’t this part working?” |
| Weeks 5–6 | Adding a new feature breaks an existing one. Even the AI struggles to pinpoint the cause |
| 2+ months | You start thinking about rebuilding everything from scratch |
What You Need to Avoid Losing Structure
The solution to this problem isn’t coding skill. It’s the habit of recording and tracking your project’s structure.
If you keep a record of what’s been built, what’s connected to what, and when each feature was added, you can later give the AI context by saying, “Here’s what our project structure currently looks like.”
Several Ways to Record Your Structure
There isn’t just one way to keep this record. Let’s look at a few widely used approaches.
Documentation files inside your project — Writing down your folder structure and conventions in Markdown files like CLAUDE.md or ARCHITECTURE.md. You can start right away without any extra tools, and Claude Code reads them automatically at the start of a conversation. The downside is that as your code grows, you have to keep updating the docs by hand, and at some point they start drifting away from the actual structure.
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, you have to copy and paste it every time you want to give the AI context.
Diagramming tools — Drawing your structure with Mermaid or Excalidraw. Great for grasping the big picture at a glance, but every structural change means reworking the diagram, which makes it a burden to maintain.
For a small project, any of these can be enough. Their shared limitation is that a person has to maintain the record by hand. That’s why services built specifically for tracking project structure have started to appear — and in this series, we’ll introduce one of them: Umtri.
Umtri — A Way to Track Your Project’s Growth
Umtri is a service that records and visualizes how your project’s structure has changed over time.
Umtri.io
Track your project growth history and configuration.
app.umtri.io
The core idea is simple: a project grows like a plant. It starts as a small seed, then a stem forms, branches spread out, and leaves appear. Umtri records this growth process in the shape of a tree.
| Stage | Plant Analogy | Meaning in Your Project |
|---|---|---|
| Trunk | Thick trunk | The whole app/service or a major domain |
| Limb | Main branch | A group of features or a major area of work |
| Twig | Small branch | Detailed feature groups, modules |
| Leaf | Leaf | Actual files, components, service units |
| Vein | Leaf vein | Functions, methods, and other specific behaviors |
Once you’ve recorded this structure in Umtri, if you later say something like “There’s a problem with the tag system,” you can immediately see which components are connected to it.
When Should You Start Tracking?
You don’t need to define the perfect structure right from the start. A good time to begin tracking is once your first core feature is complete. At that point, organize your current structure once, and then update the tree each time you add a new feature.
In the next post, we’ll cover how to actually connect Umtri with Claude Code — in other words, setting up MCP.