Vibe Coding Bible: Rethinking Software Architecture for AI-Generated Code
For the last year I noticed something consistent while working...
For further actions, you may consider blocking this person and/or reporting abuse
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 mostly agree with you — this isn’t a new idea in the sense that architecture, modular design, and system thinking already exist. That’s exactly what senior engineers and architects do.
The difference I’m exploring is not who does it, but where it lives.
Today most of that reasoning exists in human heads, meetings, and documents, while code remains the only structured artifact the system can actually operate on.
What changes with AI is that we can potentially externalize parts of that architectural reasoning into a structured, machine-readable context model — not just diagrams or docs, but something the system can validate, compare, and evolve.
So it’s less “new architecture” and more “making architecture operational and explicit.”
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.
That is spot on.
The real work has moved up the stack. It now happens at the definition stage, not the implementation stage.
My workflow looks something like this:
Feature idea
→ Deeply analyse what it is trying to solve
→ Identify dependencies, constraints, edge cases, and impacts on existing systems
→ Document architectural decisions and trade-offs
→ Generate a PRD
→ Vertically slice the PRD into small, independent issues that AI can execute
That definition phase is where the engineering happens.
Ironically, my software architecture experience has become even more enjoyable in the AI era. Instead of spending hours writing code, I spend that time exploring ideas with AI, stress testing assumptions, uncovering edge cases, and evaluating different architectural approaches. AI expands my thinking, but I still decide what belongs in the MVP versus what should wait for a production-ready system.
Everything is documented inside the codebase, version controlled, and written as a proper engineering handoff so another engineer, or even the next AI session, can continue with full context.
I'm also redesigning my development workflow to capture DORA metrics so I can measure both my own performance and the team's as AI becomes an integral part of the software development process.
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' :-)
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.
A paradigm for AI-written software is the right ambition, and the chapter that decides whether it holds is the one on coherence. Generating a working app prompt by prompt is the part AI does well; the failure shows up when the tenth prompt needs to inherit the same constraints as the first and there's no design holding them together. A paradigm worth the name has to answer where the cross-cutting decisions live, the ones no single prompt should be free to contradict, because vibe coding without that produces ten locally-reasonable pieces that don't add up to a system. The discipline isn't more careful prompting, it's holding the durable decisions somewhere stable so generation inherits them instead of re-deciding them each time. Coherence is the thing prompt-by-prompt can't produce on its own.
You have just described the Clean Architecture from Bob Martin, or something very similar to it. Anyway, great finding!