I use AI every single day. I’m not one of those „AI is a fad“ people standing on the sidelines with their arms crossed. I help my teams adopt it. I help them write better prompts. I sit with them and define what goes into their project-level system prompts. I’m a true believer.
And that’s exactly why I need to tell you where it falls apart.
we built the perfect system prompt
Here’s what we did on my teams. We sat down and codified everything a senior engineer would know into our project prompts. SOLID principles. Hexagonal architecture with ports and adapters. The exact testing libraries we use. Our folder structure. Our distributed system patterns. Saga pattern with choreography over orchestration. Outbox pattern for reliable event publishing. All of it.
In theory, this means every engineer on the team, regardless of experience level, produces the same caliber of code. The same architecture. The same patterns. The AI knows the rules, the engineer follows the output, and everyone ships clean, consistent software.
That’s the theory. Here’s what actually happened.
the 80% that looks amazing
I’ll give credit where it’s due. For roughly 80% of the work, this approach is genuinely impressive. A junior developer with our system prompt generates service scaffolding that follows hexagonal architecture. The ports are defined. The adapters are clean. The folder structure matches our conventions. The tests use the right libraries with the right patterns.
If you looked at any individual service in isolation, you’d think a senior engineer wrote it. The code is clean. The patterns are correct. The separation of concerns is textbook. A code reviewer scanning through a pull request would nod approvingly and hit approve.
This is the part that makes the whole thing so dangerous. Because 80% correctness with 100% confidence is worse than 60% correctness with appropriate doubt.
the 20% that burns your house down
Recently I saw it in the wild. A team had been shipping microservices for months using our system prompt setup. Each service individually looked great. Proper ports and adapters. Clean separation. All the right patterns.
But when you zoomed out? They had built a distributed monolith.
The microservices were coupled so tightly that you couldn’t deploy any of them independently. Service A called Service B synchronously during its startup sequence. Service C shared a database with Service D because „it was easier than setting up an event.“ Service E contained business logic that belonged in Service F, but nobody noticed because the code within each service was so cleanly structured.
The system prompt told the AI to use hexagonal architecture. It did. The system prompt said to use the saga pattern. It did. But nobody asked the right question: should this logic even live in this service?
what a senior engineer sees that the prompt can’t encode
A seasoned senior engineer spotted the distributed monolith within an hour of looking at the deployment topology. I spotted it too. Not because we memorized the rules better than the system prompt. We didn’t sit there cross-referencing SOLID principles against a checklist. We felt it.
You build this intuition after years of debugging production incidents at 2 AM. After inheriting a codebase that looked perfect in code review but collapsed under real traffic patterns. After watching a „simple deployment“ cascade into a four-hour outage because services that shouldn’t know about each other were secretly holding hands under the table.
The system prompt can tell the AI to use the outbox pattern. It can’t tell the AI that this particular piece of business logic is going to become a deployment bottleneck in three months when Team B needs to ship independently. It can’t tell the AI that the reason you separate these two bounded contexts isn’t because of some abstract principle, it’s because two years ago a similar coupling caused a week-long incident that cost the company real money.
Software engineering judgment isn’t a set of rules. It’s pattern recognition built on scar tissue.
compliance theater: too much and too little at the same time
Here’s the paradox I keep seeing. Engineers using AI with a well-crafted system prompt either comply too much or too little with the standards. Sometimes in the same pull request.
Too much compliance looks like applying hexagonal architecture to a 50-line utility service that will never change. Three layers of abstraction for a function that reads a config value. Ports and adapters for something that should have been a simple script. The AI follows the rules because the rules say to follow them. A senior engineer would say „this doesn’t need all that ceremony“ and write it simply.
Too little compliance looks like taking the AI’s suggestion to „just call this other service directly“ because the prompt didn’t explicitly cover this specific inter-service communication pattern. The AI generated clean code. It even put it behind a proper interface. But the architectural decision itself was wrong, and nobody caught it because the code looked right.
The result? Teams create architectures they don’t fully understand. They can’t debug them effectively. They can’t evolve them when requirements change. They’re operating machinery they didn’t build and can’t repair.
the distributed monolith problem in detail
Let me be specific about what went wrong with the distributed monolith, because it’s a textbook case of the dangerous middle ground.
The deployment problem was the first symptom. You couldn’t deploy Service A without also deploying Service B and Service C. In a proper microservice architecture, that’s a fundamental failure. The entire point is independent deployability. But the code within each service was beautiful. Clean interfaces, proper dependency injection, solid test coverage.
Then came the parallelization problem. Because the services were coupled, teams couldn’t work independently. A change in Service A required coordinating with the team that owned Service B. Sprint planning turned into a negotiation exercise. The thing that microservices are supposed to solve, independent team velocity, was completely broken.
And here’s the killer: the maintenance cost. When you have logic in the wrong service, every bug fix becomes an archaeology expedition. You trace a problem to Service E, but the root cause lives in Service F. Except nobody documented why that logic ended up in Service E in the first place, because the AI just put it where the prompt told it to, and the prompt didn’t know about the organizational boundaries between teams.
what the system prompt can’t contain
I’ve spent a lot of time thinking about why system prompts hit this ceiling. You can encode principles. You can encode patterns. You can even encode specific architectural decisions. But you can’t encode:
Context that spans the entire system. A system prompt operates at the service level. It doesn’t know about the other 15 services in your ecosystem, their deployment schedules, their team ownership, or their runtime dependencies. Architectural decisions that are correct in isolation can be catastrophic in context.
The „why“ behind the rules. The system prompt says „use the outbox pattern.“ But why? Because you’ve been burned by dual-write failures in distributed transactions. That experience, that burned-in-memory feeling of watching data go inconsistent at scale, is what makes a senior engineer reach for the outbox pattern at the right time and skip it when it’s unnecessary overhead.
Trade-off instincts. Every architectural principle has a cost. Hexagonal architecture adds indirection. The saga pattern adds complexity. Event-driven systems add debugging difficulty. A senior engineer knows when the cost isn’t worth paying. The system prompt treats every principle as equally important all the time.
Organizational awareness. Where should this code live? That’s not a technical question. It’s an organizational one. Which team will maintain it? What’s their deployment cadence? Who gets paged when it breaks? The system prompt has no idea.
so what do we actually do about it?
I’m not saying throw away your system prompts. Mine are still some of the most valuable engineering documents my teams have. But treat them like guardrails, not autopilot.
First, invest in architectural reviews that zoom out. Individual code reviews catch syntax and pattern issues. You need reviews that look at how services interact, where boundaries are drawn, and whether the overall system topology makes sense. This is a senior engineer’s job and it can’t be automated away.
Second, make your juniors understand the „why“ behind every principle in your system prompt. Don’t just tell them to use ports and adapters. Show them what happens when you don’t. Let them debug a tightly coupled system. Let them experience the pain that created the rule. Without that experience, they’re following a recipe without understanding cooking.
Third, accept that AI with a system prompt is a powerful tool for implementation, not architecture. Let it scaffold services, write boilerplate, generate tests, implement well-defined features. But the decisions about what to build, where it lives, and how it connects to everything else? That’s engineering. That’s human. And that’s not going away.
the real skill gap
The dangerous middle ground exists because we confused knowing the rules with understanding engineering. A system prompt can make anyone produce code that follows SOLID principles. But SOLID principles are the vocabulary of software engineering, not the fluency.
Fluency is knowing that the saga pattern is the right choice here but overkill there. That this service needs hexagonal architecture but that one is fine as a simple script. That these two bounded contexts must be separated not because of any technical principle, but because two different teams need to ship on different schedules and you learned that lesson by living through the alternative.
AI is the most powerful tool I’ve ever used in my career. I will continue to champion it, teach it, and push my teams to use it more effectively. But the engineers who think a good system prompt replaces years of hard-won architectural judgment are building the next generation of distributed monoliths. They just don’t know it yet.
And by the time they figure it out, the deployment pipeline is on fire and the only people who can fix it are the senior engineers they thought they didn’t need anymore.