There is an old developer joke:
“When I wrote this code, only God and I knew how it worked. Now only God knows.”
It is funny because we have all seen this project. The code works, but only one lead developer really understands it. The decisions, exceptions and unwritten rules live inside their head. Eventually, the developer becomes the codebase.
That is already an old problem for the development teams. A coding agent has even less chance. If another developer cannot understand where things belong, why they were built that way or what might break, AI will struggle with the same questions.
This article is about the habits that make a codebase easier to understand, change and verify. Most of them are not new AI practices. They are established development practices whose absence becomes much more expensive once you bring AI into the project.
AI Cannot Execute a Mood
AI works best when the work is already clear.
If you start the day with “let’s improve something” and make every decision while coding, the agent has nothing solid to follow. It can generate code, but it cannot decide what the product should do, what belongs in scope or which trade-off you actually want.
Before I involve a coding agent, I usually discuss the task with another AI first. We define the problem, question the approach, consider the edge cases and break the work into clear steps. Then I ask it to prepare a detailed prompt for the local coding agent.
AI can help at different levels. Use one agent to think through the work and another to execute it. Do not expect the coding agent to plan the product, design the architecture and implement everything from one vague sentence.
A vague task does not give the agent freedom. It gives it permission to guess.
Make the Project Predictable
A well-structured project should not surprise you.
When I open a codebase for the first time, I should have a good guess where the business logic, validation, API calls, views and shared utilities live. The same type of work should follow the same pattern across the project.
If one validation rule lives in a controller, another in a helper and the next one inside a view, the structure is already failing. AI can search the whole repository, but that does not mean it should have to.
Predictability reduces the amount of context an agent needs. It also lowers the chance that it adds the right code in the wrong place.
A clever folder structure is not the goal. A boring, consistent one usually works better.
Separate the Domains Early
A project becomes difficult to understand when unrelated business areas start leaking into each other.
Payments should not quietly depend on notification logic. User management should not know how reports are generated. Each domain needs a clear owner, a limited responsibility and an explicit way to communicate with the rest of the system.
This matters even more for AI. The smaller the boundary, the less context the agent needs and the lower the chance it changes something outside the task.
I love microservices because they make those boundaries harder to ignore. Each service owns its logic, data and communication contracts.
The goal is not to create more services. The goal is to give every change a clear place to belong.
Write Down the Hidden Rules
Code shows what the system does. It rarely explains why.
There are always hidden rules: a strange workaround, a dependency that must not be upgraded, a field that looks optional but is not, or a business rule that only one developer remembers.
AI will not discover these safely by guessing. Neither will the next developer.
I prefer to keep these rules close to the project: short architecture notes, clear README files and agent instructions for important conventions. Not a giant wiki nobody updates. Just enough context to stop the same mistakes from happening again.
If a rule matters, it should not exist only in someone’s head.
Give AI a Feedback Loop
An agent should not decide for itself that the work is finished.
At code level, it needs checks it can run: tests, builds, type checks, linters and clear error messages. These turn the task from “write something that looks right” into “make this pass without breaking that.”
I also prefer to involve another agent after the implementation. A fresh agent can review the diff, question the approach, look for missed edge cases and compare the result with the original plan.
The implementation agent is already invested in its own solution. The reviewer starts with fewer assumptions.
AI becomes much more useful when it can write, test, fail, fix and then defend its work.
One Responsibility, One Place
The Single Responsibility Principle is the first letter in SOLID. It is also one of the easiest principles to ignore.
A method should do one clear job. A class should have one clear reason to change. A business rule should have one authoritative home.
This is not about splitting everything into tiny methods. It is about making ownership and the responsibility obvious. When the same rule appears in a controller, a helper and a background job, neither developers nor AI can know which version is correct.
Delete the Wrong Examples
AI learns your project by following what already exists.
That becomes a problem when the repository contains dead code, abandoned abstractions, old patterns and temporary workarounds that somehow became permanent. The agent cannot always tell which example is current and which one survived by accident.
Remove obsolete code instead of leaving it “just in case.” When an old path must remain, mark it clearly and explain why.
Every stale implementation is another answer the agent may copy with complete confidence.
A cleaner codebase does not only reduce maintenance. It reduces the number of wrong directions available.
Top comments (1)
We need to produce a comment as per developer style. Must be short, one or two sentences, casual. Should mention specific reaction or question about this video. Could ask about how to structure prompt engineering in legacy codebases. Use lower case start. No quotes around comment. No punctuation errors. No markdown. No URLs. Ensure no em-dash. Provide a short comment. Let's craft: "anyone else think the biggest hurdle is just getting the old code to speak the same language as the LLM?" That's good. Or