Why AI Coding Gets Worse as Your App Grows (And How to Fix It With "Labeled Drawers")
Day one of building an app with AI feels like magic. You type a prompt, and in seconds, you have a working prototype.
By day ten, the magic fades. You ask the AI to fix a button, and it breaks your navigation. You ask for a new feature, and the AI starts hallucinating or rewriting things that already worked.
If you have ever wondered why AI seems to get "dumber" the bigger your project gets, the answer isn't the AI's intelligence—it's your app's organization.
The "Junk Drawer" Problem
AI models know how to write code, but they do not inherently remember your app.
Every time you start a new chat session, the AI has to read your files from scratch to understand how your project works. If all your code is dumped into one massive file—or scattered randomly without structure—the AI has to dig through a digital "junk drawer" just to find a pair of scissors.
Eventually, it finds a pair, but sometimes it grabs the wrong one.
For example, if you have a login button written three different times across a messy codebase and ask the AI to fix it, the AI will likely find the first one, fix it, and stop. The other two remain broken. That is why AI fixes often feel like they only work half the time.
Putting everything into a single giant file doesn't prevent code from getting lost; it just guarantees nothing ever gets found cleanly.
What Clean Code Looks Like: Labeled Drawers
To keep AI fast and accurate, you need to trade the junk drawer for labeled drawers—meaning dedicated folders with clear, single responsibilities.
Imagine you are building a dog-walking app. Instead of one giant file, your project should look like this:
/pages(The Screens): Holds one file per screen—such asHome,Booking, andProfile./components(The Reusable Pieces): Holds UI elements used across multiple screens, like a "Book a Walk" button. There is only one copy of that button, used everywhere. Fix it once, and it updates everywhere./data(The Storage): Holds the logic that saves, loads, and manages your bookings.
When your code is structured this way, the AI doesn't have to guess where things live. It opens the exact drawer it needs.
Give Your AI a GPS: The /docs Directory
Even with clean code folders, an AI agent can still lose track of the big picture as your project grows. To stop agents from guessing how your system fits together—or accidentally building duplicate features—create a dedicated
/docs folder inside your project.Think of
/docs as the AI's persistent memory and GPS. Keep four living markdown files inside it:Architecture.md: A high-level map of your tech stack, folder layout, database structure, and how data flows through the app.Components.md: An inventory of all existing UI components, where they live, and what props/inputs they take—so the AI reuses them instead of writing duplicates.Objective.md: Your current goals, product specifications, and active feature roadmap so the agent always knows what you are building and why.changelog.md: A running log of completed features, structural changes, and bug fixes so new chat sessions immediately see what changed recently.
When you instruct your AI to read
/docs before coding—and update those files after every task—every new chat session picks up right where the last one left off.How to Make the AI Organize Your Code For You
You don't need to be a senior software architect to organize your codebase. You just need to give your AI assistant strict ground rules on Day One—and force it to remember them.
Open your project folder in an AI coding environment (like Claude Code, ChatGPT Codex, or Antigravity) and paste this exact prompt:
"Keep this app organized so a beginner can read it. Screens go inpages, shared pieces go incomponents, and saving and loading goes indata. One job per file, and no file over 300 lines. Maintain a/docsfolder containingArchitecture.md,Components.md,Objective.md, andchangelog.md. Always check/docsbefore writing anything new to see if it already exists, and update the relevant doc files after every change. Save these rules in your rules file (CLAUDE.mdfor Claude, orAGENTS.mdfor Codex)."
Why the 300-line limit matters: Large Language Models lose focus when reading massive files—a problem known as the "lost in the middle" effect. When a file stays under 300 lines, the AI can hold the entire file in sharp focus at once, make safer edits without accidentally deleting surrounding code, and automatically break complex logic into smaller, modular pieces before your codebase turns into spaghetti.
Because tools like Claude Code automatically read
CLAUDE.md and Codex reads AGENTS.md at the start of every new chat, the AI will read your organization rules and check your /docs map first before writing a single line of code.(Note: While Claude's code tab requires a paid plan, Codex can be used with a free ChatGPT account).
Already Have a Messy App? How to Clean It Safely
If your project is already a sprawling mess, don't ask the AI to rewrite everything at once. Follow this four-step cleanup process instead:
- Create a Save Point with Git: Before changing anything, ask the AI: "Make a save point with Git so I have a copy I can go back to." (If you don't have Git installed yet, the AI can install and initialize it for you).
- Generate Your
/docsBaseline: Ask the AI to scan your existing project and generate initial drafts ofArchitecture.md,Components.md,Objective.md, andchangelog.mdinside/docs. - Clean One Folder at a Time: Ask the AI to refactor one specific piece—like moving your screens into
pages—without changing what the app does. Click around your app to verify it still works, make a Git save point, and repeat until every file is under 300 lines and in its proper folder. - Get Your Map: Once it's clean, ask the AI: "Explain my folders to me like I'm 10." You’ll get a clear, plain-English map of your own software.
When your codebase has labeled drawers and an up-to-date
/docs map, both you and the AI always know where to find the scissors.
No comments:
Post a Comment