Repository navigation
Draft: A Software Engineering Framework for Enterprise‐Grade Code using AI Coding Agents
Achieving a 4x-5x Demonstrable ROI by "ANTI - Vibe Coding"
This is a detailed tutorial with real world citations from our live project where we moved beyond inconsistent, low-impact results to solid, production ready code. This is a concrete refutation of "vibe coding" paradigm. Our experience developing our open-source project demonstrates that a disciplined, software engineering-first approach is the key to unlocking dependable, high-quality output. By implementing a framework centered on "Context Engineering" — using GenAI to build robust specifications before coding, we transitioned from "hope for the best" to consistent, robust, production quality software implementations of even fairly complex features. This methodology compressed a ~100 person-day project into an estimated 15 person-days, demonstrating a tangible 5x ROI. This guide outlines our step-by-step framework for enterprise adoption.
Our journey with AI in development began with the "Coding Assistant" paradigm, using tools like GitHub Copilot, Codeium, and the original SourceGraph Cody.
Key Characteristics of Coding Assistants:
- Minimal Autonomy: The AI suggests code; the human drives the process.
- High-Frequency Human Intervention: Constant review and feedback are required.
- Sequential Workflow: Work is done one file or one discrete function at a time.
- Context Source: The primary context is the existing codebase, indexed by the assistant.
Diagram 1: The Traditional Coding Assistant Workflow
graph LR
User_Prompt[User Prompt] <--> Coding_Assistant
Coding_Assistant <--> genAI[genAI]
subgraph Coding_Assistant [Coding Assistant]
System_Prompt[System Prompt]
Indexed_Code[Selection from indexed code]
end
Observation: While useful, this approach yielded incremental gains. The quality was highly dependent on the tool's code-indexing capability, with tools like SourceGraph Cody showing superior performance due to their expertise in this area.
The Shift to Agentic Coding: In mid-2025, we re-evaluated the landscape and found that "Coding Agents" like Gemini CLI, JetBrains Junie, and Sourcegraph Amp had matured significantly. Unlike assistants that merely suggest code, agents can understand a high-level task, create a plan, and execute it across multiple files and steps with greater autonomy. This shift required a more robust methodology to manage their power and mitigate risks.
"Vibe coding" is the practice of giving a simple, high-level prompt to an LLM and expecting production-ready code. This approach fails in an enterprise context because LLMs lack business context, nuance, and an understanding of non-functional requirements.
The output of vibe coding is often:
- Functionally incorrect or irrelevant.
- Riddled with subtle bugs and security vulnerabilities.
- Devoid of enterprise-grade characteristics like modularity, maintainability, testability, and security.
Trying to build production systems with this method is a recipe for developer burnout and project failure.
To overcome these limitations, we developed a framework centered on a crucial, often-overlooked discipline: Context Engineering.
Context Engineering: The practice of systematically providing an LLM or AI Agent with comprehensive, precise, and multi-faceted information to ensure its output is accurate, relevant, and aligned with all project requirements.
Our intuition was simple: LLMs are not curious. LLMs have known limitations like context drift and hallucinations which are magnified in autonomous, multi-step agents. To mitigate known limitations, we must provide all the necessary context upfront.
Step 1: Use GenAI for Pre-Coding Requirement & Specification Generation Before writing a single line of code, we use LLMs as expert partners in product management and architecture. This compresses weeks of manual work into days. To eliminate ambiguity and create specifications that are both human-readable and machine-executable, we integrate Behavior-Driven Development (BDD). After a User Story is defined, we use BDD's Gherkin syntax (Given, When, Then) to write concrete scenarios that describe the system's behavior. These scenarios, saved in .feature files, become our living documentation and our formal acceptance criteria.
graph TD
subgraph Context_Engineering [Context Engineering / Pre-Coding Phase]
direction TB
Step1[Feature Overview]
Step2[GenAI-aided Research]
Step3[Conceptual Architecture]
Step4[Technical Architecture]
Step5[Epics]
Step6[User Stories]
Step7[BDD Scenarios - dot-feature files]
Step8[Tasks]
Step1 --> Step2
Step2 --> Step3
Step3 --> Step4
Step4 --> Step5
Step5 --> Step6
Step6 --> Step7
Step7 --> Step8
end
%% Styling to highlight the flow
style Step1 fill:#f9f9f9,stroke:#333,stroke-width:1px
style Step2 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style Step7 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
-
Output: We generate highly detailed specifications, supplemented with precise diagrams (which LLMs like Mermaid excel at):
- Requirements and Architecture Diagrams - Semantic Search with various illustrative diagrams - The Epics are linked at the bottom., Refactoring to create SDK, Better JS compatibility
- Sequence Diagrams
- State Diagrams and Flow Charts
- Benefit: This creates an unambiguous "source of truth" for both human developers and the AI Coding Agent.
Step 2: Structure Tasks as Unambiguous Instructions The detailed tasks generated in Step 1 become the primary input for the Coding Agent. Each task is self-contained and includes:
- A clear description of the goal.
- Relevant architectural context and diagrams.
- Precise, GenAI-generated "Acceptance Criteria."
- We found one redditor suggesting BDD/Gherkin files and decided to include this into our flow. (TBD: Need to adopt and link some of our gherkin files.)
Step 3: Execute with an Agentic Workflow With this rich context, the Coding Agent is no longer "vibing." It is executing a well-defined engineering plan.
Diagram 2: The Engineered Agentic Workflow
graph LR
subgraph Inputs
direction TB
Specs["Specs, Diagrams, BDD,<br/>Acceptance Criteria"]
User_Prompt[User Prompt aka github task]
AgentsMD[AGENTS.md]
ConventionsMD[Conventions.md]
end
subgraph Coding_Agent [Coding Agent]
System_Prompt[System Prompt]
Indexed_Code[Selection from indexed code]
Agentic_workflow[Agentic Workflow]
end
Specs --> Coding_Agent
User_Prompt <--> Coding_Agent
AgentsMD --> Coding_Agent
Coding_Agent <--> genAI[genAI]
Step 4: Implement Rigorous Human-in-the-Loop Governance Human expertise is non-negotiable. The productivity gains from AI afford senior developers more time for high-value review activities.
- Review Architectural Choices: Evaluate libraries, frameworks, and patterns suggested by the agent.
- Validate Specifications: Scrutinize all GenAI-generated epics, user stories, and acceptance criteria for errors before they cascade.
- Conduct Thorough Code Reviews: Ensure that you instruct the Agent (via Agents.md - TBD - Link to our Agents.md file) on security (input sanitization), error handling, test coverage, and documentation (JSDoc, etc.) AND review the code for their presence.
The Challenge: Our open-source project, UDAN, needed a significant refactoring to separate the UI from the core logic, exposing the functionality as an SDK. This was critical for customer-defined user experiences and for providing a Machine-Consumable Port (MCP) for LLMs.
The Estimates & Results:
| Approach | Estimated Effort (Person-Days) | Key Characteristics |
|---|---|---|
| Manual (No AI) | 90 - 100 | Manual spec writing, architecture, and coding. |
| Coding Assistants | 45 - 55 | AI-assisted coding, but manual pre-coding work. |
| Engineered Agentic Framework | ~15 (Projected) | 5 days for GenAI-aided specs & architecture. 10 days for Agentic coding & review. |
Key Findings from the Agentic Approach:
- Pre-Coding Efficiency: We compressed 25-30 person-days of architecture and specification work into just 5 person-days.
- Architectural Robustness: The GenAI-aided architecture was more robust and included more comprehensive diagrams than a human would have the patience to create.
- Agent Performance: With detailed context, Coding Agents performed exceptionally well, producing near-production-grade code that required only minor edits.
Adopting this framework delivers direct, quantitative benefits and indirect, strategic advantages.
Direct & Quantitative Improvements:
- Productivity Gains: A 5x-10x improvement in developer productivity.
- Cost Savings: A direct 4x-10x cost reduction, even after factoring in paid GenAI tool licensing.
Indirect & Qualitative Improvements:
- Massive Tech Debt Reduction: The focus on upfront architecture and documentation leads to more maintainable and robust code.
- Enhanced Security: Rigorous, AI-assisted planning and review cycles help identify and mitigate vulnerabilities early.
- Improved Code Quality: The resulting code is well-documented, modular, and tightly aligned with business requirements.
This approach is powerful but requires discipline. "Garbage In, Garbage Out" (GIGO) remains a significant factor.
-
Risk: Over-reliance on AI without critical oversight.
- Mitigation: Human review is a mandatory gate at every stage (specs, architecture, code).
-
Risk: Inexperience leading to uncaught errors.
- Mitigation: This framework relies on experienced architects (12+ years) and senior developers (7+ years) to guide the process and identify subtle AI errors. LLMs can get stuck in logical loops, and senior expertise is crucial for course correction.
-
Risk: Ambiguity in initial requirements causing cascading failures.
- Mitigation: The pre-coding step (Step 1) is the most critical. Any errors here will manifest in the final code. This stage requires the most senior-level attention.
###Some links for research https://zed.dev/ https://github.com/gemini-cli-extensions/conductor https://geminicli.com/extensions/?name=gemini-cli-extensionsconductor https://github.com/browser-use/browser-use https://www.warp.dev/