The AI that aced your side project will struggle with your real one
Loading...
Loading...
Join JS Mastery Pro to apply what you learned today through real-world builds, weekly challenges, and a community of developers working toward the same goal.
You've seen the magic trick. You start a fresh project, describe what you want, and the agent scaffolds a working app in minutes. Clean structure, sensible names, tests that pass. It feels like the future showed up early.
Then you point the same agent at the codebase you actually get paid to work on. The ten-year-old one. The one three people understand and two of them left. And the magic is gone. It suggests changes that look right and aren't. It "fixes" one thing and quietly breaks another. It writes confident code against a system it clearly doesn't understand.
Most people read that as "the AI is good, my codebase is just a mess." That's the wrong frame, and it keeps you stuck. The agent was never good at coding in general. It's good at coding greenfield, where nothing pushes back. Your real codebase pushes back constantly, in ways the agent can't see.
This isn't a vibe. The figures people quote off DORA's 2026 data are blunt: AI tools give something like a 35 to 40 percent boost on clean, new work, and a small fraction of that, roughly a quarter, on mature codebases. Same tools, same models. The only thing that changed is the code. And the word everyone lands on for the cause is the same one: comprehension. The agent isn't slow on your codebase. It doesn't understand it.
Which matters, because almost nobody works greenfield. Most real software is old. A large share of big companies still run systems older than the developers maintaining them. The fresh-project demo is the exception. Your actual job is the other ninety percent.
The reason is simpler than it looks. The most important rules in a mature codebase aren't written in the code. They live in people's heads, in a Slack thread from 2021, in the memory of an incident that made someone wrap one function in a retry with a comment that just says "do not remove." Why the auth check runs in that odd order. Why that field is nullable when it obviously shouldn't be. Which module looks dead but isn't.
None of that is in a file. And an agent can only reason about what it can see. The context window can't hold what was never written down. So the agent does the only thing it can do with a gap: it fills it with what worked in its training data. Those assumptions are correct on a clean project and wrong on yours.
That's what makes it dangerous instead of just unhelpful. It doesn't error out. It produces code that passes the tests, reads cleanly, and quietly violates a contract nobody ever wrote down. Everything looks fine. Six weeks later something breaks in production in a way no test was watching for, and the trail leads back to an assumption the agent was never told was wrong.
The instinct is to give the agent more. Load the whole repo. Point it at everything. Surely if it can see all the code, it'll understand the code.
It won't, for two reasons. First, dumping more into the context doesn't buy comprehension, it costs it. Attention spreads thin across a huge pile of files and the one detail that matters gets buried. Second, and this is the one people miss, the rules it's missing were never in the files to begin with. You can load all three hundred thousand lines and the reason that function is fragile still isn't in there. Volume was never the problem. Legibility was.
The move that actually works is boring, and it works every time: before the agent writes a line, make the codebase legible to it.
Step zero is reading the real structure, with the agent's help, and writing down what's actually there. Not documentation for humans. A map for the agent. Put the real module boundaries in it, where one part of the system ends and the next begins. Put the patterns the code actually uses, not the ones a tutorial would use, so the agent matches your system instead of importing its own habits. Put the landmines: the contracts you can't break, the parts that look wrong but are load-bearing, the spots where a small change ripples further than it should. And put how data really moves through the thing, start to finish. You keep that in a file the agent reads on every task, so it reasons from evidence about your system instead of guessing from its training.
Then two habits. First, pin down how the code behaves now, before you touch it. A handful of tests that capture what it currently does, even the behavior nobody planned, turn a silent break into something you can actually see. Second, start small with heavy oversight, and give the agent more room only as the system gets more legible, not before. Autonomy is something a codebase earns by becoming readable, not something you hand over on day one.
The judgment is the part you can't skip. The agent can help build the map, but you decide what's a real constraint and what's an accident, what's load-bearing and what's just old. Get that wrong and you've written a confident map to the wrong city. The map is only as honest as the person making it.
This is the work almost no AI tutorial teaches, because greenfield demos are easier to film. It's also most of your actual career. In the Agentic Engineering course it's a whole module built on a real open-source repository, not a toy, where the first move on unfamiliar code is exactly this: an audit step that reads the real project and writes the map before a single feature gets built on top of it.
And the honest part. You can grab that audit skill for free on GitHub today. What you can't download is the judgment around it: knowing what's worth making legible, what the agent must never assume, and when the code has earned more rope. The skill reads the structure. Reading a system you didn't write, and deciding what actually matters, is still on you.
A fresh project has no history to get wrong. Yours has ten years of it. Teach the agent your history, or watch it confidently guess.
