Spec-Driven Development with OpenSpec: Write the Spec, AI Writes the Code

There's a moment every engineering team knows well: the gap between what the spec says and what the code actually does. Requirements live in Confluence, logic lives in someone's head, and the codebase drifts further from intent with every sprint. What if you could collapse that gap entirely — and have AI write production-ready code directly from the specification?

That's the promise of spec-driven development, and with tools like OpenSpec and modern LLM-powered pipelines, it's no longer theoretical. Enterprises that adopt this workflow are cutting development cycles by up to 80% while producing more consistent, auditable, and maintainable software. Here's how it works — and why forward-thinking engineering leaders are making it the foundation of their AI strategy.

What Is Spec-Driven Development?

Spec-driven development (SDD) flips the traditional workflow. Instead of writing code and then documenting it (if you're lucky), you start with a machine-readable specification and let AI generate the implementation.

The specification becomes the single source of truth. It defines:

  • API contracts (endpoints, request/response schemas, auth)
  • Business rules and validation logic
  • Data models and relationships
  • Expected behaviours and edge cases

OpenSpec formalises this idea with a structured format that LLMs can parse, reason over, and translate into working code. Think of it as OpenAPI — but richer, with business context baked in. The result: AI that doesn't just generate syntactically valid code, but code that correctly reflects intent.

The Traditional Problem: Specs That Rot

In most organisations, specs and code diverge almost immediately. A Confluence page written in Q1 describes a feature that has been modified six times by Q3. The spec no longer reflects reality, the original author has moved on, and the next developer inherits a mystery.

McKinsey's 2023 research on developer productivity found that engineers spend nearly 30% of their time on code comprehension — understanding what existing code does before they can modify it. A significant portion of that effort is reconciling code with outdated or absent documentation.

Spec-driven development solves this at the root. When the spec is the authoritative input and the code is generated from it, they cannot diverge — because every code change starts with a spec change.

How OpenSpec Works in Practice

An OpenSpec document describes a feature in structured, human- and machine-readable terms. Here's a simplified example for a customer order API:

openspec: "1.0"
feature: CustomerOrderService

entities:
  Order:
    fields:
      - name: orderId
        type: UUID
        generated: true
      - name: customerId
        type: UUID
        required: true
      - name: items
        type: List[OrderItem]
        minLength: 1
      - name: status
        type: Enum[PENDING, CONFIRMED, SHIPPED, CANCELLED]
        default: PENDING

operations:
  placeOrder:
    input: PlaceOrderRequest
    output: Order
    rules:
      - "Customer must have verified email"
      - "Total value must not exceed customer credit limit"
      - "Inventory must be reserved atomically"
    errors:
      - InsufficientInventoryError
      - CreditLimitExceededError

Feed this into an OpenSpec-aware AI pipeline and it generates:

  • The data model and migration scripts
  • The service layer with business rule validation
  • REST or GraphQL API endpoints
  • Unit and integration test scaffolding
  • API documentation (OpenAPI/Swagger)

What would take a senior developer two to three days to implement correctly is produced in minutes — and critically, it's consistent with everything else generated from specs in the same codebase.

RAG + Codebase Awareness: The Missing Piece

Generic code generation from LLMs has a well-known limitation: the output doesn't know your codebase. It generates boilerplate that doesn't follow your naming conventions, doesn't reuse your shared utilities, and doesn't integrate with your existing patterns.

This is where Retrieval-Augmented Generation (RAG) transforms spec-driven development from a toy into an enterprise capability. A RAG pipeline indexes your entire codebase — models, services, utilities, tests — and retrieves relevant context at generation time. The LLM doesn't just know the spec; it knows how your team codes.

GitHub's research on Copilot adoption across enterprise teams found a 55% improvement in task completion speed among developers using AI assistance. When that assistance is grounded in codebase context via RAG, the gains compound further — because developers spend less time correcting AI output that doesn't fit the codebase.

Infonex's implementation combines OpenSpec with a codebase-aware RAG layer, meaning generated code slots into your architecture as if a senior developer who has read every line of your codebase wrote it.

What This Means for Engineering Leaders

For CTOs and Engineering Managers, spec-driven development with AI changes the economics of software delivery in three concrete ways:

1. Junior developers ship at senior velocity. When AI handles the translation from spec to implementation, the bottleneck shifts from implementation skill to specification quality. A well-structured spec from a junior developer produces solid, consistent code — dramatically compressing the experience gap on your team.

2. Compliance and auditability become natural by-products. In regulated industries — finance, healthcare, logistics — being able to demonstrate that code faithfully implements a formal specification is enormously valuable. The spec is the audit trail. Infonex has deployed this model for enterprise clients where traceability between requirements and implementation is a compliance requirement.

3. Onboarding time collapses. New developers onboard to a spec-first codebase by reading specs, not reverse-engineering code. Context is explicit, not tribal. Infonex clients including Kmart and Air Liquide have reported that this shift alone reduces meaningful contribution time for new hires from weeks to days.

Getting Started: A Pragmatic Path

You don't need to rewrite your codebase to adopt spec-driven development. The most successful enterprise rollouts start with a single bounded domain — a new microservice, a greenfield feature, or a well-isolated module — and use it to establish patterns and demonstrate ROI.

The steps are straightforward:

  1. Define your OpenSpec schema for the target domain
  2. Index your existing codebase for RAG context
  3. Run generation against the spec, review output, iterate on the spec
  4. Establish spec-first as the team norm for all new work in that domain
  5. Expand incrementally

The key insight from teams that have done this successfully: the bottleneck quickly shifts from "how do we write this code?" to "how do we write this spec well?" — which is actually the more valuable skill, and one that transfers directly to better system design.

Conclusion

Spec-driven development with OpenSpec and AI isn't a future concept — it's a production workflow that leading enterprises are using today to ship faster, more consistently, and with greater confidence. The combination of structured specifications, LLM code generation, and codebase-aware RAG eliminates the most painful parts of software development: the drift between intent and implementation, the cost of boilerplate, and the knowledge silos that slow teams down.

For engineering leaders, the question isn't whether AI will change how your team builds software. It's whether you'll be ahead of that shift or catching up to it.

Ready to See What 80% Faster Development Looks Like for Your Team?

Infonex helps enterprises adopt AI-accelerated development workflows — from OpenSpec integration and RAG pipelines to full codebase-aware AI tooling. Our clients, including Kmart and Air Liquide, have achieved 80% faster development cycles by working with us to implement these approaches at scale.

We offer a free consulting session for enterprise teams ready to explore what's possible. No commitment, no sales pitch — just a practical conversation about your codebase, your bottlenecks, and where AI can have the most impact.

Book your free AI consulting session at infonex.com.au →

Comments

Post a Comment

Popular posts from this blog

How RAG Makes AI Development Assistants Codebase-Aware

Imagine hiring a senior developer who has memorised every line of your codebase, every API contract, every migration script, and every architectural decision your team has ever made — and who can answer questions about any of it in plain English, in seconds. That's the promise of Retrieval-Augmented Generation (RAG) applied to software development. And in 2026, it's no longer a promise. It's production reality for engineering teams that are serious about moving fast. Generic AI coding assistants — the kind that ship with a base LLM and a syntax highlighter — are useful for boilerplate. But they have a fundamental blind spot: they don't know your codebase. They don't know that your UserService has a quirk in how it handles multi-tenant auth, or that your database team deprecated the old orders_v1 schema six months ago. Without that context, AI suggestions are educated guesses at best and hallucinated nonsense at worst. RAG changes the equation. By grounding...
Read more

How RAG Makes AI Development Assistants Codebase-Aware

Every enterprise has a secret weapon hiding in plain sight: its codebase. Millions of lines of hard-won logic, domain-specific patterns, internal API contracts, and architectural decisions — encoded in files that only experienced engineers truly understand. When AI coding assistants ignore this context, they produce generic code that doesn't fit. When they understand it, they become something else entirely: an expert collaborator who already knows your system inside out. That's the promise — and increasingly the reality — of Retrieval-Augmented Generation (RAG) applied to software development. By grounding AI models in your actual codebase rather than relying on general training data alone, RAG transforms a competent AI assistant into a codebase-aware engineering partner. For CTOs and Engineering Managers evaluating where AI fits in their development stack, understanding how RAG works at a technical level is no longer optional — it's a strategic necessity. What RAG A...
Read more

How RAG Makes AI Development Assistants Truly Codebase-Aware

Your AI coding assistant just suggested a function that already exists — three layers deep in a service your team wrote 18 months ago. Or worse, it generated a database call that bypasses your repository pattern entirely. Sound familiar? This is the core problem with vanilla LLMs in software development: they're brilliant in the abstract and blind to your specific codebase. They don't know your naming conventions, your internal APIs, your architectural decisions, or the tech debt your team is carefully managing. They answer from training data — not from your repo. Retrieval-Augmented Generation (RAG) is the architectural pattern that fixes this. And for enterprise engineering teams, it's the difference between an AI assistant that occasionally helps and one that becomes an indispensable part of the development workflow. This post breaks down how codebase-aware RAG actually works, what it takes to implement it properly, and why teams that get it right are reporting dev...
Read more