Vibe Coding Bible: Rethinking Software Architecture for AI-Generated Code
For the last year I noticed something consistent while working with AI-generated code.
The more I used AI to write code, the more my systems started to break in a very specific way:
- small changes caused unexpected side effects
- refactoring became increasingly risky
- context grew until it became difficult to manage
- AI sometimes “helped” by breaking nearby modules
- fixing one thing often broke something else
At some point I stopped thinking of this as a prompt engineering issue.
It felt more like a fundamental mismatch in the programming model itself.
The core mismatch
Most software architecture today is built around one assumption:
humans are the primary authors of code
We expect that:
- humans can understand the system over time
- humans can safely refactor large dependency graphs
- humans can maintain mental models of complexity
- humans can coordinate changes across modules
This works reasonably well when humans are the main drivers of development.
But with LLMs involved, a different behavior emerges:
every interaction effectively starts from a partial or reconstructed context
Even if the full codebase exists, the model operates with limited visibility at any given moment.
As systems grow, this leads to predictable patterns:
- increasing coupling
- fragile refactoring
- hidden dependencies
- loss of global consistency
The idea behind Vibe Coding Bible
This led me to a different question:
What if we design software assuming AI is the primary code author, and humans are system designers?
That shift changes many assumptions.
Some familiar practices start to behave differently:
- flexible interfaces become harder to reason about
- deep abstraction layers introduce fragility
- refactoring increases cognitive cost
- shared mutable structures amplify unexpected behavior
Core principle: nailed interfaces
The central idea is simple:
interfaces should not evolve
Once defined:
- they are never modified
- they are never extended
- they are never refactored
If requirements change, we do not modify the interface.
We create a new block with a new interface.
Even if it feels redundant.
Because AI makes duplication cheap — but coupling remains expensive.
Block structure
Every unit of code is a block:
-
interface.py→ immutable contract -
implementation.py→ AI-generated logic -
tests.py→ optional generated tests
Key rule:
the interface is frozen forever
No exceptions.
Tree instead of graph
Most real-world systems naturally evolve into dependency graphs:
- modules depend on each other
- dependencies spread in multiple directions
- small changes produce system-wide effects
In AI-heavy development, this becomes especially unstable.
So instead we enforce a simpler structure:
- strict tree hierarchy
- level-based imports only
- no cross-branch dependencies
- no lateral coupling
This is not elegant.
But it is predictable.
And predictability matters more than flexibility when AI writes most of the code.
No refactoring rule
In this model:
If something is wrong:
- we do not refactor it
- we replace it
If behavior changes:
- we do not extend existing modules
- we create new ones
If an interface no longer fits:
- we do not modify it
- we define a new block
At first this feels inefficient.
But the cost model shifts:
- writing new code is cheap
- managing coupling is expensive
So we optimize for regeneration instead of evolution.
What changes for developers
In this model, developers stop being:
- refactorers
- dependency graph managers
- large-codebase navigators
And become:
- system decomposers
- interface designers
- constraint engineers
- AI operators
The job shifts from writing code to shaping boundaries.
Migration strategy
Existing systems are not migrated directly.
Instead:
- freeze problematic modules
- stop modifying legacy code
- build new AI-native blocks alongside it
- gradually shift functionality over time
Legacy code becomes background context, not something to constantly fix.
This is not a universal rule
This is an experiment.
It may not apply to all systems.
Some domains may still require:
- complex shared state
- deep optimization
- tightly coupled systems
But in many AI-heavy workflows, traditional assumptions start to break down.
Why I’m writing this
I call this experiment:
Vibe Coding Bible
It is not a finished framework.
It is a set of assumptions I am testing in practice.
Related projects
Programming paradigm for AI-written software:
https://github.com/evgeniykormin86-stack/Programming-Paradigm-for-AI-Written-SoftwareIncident-driven AI system (Golden Armada):
https://github.com/evgeniykormin86-stack/golden_armada
Final thought
The question I’m exploring is simple:
What does software architecture look like when AI becomes the primary programmer?
This is one possible answer.
Not the final one.
But a starting point.
Top comments (8)
in simple terms, we need clear and maintained guidelines (copilot.md etc.) for AI to follow when authoring code - one that meets all the design, architectural, performance and safety concerns
I started from exactly this direction — trying to control AI-generated code through a well-maintained set of rules: architecture guidelines, style constraints, safety policies, and decision heuristics (something like a copilot.md for the whole system).
In practice, this approach does not scale the way it initially seems.
What actually happens
As the system grows, the “rule layer” itself starts to become a second system:
rules accumulate over time
exceptions are added for edge cases
guidelines begin to overlap and contradict each other
you introduce meta-rules about when to apply other rules
Eventually, you don’t just manage code anymore — you manage interpretation of rules.
The core issue
control shifts from code execution to rule interpretation
And that is where things start to degrade:
conflicting instructions become inevitable
decision boundaries become unclear
behavior becomes harder to reproduce consistently
system understanding depends on context-sensitive interpretation of documentation
At that point, the rules no longer simplify the system — they become part of its complexity.
Key insight
The problem is not lack of rules, nor poor rule quality.
The problem is that instruction-based control does not scale at the same rate as AI-driven system evolution.
The more powerful the generation capability becomes, the faster the rule layer turns into a brittle abstraction layer.
Why this matters for Golden Armada
Golden Armada takes a different approach.
Instead of trying to constrain behavior through increasingly complex instructions, it shifts control into:
structured operations
strict contracts
traceable execution flows
observable system evolution
Core distinction
Rule-based control (copilot.md approach):
“how the system should behave”
Golden Armada approach:
“what the system actually did, and how it got there”
Final thought
Rules are still useful — but at scale, when AI becomes the primary source of change, instruction-based governance tends to degrade faster than it can stabilize the system.
At that point, control needs to move from describing behavior to observing and structuring execution itself.
Interesting ideas, you might be on to something ...
I genuinely wonder if the people who got into 'coding' or 'development' because they liked doing just that (to code, or to develop) will be "the same" people who like doing things in 'the new way', where AI writes most of the code ...
We're moving from being "bricklayers" to being "architects", but I cannot escape the feeling that we might lose part of the 'craft', and the enjoyment of doing it.
That being said, nobody's stopping us from still writing at least some of the code ourselves (unless the boss says we shouldn't).
P.S. what also puts me off a bit is the whole "non-deterministic" thing, not just when it's about AI for coding, but even more when we integrate AI into the "runtime" of our systems - LLMs are responsible to nobody and can basically do crazy stuff even when we told them not to ...
The unpredictability of it (which is of course the underlying reason why it's powerful) just gives me the heebie-jeebies, no matter how many "control layers" or 'harnesses' we build around it.
Then again, I'm a control freak and I guess it shows ;-)
I think that's actually where my view differs a bit.
I'm not sure programmers become less important. If anything, I think the abstraction layer moves up.
Historically we stopped writing machine code, then assembly, then a lot of boilerplate that used to be considered "real programming". Every step looked like a loss of craft at first.
What interests me is whether we're moving toward a world where programmers inherit from the program itself rather than from a collection of hard-earned tribal knowledge accumulated through years of debugging and refactoring.
In that model, the human is still in charge. The human defines the constraints, interfaces and architecture. The AI is just an implementation engine operating inside those boundaries.
Regarding unpredictability, I actually share that concern. A large part of the idea came from not trusting the model enough to give it unlimited freedom. The whole point of nailed interfaces and strict boundaries is to reduce the blast radius when the model inevitably does something strange.
Yeah good points, I think I basically agree, I guess it's just the transition phase that generates the 'mental friction' :-)
I think the underlying premise of what you’re trying to document and curate is actually rooted in a software engineering methodology that has existed for decades.
You asked:
“What if we design software assuming AI is the primary code author, and humans are system designers?”
My view is that this model already existed - replace AI with junior or intermediate software developers, and replace humans with Software or Solution Architects.
The architect’s responsibility has always been to conceive the system, define its boundaries, establish how the different moving parts interact, and ensure that the whole delivers the intended business outcome. Developers then implemented that design.
Software engineers were never valuable simply because they could write code. Code was only the implementation layer. Their real value has always been their ability to take an ambiguous problem, model it as a system, decompose it into coherent components, define the interactions between those components, and then implement that design in code so that the system behaves predictably.
AI hasn’t fundamentally changed that responsibility - it has simply accelerated the implementation phase.
The challenge today is that while AI can generate code remarkably well, it does not naturally maintain a consistent mental model of an entire system over long periods of development. That responsibility still belongs to the human.
This is exactly where modular system design becomes even more important than before.
A module is far more than just a folder or namespace. It is an encapsulated collection of concepts, business rules, and actions that together deliver a specific business capability or outcome. Once software is designed around these clear boundaries, AI becomes significantly more effective because each piece of work has well-defined context and responsibilities.
This is also why I believe a Modular Monolith is the best default architecture for the vast majority of products today. It gives you the architectural discipline and separation of concerns that AI benefits from without introducing the operational complexity that comes with distributed systems like microservices before they’re actually needed.
In many ways, a lot of what you’re describing already exists within software architecture. What’s changing is that many people outside software engineering are now discovering these concepts because AI has made software creation more accessible.
Ironically, I think that makes experienced software engineers more valuable, not less. The fundamentals of software design, system thinking, architecture, modularity, and decomposition become even more important when the person writing most of the code is an AI model.
This is actually the thinking behind my own AI-assisted development framework, which I call the 3FS Framework.
The core thesis is that the biggest weakness of AI agents isn’t code generation - it’s context rot.
As conversations become longer, AI gradually loses the continuity that human engineers naturally maintain. That leads to architectural drift, unnecessary refactoring, contradictory implementations, and “fixing” things that were actually intentional design decisions.
To address that, my framework deliberately separates context into three layers:
Every time the AI begins work, it is effectively “reoriented” with these three layers so it understands not only what it is building, but why previous decisions were made and where the current work fits into the larger architecture.
I think you’re exploring an important space, and whatever you build will probably help a lot of people - especially those who are currently relying on AI for software development.
That said, I personally think the era of pure “vibe coding” is already coming to an end.
Without proper architecture, modular boundaries, and context management, the problems you’ve identified become inevitable. Developers end up spending more and more time - and money - trying to prompt AI into correcting issues that stem from missing context rather than missing capability.
The models will continue to do what they have always done: produce highly capable but fundamentally probabilistic outputs.
The quality of the software will increasingly depend not on the prompts themselves, but on the systems, architecture, and guardrails that surround those prompts.
I actually agree with most of what you're saying.
I don't think AI suddenly made architecture, modularity, decomposition, or system thinking irrelevant. Quite the opposite.
My question is whether the assumptions under which those practices evolved are still valid.
Historically, architects and senior engineers had time to absorb change because implementation itself was expensive. Writing a meaningful module could take days. During those days people discussed trade-offs, reviewed designs, discovered hidden dependencies, changed their minds, and gradually built a shared mental model of the system.
Today implementation is approaching zero cost.
The part that didn't accelerate is understanding.
A team lead can still spend two days understanding the consequences of a change. An architect can still spend a week evaluating trade-offs. The system still requires the same reasoning effort.
The difference is that the implementation can now appear in 15 seconds.
That's the gap I'm interested in.
I don't think modularity solves it completely. In fact, I think modularity is one of the guardrails we already discovered decades ago. The reason I'm exploring this space is because I suspect we need additional guardrails that operate above the code level.
When a senior engineer reviews a merge request, they are not really reviewing lines of code. They are evaluating hidden concepts:
Those concepts exist today, but mostly inside people's heads.
The question I'm trying to answer is whether some of those signals can be extracted, measured, tracked, and used as explicit system constraints.
Not because architecture is wrong.
Because implementation speed has become so high that human understanding is becoming the bottleneck.
So I think we agree on the fundamentals.
Where I may differ is that I believe we're entering a period where engineering moves one abstraction level up again. Not away from architecture, but from architecture toward measurable system evolution and consequence management.
I don't know yet whether that's true. That's what I'm trying to test.
You have just described the Clean Architecture from Bob Martin, or something very similar to it. Anyway, great finding!