When a CTO tells me AI is generating mediocre code, my first question is no longer about the AI. It’s about the repository.
Think about the software engineering knowledge a modern language model can work with: Bertrand Meyer’s design by contract, Michael Nygard’s Architecture Decision Records, continuous integration as championed by Martin Fowler, Kent Beck’s TDD, Mike Cohn’s test pyramid, Alistair Cockburn’s hexagonal architecture, Robert Martin’s SOLID principles, and Michael Feathers’ work on legacy code.
We don’t know exactly which books went into each model’s training data. But these models can recognize and work with those concepts. For practical purposes, AI has already read all the books.
So why doesn’t the code it generates consistently reflect those practices?
The paradox: knowing isn’t applying
A model’s knowledge of a good practice doesn’t mean it will apply it. The result depends on the code it encounters, the instructions it receives, and the checks around it.
If your codebase is spaghetti with no recognizable patterns, AI won’t turn it into a clean architecture on its own. It may reproduce the inconsistencies already there, or come up with something that looks reasonable but doesn’t fit the rest of the system.
Andrew Hunt and David Thomas, the authors of The Pragmatic Programmer, popularized the idea of broken windows in software decades ago: disorder left unchecked invites more disorder. AI can accelerate that effect. When we generate code faster, we can accumulate inconsistencies faster, too.
The uncomfortable conclusion: the model is only part of what determines quality. The engineering discipline around it matters, too.
Good practices were always for the next reader
Design patterns, Clean Code, hexagonal architecture, and SOLID aren’t just matters of style or rules to follow for their own sake. Much of their value is in helping whoever comes next: the teammate who inherits a module, or our future selves six months from now, when we’ve forgotten how any of it works.
A recognizable pattern tells the reader where to look. It makes the author’s intent easier to follow and gives both people a shared way to reason about the code. We read code far more often than we write it. These practices help with that reading.
Now think of AI as another reader. Without persistent, accessible context, each new session is like a teammate’s first day: it doesn’t automatically know what happened yesterday. Clear responsibilities, explicit interfaces, and controlled dependencies make it easier to find its way and reduce the room for mistakes.
We’ve all seen the difference. A focused, loosely coupled module that fits on one screen is easier to understand and change with confidence. A module that does everything, imports dozens of functions with unclear purposes, and takes endless scrolling to follow makes mistakes more likely. It also makes us less confident in our changes.
Those same characteristics affect how reliably a model can work with the code.
The practices we use to help the next developer also give AI a clearer picture of the system.
Naming is part of programming
Here’s the first practical lever, and it costs very little: use a shared vocabulary with the model.
“Hexagonal architecture.” “Modules communicate through their interfaces.” “Test pyramid.” “Record this decision as an ADR.”
These terms compress decades of ideas and trade-offs into a few words the model recognizes. Naming an established pattern can be a more effective starting point than explaining it from scratch over several paragraphs.
That goes against a common instinct: relaxing engineering practices because AI lets us move faster. The more code we generate, the more explicit we need to be about how we want to build it.
AI can help us apply good practices, but we shouldn’t assume it will choose the right ones on its own. We need to name them, show what they look like in our codebase, and check the results.
We learned the limits of naming on an AI-maturity diagnostic product we build. Our standards file listed SOLID and hexagonal architecture with a note that the agent “knows them by name.” Over long sessions, those named-only principles were skipped silently. We kept the vocabulary, but moved the boundaries that matter into mechanical checks on imports and dependencies, and left AI review as a second pass. Naming gives the agent the starting point. Checks keep it there.
If it isn’t written down, AI has to guess
The second lever: record your decisions.
Well-structured code shows what a system does and how it’s organized. It doesn’t necessarily explain why one solution was chosen over another. Someone on the team may remember why you chose a particular database. A new AI session won’t have that context unless you provide it.
There’s no need to invent a new format. Michael Nygard described Architecture Decision Records (ADRs): short documents that capture the context of a decision, the alternatives considered, and the reasoning behind the choice.
You don’t need to document every detail. Focus on decisions someone is likely to question six months from now, especially those shaped by trade-offs involving budget, security, performance, or existing system constraints.
When that record is available to the AI, it gives each new session useful context. It also gives the team a decision history. If the person who remembers the reasoning leaves, the reasoning stays.
On a warehouse app for an ERP client, the agent built every workflow against a simulated backend. An audit later showed the code matched the simulation, not the client’s real API: different identifiers, different field names, writes that would never reach a real endpoint. Nothing in the repo said which contract was the truth. We added a snapshot of the real API specification as the oracle for contract tests, wrote the decision down as an ADR, and listed the open questions for the client instead of letting the agent fill the gaps. From then on, each fix started with a failing test against the real contract.
Advice doesn’t scale. Enforcement does.
The third lever, and the most important one: make the rules enforceable.
A style guide in a wiki is a recommendation. A test, linter, or quality gate that blocks a change when it breaks a rule is a mechanism.
Continuous integration has put this idea into practice for years: check early and surface problems before they spread. We can’t automate everything, but we can automate a lot: conventions, type checks, tests, dependency rules, and certain architectural boundaries.
On an internal recruiting tool, the risk that tests could touch the development database was documented. One day a test run’s cleanup cascaded and wiped the development data, while every test passed. Our own retrospective put it plainly: the risk was documented, not structurally blocked. Tests now run against a separate database instance, and the configuration makes the old path impossible rather than discouraged. On a client platform the owner put the same idea in one sentence: “a rule that no gate enforces is not a rule.” After the first feature queried the database straight from business logic, we added an architecture gate. Rewriting that code to pass it surfaced a real bug in the password-reset flow.
For what automated checks can’t catch, we still need human review. That’s the lesson behind Toyota’s andon principle: when a serious problem appears, stop and investigate instead of letting it keep moving down the line. The goal is to reserve the team’s judgment for the decisions that actually require it.
That changes the promise we’re making. Instead of “we trust AI to get it right,” it becomes “we’ve made certain mistakes harder to introduce without something catching them.”
Productivity is an outcome
What about speed, the reason many of us started using AI in the first place? The tool alone doesn’t guarantee it.
When code has a recognizable structure, important decisions are documented, and rules are checked automatically, AI has less to guess. It has a better chance of finding its way, proposing consistent changes, and getting early feedback when something doesn’t meet expectations.
Those conditions make productivity gains more likely. The quality of the environment matters as much as the capabilities of the tool working in it.
Where to start
You don’t need to transform the entire system in the first month. Start small:
- Give AI a map. Add a document at the root of the repository explaining what the system does, how it’s organized, and where to find things. Make sure your AI tools are instructed to read it. If a new teammate needs that map, an AI agent probably does, too.
- Choose your patterns and name them explicitly. In the code, in instructions, and in reviews. Shared vocabulary reduces ambiguity.
- Record the decisions that matter. Not every decision. Focus on the ones someone will question six months from now. A short ADR is enough.
- Automate one rule your team keeps breaking. Add a test or quality gate that catches a recurring problem. Give the team a useful first example to build on.
Then come the more interesting questions: how to organize that map so agents find the right context, how to connect the checks, and how to use each failure to improve the system. I’ll explore those in future posts.
Credit where it’s due
We didn’t invent any of this. That’s part of the point.
Meyer, Nygard, Fowler, Beck, Cohn, Cockburn, Martin, Feathers, Hunt and Thomas, Toyota: these ideas have been around for decades. As an industry, we’re familiar with them. We’re less consistent about putting them into practice.
Spec-Driven Development is one approach to making explicit specifications central to AI-assisted development. Our implementation is called Generative Specification (GS), formalized by Juan Carlos Ghiringhelli in his white paper on Zenodo, and we use it in our work.
With GS, we aim to turn engineering practices and decisions into explicit, verifiable rules that are hard to bypass, so quality depends less on someone, human or AI, remembering to follow them.
The practices were already there. The challenge is to make them part of how the work gets done.




























