Your Codebase Is the Prompt: Why AI Thrives in Some Projects and Fails in Others

There's an old joke among developers: "When I wrote this code, only God and I knew how it worked. Now only God knows."

The reason this joke is funny is that it nails a project every one of us has run into—the code runs, but only the lead developer truly understands it. All those decisions, exceptions, and unwritten rules live in his head. Over time, the developer himself becomes the codebase.

This has long been a familiar problem for dev teams. But coding agents have it worse: if another human developer can't figure out where code should live, why it's designed that way, or what change will break things, AI faces exactly the same dilemma.

Rather than discussing "how to make AI better at writing code," let's flip the perspective: the codebase itself is the prompt given to AI. When the prompt is clear, AI swims effortlessly; when the prompt is chaotic, AI can only guess. The habits below aren't new inventions of the AI era—they're existing engineering practices whose cost of absence balloons the moment you bring AI into the picture.

AI Can't Execute a "Vibe"

What AI does best is execute work that's already clear.

If you show up at your desk in the morning and just say, "Let's optimize some stuff," then make decisions as you go, the agent has nothing solid to follow. It can generate code, but it can't decide for you what the product should do, what's in scope, or which trade-off you actually want.

The author's approach: before letting a coding agent start, discuss the task with another AI first. Define the problem clearly, challenge the approach, consider edge cases, break the work into explicit steps. Then have it 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. Don't expect a coding agent to do product planning, architecture design, and full implementation all at once from a vague sentence.

A vague task doesn't give the agent freedom—it gives it permission to guess.

Make the Project Predictable

A well-structured project shouldn't surprise you.

When you first open a codebase, you should be able to roughly guess where business logic, validation, API calls, views, and shared utilities live. The same kind of work should follow the same patterns throughout the project.

If one validation rule is in the controller, another is in a helper, and a third is buried in the view, the structure has already failed. True, AI can search the entire repository—but that doesn't mean it has to.

Predictability reduces the amount of context the agent needs, and it lowers the odds of putting the right code in the wrong place.

The goal isn't a clever, fancy directory structure—it's a boring but consistent one, which usually works better anyway.

Isolate Domain Boundaries Early

A project becomes hard to understand when unrelated business domains start bleeding into each other.

Payment logic shouldn't quietly depend on notification logic, and user management shouldn't know how reports are generated. Each domain needs clear ownership, limited responsibilities, and an explicit way of communicating with other systems.

This matters even more for AI. The smaller the boundaries, the less context the agent needs, and the lower the chance it modifies the wrong thing outside the task.

The author favors microservices because they make these boundaries harder to ignore—each service owns its logic, data, and communication contracts.

But the goal isn't to create more services—it's to give every change a clear home.

Conway's Law, proposed by programmer Melvin Conway in 1968, states that any organization designing a system will produce a system structure that closely mirrors the organization's own communication structure. This means that if a team is divided by function (frontend, backend, database), the architecture they design is likely to be layered by technology; if the team is divided by business domain (payments, users, reports), the architecture is more likely to show clear domain boundaries. This law applies equally to AI collaboration: when a codebase has blurry boundaries and overlapping responsibilities, it usually reflects that the team's own communication never drew domain lines clearly. An agent has no organizational memory—it can only read code—so it receives less boundary information than a human developer. If you want AI to make fewer mistakes, first have the team clarify at the organizational level "who owns which business," and the domain boundaries in the codebase will naturally become clearer.

Write Down the Hidden Rules

The code shows what the system does, but it rarely explains why.

There are always hidden rules: a strange workaround, a dependency that must never be upgraded, a field that looks optional but is actually required, a business rule only one developer remembers.

AI won't safely discover them by guessing, and neither will the next human developer who takes over.

The author prefers keeping these rules close to the project: short architecture notes, clear README files, and agent instructions for important conventions. Not a giant wiki nobody maintains—just enough context to stop the same mistake from happening again.

If a rule matters, it shouldn't live only in someone's head.

In software engineering, this kind of knowledge that was never formally documented and only spread by word of mouth is called tribal knowledge. It typically includes: why a dependency is locked to an old version, why a field looks redundant but must never be deleted, why a piece of code uses a strange regex instead of a standard parser. Tribal knowledge is highly efficient for small teams in the short term, because veterans can answer questions on the spot; but its cost multiplies quickly with turnover and time—newcomers take weeks or even months to rebuild that understanding, and AI agents can't acquire it at all by "asking a colleague." The more insidious risk is that when the developer who holds this knowledge leaves, the codebase doesn't throw an error—but bad changes quietly pile up. The remedy is to "externalize" tribal knowledge into architecture decision records (ADRs) in the repo, README notes, or agent instruction files, turning critical rules into searchable, AI-readable first-class citizens.

