I was working through a familiar kind of job recently: taking older working code and moving the parts worth saving into a newer, cleaner framework.
That sounds straightforward enough.
It usually isn't.
The old code has useful pieces in it. Some of it still represents decisions that were correct. Some of it solves problems that shouldn't have to be solved twice. But it also grew up in a different environment, under different assumptions, with different shortcuts.
So the job isn't just copying old code forward.
The job is deciding what still belongs.
And that got me thinking about a problem I've run into before with AI-assisted development.
Not the dramatic kind of problem where the AI does something obviously stupid.
The quieter kind.
The kind where everything seems fine until one day you open a file and realize it has become far more important than it was ever supposed to be.
The elephant didn't arrive all at once
That's the part that keeps standing out to me.
The elephant doesn't walk into the room.
You build it there.
One small change at a time.
A project starts with a pretty reasonable structure. The file names make sense. The folders make sense. The responsibilities seem clear enough.
Then you start building.
And real work is messy.
You add a mode.
You fix a panel.
You add an export option.
You make the layout prettier.
You handle a special case.
You add a fallback.
You move a button.
You add a helper function.
None of those feel dangerous by themselves.
Most of them are just normal development.
But then one helper function needs to know about state.
Then the state needs to know about the platform.
Then the platform branch needs to know about the export path.
Then the preview code needs to know about the editor state.
Then the editor state needs to know about the project tree.
Each step makes sense in the moment.
Each change solves the problem in front of you.
The AI can make the change quickly, and the result works, or at least appears to work.
So you accept it.
Then you accept the next one.
Then the next one.
And one day that file is no longer just a file.
It's the place where everything seems to happen.
That's the moment that bothers me
The thing that bothers me isn't just the file size.
Yes, giant files are harder to deal with.
They're harder to review. They're harder to replace cleanly. They burn more context. They make every change feel a little more dangerous.
But the size is only the visible part.
The real problem is that the file has lost its job.
It started out as one thing.
Now it's doing five things.
And because it does five things, the AI keeps finding reasons to add a sixth.
That's how the mess feeds itself.
The more a file knows, the more useful it looks.
The more useful it looks, the more the AI wants to use it.
The more the AI uses it, the harder it becomes to separate anything later.
"For now" has a way of sticking around
I've also learned to be suspicious of the phrase:
"Just put it there for now."
Sometimes that's fine.
Sometimes you really do need to keep moving.
Not every little change deserves a big architecture meeting.
But "for now" has a long shelf life.
Especially with AI.
If you don't write down that something was temporary, the next session doesn't know it was temporary.
It just sees existing code.
And existing code looks like permission.
So the shortcut becomes a pattern.
Then the pattern becomes the design.
Nobody sat down and decided that.
It just happened.
This is where the map matters
This is one of those places where I'm becoming more convinced that AI-assisted projects need a living map.
Not a big fancy design document.
Not a file nobody reads.
Just a practical note that says:
This is how the project is shaped.
This is where major behavior lives.
This is where new pieces should go.
This is what doesn't belong in these files.
This is what should be checked before changing this part of the system.
Without that, each AI session has to rediscover the project.
That may work when the project is tiny.
It doesn't work as well once the project has real history behind it.
And it really doesn't work well after the structure has already started to drift.
At that point, you're not asking the AI to follow the design.
You're asking it to infer the design from whatever mess the last several sessions left behind.
That's not a great place to be.
The hard part is stopping
The hard part isn't knowing that structure matters.
Most developers know that.
The hard part is stopping long enough to deal with it.
That's even harder with AI, because the tool can move so quickly.
Fix this.
Now fix that.
Now add this.
Now clean up that panel.
Now handle this mode.
Now support this option.
That kind of momentum feels productive.
And sometimes it is productive.
But speed can hide decay.
You can make a lot of progress while also making the project harder to maintain.
That's why every so often, I think you have to stop and ask a different question:
What has this file become?
Not what was it supposed to be.
Not what did we name it when the project started.
What has it actually become?
If the answer is "a little bit of everything," then the elephant is already growing.
Move it while it's still small
That's probably the real lesson I took from it.
Don't wait until the project is obviously in trouble.
Don't wait until one file controls everything.
Don't wait until every change feels dangerous.
Don't wait until the AI has to read half the repo to change one button.
The elephant is easier to move when it's small.
Split the file while the seams are still visible.
Move the helper while you still remember why it exists.
Separate the platform behavior before it leaks everywhere.
Update the project notes while the project still roughly matches the notes.
That isn't bureaucracy.
That's just keeping the project understandable.
The shape of the project is part of the work
The code working today isn't enough.
It also has to remain changeable tomorrow.
That's the part AI can make easy to forget.
When the assistant is moving quickly, it's tempting to treat each working change as progress.
And it is progress.
But if every working change makes the project harder to reason about, you're borrowing against the future.
Sooner or later, the debt comes due.
And by then, the elephant may already be too large to move easily.
That's why this stuck with me.
The elephant didn't walk into the room.
We built it there.
One reasonable shortcut at a time.
Where this goes next
This is the personal workflow issue behind the companion guide, Do Not Let AI Build the Elephant in the Room.
That guide steps back from my own experience and looks at the bigger question: how do you keep AI from quietly turning one convenient source file into the center of the whole project?
-- Charles