Optimize Your Codebase for AI Coding Agents
TL;DR: Quick Answer If your codebase doesn't contain the exact nouns and verbs you use to prompt your AI coding agent, the agent will do a much worse job. By ensuring your code reflects your spoken domain language, agents can map instructions directly to components, preventing them from generating messy, monolithic scripts.
If you're using a coding agent and your codebase does not contain the nouns and the verbs that you use to prompt the agent with, your agent will do a worse job. Period. I see this happen all the time. What do I mean by this? Let's say you're building a system that sells t-shirts online. You've got a bit where you have to take payment by calling a payment processor, a bit to update an order in a database, and a bit to send a message to a warehouse to ship the item.
Why do AI coding agents write monolithic scripts instead of modular code?
AI agents write monolithic scripts because they lack clear semantic hooks in your existing codebase. If your code doesn't explicitly define the business concepts you are prompting for, the agent defaults to a procedural list of database updates and API calls to satisfy the request.
As I'm describing that t-shirt store flow above, there are some clear nouns in there: order, payment processor, warehouse. There are also some verbs: take payment, create order, send message. I want to stress that you want all of these things to exist in your codebase as named verbs and nouns. If you just prompt an agent to build the system for you without any of that semantic structure already in place, you'll just get a long script. The AI will just make a raw API call, create a row in a database, and send a message all in one file. You won't have any of these concepts properly modeled.
How do nouns and verbs improve AI coding agent accuracy?
Explicit nouns and verbs allow the agent to map human-language prompts directly to specific classes and methods. When your prompt matches the structural language of your codebase, the AI understands your intent by conceptual analogy rather than just blindly grepping for syntax.
Think about what happens when you have all of these concepts written as first-class systems. The next time you prompt the agent—because you prompt it with human language, using nouns and verbs—you might say something like: "Every time taking a payment fails, roll the order back."
Because the structure is there, the agent is able to figure out, "Oh, you've prompted me with the noun order, and I can see in the codebase there's this thing called Order. You used the verb take payment, and there is a verb within this codebase called takePayment." It starts to search by analogy. This makes agents so much more effective at actually doing the thing you want it to do and not making mistakes.
// The agent can easily map natural language to this structure
class PaymentProcessor {
async takePayment(orderId) { /* ... */ }
}
class Order {
async create(items) { /* ... */ }
async rollBack() { /* ... */ }
}
What are the best naming conventions for AI coding agents?
The best naming conventions treat your business domain as first-class citizens in the code. You should align your variables, classes, and function names exactly with the plain-English vocabulary you use when describing features to your team or your AI tools.
If you're refactoring your codebase, remember that your biggest context is your codebase itself, and it should reflect the nouns and verbs that you use to prompt it. Here is how that translation looks in practice:
| Spoken Prompt Language | Poor Implementation (Procedural) | AI-Optimized Implementation (Nouns/Verbs) |
|---|---|---|
| "Take the payment" | await fetch('https://api.stripe.com/charge') |
paymentProcessor.takePayment() |
| "Create the order" | db.query('INSERT INTO orders...') |
order.create() |
| "Message the warehouse" | axios.post('http://warehouse/api') |
warehouse.sendMessage() |
If your current code looks like the middle column, you can ask an agent to refactor it into the format on the right. Once those nouns and verbs are established, every subsequent prompt will be drastically more accurate.
Frequently Asked Questions about AI Coding Agents
Does domain-driven design actually matter for AI?
Yes, absolutely. Domain-driven design (DDD) drastically improves AI coding assistants because it forces developers to use a ubiquitous language. When the codebase uses the same terminology you use in your prompts, the AI can seamlessly translate your natural language into the correct structural changes.
Why does my AI keep hallucinating functions that don't exist?
I usually see this happen when the agent understands your intent but cannot find the corresponding structural concepts in your codebase. If you ask an agent to "process a refund," but your code only has a generic database update query, the AI might invent a processRefund method because the noun and verb you prompted with were missing from the code entirely.
Can I just use an agent to fix my messy procedural code?
Yes, this is one of the highest-leverage ways to use an agent. You can prompt the AI to extract procedural scripts into dedicated classes and functions using specific nouns and verbs. Once refactored, the agent will have a much easier time navigating and modifying the code in the future.
