Preparing Your Codebase for AI Coding Agents

Originally posted in Obics.io

The Brilliant New Hire With No Memory

While LLM coding agents are extremely smart, they are pretty stupid about your own project. They don’t know what your app is trying to do, the architecture, or anything really. It’s like a very smart software developer on their first day in the office. No matter how smart they are, they won’t contribute much in their first month of work because you need domain-specific knowledge. We don’t have a month with agents because each session starts with blank memories, but there are techniques to prepare your environment so that they will understand your domain on the go. As a result, you’ll eventually reach the point where you can prompt with business and product requirements as if you’re talking to an engineer that has been on the project for years.

Basic Instructions in CLAUDE.md/AGENTS.md

The easiest and first thing I’d start with is to populate CLAUDE.md/AGENTS.md with the basic architecture of your project. This is injected in every session, so it’s extremely important to get right, but also should be brief to minimize tokens. Describe your application’s business purpose, the role of the different services, directory structures, main flows of the application, etc. Or, you know, ask your agent to write that.

If you have a monorepo with multiple services in subfolders, add CLAUDE.md/AGENTS.md files in each service root. Those will be loaded when the agent works on the relevant service, so you can go into more detail about what the service does, the interaction with other services, message protocols, endpoints, kind of thing.

Database access

I can’t stress enough how meaningful it is to give your agent access to the database with a CLI or an MCP. Now, before you get all worked up about security, this doesn’t have to be the production database. It can be the staging or dev database. The important thing is that it has the same schema as production. The database tells the story of the relationships of your entities, which is invaluable for understanding the domain of your application.

Meaningful names in the database are more crucial now than before. In the new world, if a table was named “work”, you could ask the guy on the other side of the room what it’s for. The agent doesn’t have that capability. The popular agents like Claude Code and Codex decided to take the path of “grep” rather than RAG. That means that instead of maintaining a RAG-based knowledge base (like Cursor), they just “grep” for variable and function names that they guess might be relevant. Surprisingly, it works very well, but giving meaningful names is what makes this work well.

Preparing the Source code for an agent

The source code itself is obviously important, it’s the “ground truth” of your project. The best way to make agents work well is good structure of the code and good naming. The division of service and file responsibility is extremely important. If you mix and match functionality, the agent won’t find the right stuff or add a bunch of duplications. Get the file names, type names, and function names right. We already established that the agent doesn’t have access to the guy in the cubicle nearby, and for the most part it doesn’t have memory of previous sessions, so grep-ing for meaningful names is super important. It will also be much easier to set instructions for your agent when there are unique, ubiquitous names. For example, the following prompt is excellent: “in the feature Pandora, there’s support for GCP. add equivalent support for AWS”. If you have a unique feature name like Pandora, with services, files, and function names that include ‘pandora’, it will be very easy for the agent to find the right code, and for you to describe the right intent.

The book Domain-Driven Design (DDD) comes to mind as very relevant in this context.

Tests

The final thing I’ll mention is tests. Unit tests by themselves don’t contribute much to the agent’s understanding. They just double what the agent has to read and most likely it won’t bother to read them at all. End-to-end tests, however, besides being great for verification, allow the agent to understand main flows of your project without having to read the huge source code that runs during those tests. I myself mention them in CLAUDE.md instructions, along with a short description, but I don’t explicitly ask the agent to read the tests before doing a task.

Wrapping up

Good architecture, meaningful names, a database that tells a story, and end-to-end tests that capture your main flows are the same things that make a codebase pleasant for humans. But agents just raise the stakes. In a world where creating the right environment means the difference between a glorious auto-complete and a team of senior engineer you’re managing.