Give AI a Feedback Loop

An agent shouldn't decide on its own that "the work is done."

At the code level, it needs runnable checks: tests, builds, type checking, linters, and clear error messages. These turn the task from "write something that looks right" into "make this pass, and don't break that."

The author also likes to bring in another agent after implementation is complete. A fresh agent can review the diff, challenge the approach, hunt for missed edge cases, and compare the result against the original plan.

The implementing agent is already invested in its own solution, while the reviewer starts with fewer assumptions.

AI becomes truly useful when it can write, test, fail, fix, and defend the result.

Type checking and linting are the cheapest, fastest layer of the feedback loop. Type checking verifies that the types of variables, parameters, and return values are consistent before compilation or execution, catching a large number of interface misuses before the code even runs; lint tools use static analysis to find pattern problems like unused variables, suspicious null handling, and style violations. Compared with unit tests, they don't need to run full business logic, so the feedback cycle is measured in seconds—ideal for an agent to self-check immediately after every change. For AI, the value of these two tools isn't just "finding errors"—it's providing a clear, parseable signal: the agent doesn't need to understand the whole system; it just reads the error message and knows whether its change crossed a line. The shorter and more deterministic the feedback loop, the lower the iteration cost of the agent's self-correction, gradually converging "write something that looks right" into "make all the checks pass."

Single Responsibility, Single Place

The Single Responsibility Principle is the first letter in SOLID, and one of the most easily overlooked principles.

A method should do one clear thing, a class should have one clear reason to change, and a business rule should have one authoritative home.

This isn't about splitting everything into tiny methods—it's about making ownership and responsibility obvious at a glance. When the same rule appears in the controller, a helper, and a background job all at once, neither the developer nor the AI can tell which version is correct.

SOLID is an acronym for five principles in object-oriented design, popularized by Robert C. Martin: the Single Responsibility Principle (S), the Open-Closed Principle (O), the Liskov Substitution Principle (L), the Interface Segregation Principle (I), and the Dependency Inversion Principle (D). The Single Responsibility Principle is most easily misunderstood as "a class does only one thing," but the more accurate formulation is "a module should have only one reason to change"—that is, its responsibility boundary is defined by who would ask it to change. When a business rule exists in the controller, a helper, and a background job at the same time, any requirement change forces the developer to modify it in multiple places, and consistency is hard to guarantee. For AI, this duplication is disastrous: the agent can't tell which location is the authoritative version, and it easily changes one and misses the others, producing an implementation that looks correct but is actually fractured.

Delete the Wrong Examples

AI learns your project by following what already exists.

Problems arise when the repository is stuffed with dead code, abandoned abstractions, old patterns, and temporary workarounds—workarounds that, through some twist of fate, became permanent solutions. The agent can't always tell which example is current and which merely survived by accident.

Rather than keeping things "just in case," delete outdated code. If the old path must stay, label it clearly and explain why.

Every stale implementation is another answer the agent might confidently copy wrong.

A cleaner codebase not only reduces maintenance cost—it also reduces the number of ways to go wrong.

Looking at these points together, the logic is consistent: the ceiling on AI's code writing often doesn't depend on the model itself, but on how well your codebase is written as a "prompt." If product and engineering teams want coding agents to deliver real value, rather than chasing the latest model, they should first go back and repair the engineering foundations that have been neglected for years.

One-line Summary

The codebase itself is the prompt given to AI—engineering foundations set the ceiling on agent performance.

Paragraph Summary

The article proposes a core perspective: instead of agonizing over how to make AI better at writing code, treat the codebase itself as the prompt given to AI. When the prompt is clear, AI swims effortlessly; when it's chaotic, AI can only guess. From this, the author lays out seven engineering practices: use another AI to think the task through clearly before letting a coding agent execute; make the directory structure predictable—boring but consistent; isolate domain boundaries early; write rules hidden in developers' heads into READMEs or architecture notes; build a feedback loop for AI from tests, builds, and type checking, and bring in an independent review agent; stick to single responsibility so each kind of work has one authoritative home; and delete dead code and outdated examples so the agent doesn't copy the wrong answers. The conclusion: the ceiling on AI's code writing often doesn't depend on the model itself, but on how well the codebase is written as a "prompt."