Discover how to avoid the pitfalls of AI project management with structured approaches and specialized agents, making your coding life easier and more organized.

From Vibe Coding to Agent Teams: How I Stopped My AI Projects from Turning into a Mess

After months of using general AIs, I noticed a frustrating trend in my coding universe—duplicated logic, inconsistent patterns, and a structure that seemed thrown together by a committee deciding between coffee and chaos. Fear not, friend! There’s a light at the end of the tunnel, and it’s not an oncoming train. 🚂 Let’s dive into how I transformed my messy projects into efficient systems.

1. The Problem: My Code Was Slowly Rotting 🐛

You know that moment when your beautifully crafted code starts to feel more like a tangled mess? Yup, that happened to me. It was like watching a salad turn into a soggy pile of greens—unpleasant and yet oddly relatable.

Before, I was battling repetitive code, mixing libraries, and dealing with weak tests that barely passed. Each modification sent ripples of chaos throughout my project.

2. What I Tried (And Why It Didn't Work) 🤦

I’ll spare you the details of my failed attempts, but here’s a rundown:

Spec-first tools like Kiro: Beautifully shipped stories until I needed a refactor. Imagine steering a cruise ship with just a bicycle. Not fun. 🚴‍♂️
Mixing tools: I tried using Kiro for new projects, Cursor for tweaks, and Claude for cleaner code, but it felt like juggling chainsaws. Seriously, stability? What’s that? 🔪

3. The Breakthrough: Specialist Agents + Organized Docs 💡

The lightbulb moment hit me: what if I treated AI like a real development team? Enter sub-agents! I organized them under ./claude/agents, each with a specific role:

Architect → Owns docs/arc42/* (the system design stuff)
Tech Lead → Steward of docs/developer-guide/* (standards + templates)
Developer → Responsible for following CLAUDE.md + dev guide (the actual coding)
React UI Designer → Focused on Next.js components in src/app/*, src/components/*
Manual Tester → Develops test plans in docs/product/*
Product Owner → Manages stories and epics in docs/product/*

4. How It Actually Works (With Code Examples) ⚙️

Here’s a peek into how I defined each agent:

---
name: architect
description: "Use this agent when you need to create, update, or maintain architectural documentation and decisions for the project."
model: sonnet
color: purple
---

You are now an expert Software Architect and Technical Documentation Specialist... Sounds fancy, right? 😎

5. My Documentation Strategy (The Key to Success) 📜

A coherent documentation strategy was crucial. Here’s what I implemented:

Keep docs short and focused: Use the arc42/dev-guide for concise references with runnable examples.
Break up big docs: Small markers for easier navigation and recall.
Separate concerns: Ensure agent definitions are reusable and distinct from working docs.

6. The Results (Spoiler: It Actually Works) 🏆

With this organized system, my coding life improved dramatically:

Quality compounds instead of decays: My codebase enhances over time, not disintegrates.
Refactors and bug fixes get cheaper: Making changes became a walk in the park.
My effort decreases over time: As agents align with repository patterns, they make fewer errors.

In a nutshell, if your AI projects have felt like they’re crumbling after just a few adjustments, give this approach a try! Stay tuned for future updates on my methods and design patterns. 🛠️