Design-First Vibe Coding: Making AI Work at Enterprise Scale
The Promise and the Reality of Vibe Coding
When AI-assisted coding tools first emerged, they fundamentally changed how developers write software. They accelerated implementation, reduced repetitive coding, and made it remarkably easy to turn ideas into working code.
We saw AI-assisted development as an opportunity to improve the way we build software and, ultimately, deliver greater value to our customers. We quickly adopted AI agents such as GitHub Copilot to help developers implement user stories faster and support developers across the full spectrum of engineering work.
At first, everything worked as expected. So, we scaled it across systems.
In large enterprise environments such as banking, government, telecommunications, and insurance, speed is only one measure of success. Software must also be consistent, secure, maintainable, auditable, and aligned with well-defined architectural standards. As we expanded the use of AI across larger enterprise systems, we discovered that unconstrained vibe coding introduced a new challenge: consistency.
The same user story, implemented twice by the same AI agent, could produce two noticeably different designs. We realized that scaling AI-assisted development wasn't simply a matter of creating better prompts. We needed a different approach..
One principle never changed: design ownership and final accountability always remain human. AI accelerates software delivery, it does not replace engineering responsibility.
Our First Attempt at Control: Repository-level Instructions
We introduced markdown-based instruction files inside each repository, capturing:
- High-level architectural principles
- Low-level design constraints
- Business rules and domain context
- Coding standards and conventions
This immediately improved results. Generated code became:
- More accurate
- Better aligned with the microservice design
- Easier to review and integrate
For a while, this felt like the right answer.
The Scalability Problem
Whenever we introduced a cross-cutting architectural change, for example:
- A new error-handling strategy
- Updated logging or auditing requirements
- Changes to integration patterns
We had to update every instruction file in every repository and over time, aditional issues started to appear
- Repositories slowly drifted out of sync
- Subtle differences emerged in what were supposed to be “shared” guidelines
- Ensuring consistency across teams became increasingly difficult
At that point, we knew we needed something more structural than better prompts or stricter discipline.
A Key Insight: Architecture Must be Machine-Consumable
Traditionally, architecture documentation is written for humans.
AI agents, however, need architecture that is centralized, versioned ,discoverable and Queryable at runtime.
We stopped trying to embed architecture into prompts and instead asked a different question, What if AI agents could fetch architecture the same way services fetch configuration?
Introducing the Architecture MCP Server
We created a dedicated architecture Git repository per project, containing:
- High-level design (HLD)
- Low-level design (LLD)
- Service-specific documentation
- Architecture and sequence diagrams (PlantUML, Draw.io)
On top of that repository, we built an Architecture MCP Server.
Its responsibility is intentionally simple:
- Sync architecture artifacts from Git
- Expose them to AI agents on demand
GIT remains the source of truth. The MCP server becomes the bridge between design and AI-assisted implementation.
A Design-First Approach
Diagrams matter, but they are only one expression of the design.
What we practice is a design-first approach, where the following are treated as first-class inputs to AI agents:
- Architectural principles and constraints
- Service responsibilities and boundaries
- Interaction flows
- Business rules
- Coding standards
Design-first vibe coding means architecture, design artifacts, and business rules are mandatory inputs to AI agents, not optional documentation for humans.
From Principle to Practice
Reframing architecture as a mandatory, machine-consumable input is what transformed AI-assisted development into a predictable, architecture-driven delivery model. It allowed us to preserve the speed of vibe coding while restoring the consistency, governance, and architectural discipline that enterprise software demands.
Throughout this journey, one principle remained unchanged: AI accelerates software delivery, but design ownership and engineering accountability always remain human.
If you're ready to move from the concept to the implementation, the companion article, Design-First Vibe Coding: The Implementation Guide, walks through how to put the design-first approach into practice.
