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

What if you could hand a document to your development team and have working, production-ready code materialise within hours — not weeks? That's not a thought experiment anymore. It's the promise of spec-driven development, and for engineering teams that have embraced it, the productivity gains are transformational.

At Infonex, we've seen clients like Kmart and Air Liquide reduce development cycles by up to 80% — not by hiring more engineers, but by fundamentally changing the interface between human intent and machine execution. The key enabler? A methodology we call OpenSpec: write the specification, and let AI write the code.

In this post, we'll break down how spec-driven development works in practice, why it's rapidly becoming the default workflow for forward-thinking engineering teams, and what it means for your organisation's ability to ship faster without sacrificing quality.

The Problem with Traditional Development Cycles

Traditional software development suffers from a fundamental translation problem. Business requirements get written in prose, handed to architects who model them in diagrams, then passed to developers who interpret those diagrams into code. At each handoff, meaning is lost, assumptions creep in, and defects multiply.

The result? A 2023 McKinsey study found that large software projects run 45% over budget and 7% over time on average — and 17% of projects go so badly they threaten the company's existence. Much of this waste lives in the gap between what was specified and what was built.

Spec-driven development attacks this gap directly. Instead of treating the specification as a document that humans interpret, it treats the spec as a machine-readable contract — the single source of truth from which code, tests, and documentation are all derived.

What Is OpenSpec?

OpenSpec is Infonex's framework for AI-accelerated, specification-first development. At its core, it's a structured approach to writing technical specifications that LLMs (Large Language Models) can parse, reason about, and translate directly into working code.

An OpenSpec document is not just a README. It includes:

  • Domain model definitions — entities, relationships, and invariants
  • Behavioural contracts — what each function or service must do, expressed as input/output mappings
  • Acceptance criteria — testable conditions that define "done"
  • Integration constraints — API contracts, data formats, and external dependencies
  • Non-functional requirements — performance, security, and scalability boundaries

When an AI model like GPT-4o or Claude receives a well-formed OpenSpec document, it has enough context to generate not just skeleton code, but complete, context-aware implementations — including error handling, edge cases, and test suites.

From Spec to Code: A Practical Example

Consider a simple OpenSpec definition for a user authentication service:

## Service: UserAuthService

### Domain Model
- User: { id: UUID, email: string, passwordHash: string, createdAt: timestamp }
- Session: { token: JWT, userId: UUID, expiresAt: timestamp }

### Behaviour: authenticateUser(email, password) -> Session | AuthError
- GIVEN a valid email and matching password
- WHEN authenticateUser is called
- THEN return a signed JWT with 24h expiry
- IF email not found OR password mismatch → throw AuthError("INVALID_CREDENTIALS")
- IF account locked → throw AuthError("ACCOUNT_LOCKED")

### Acceptance Criteria
- Passwords must be verified using bcrypt with cost factor >= 12
- JWT must include userId, issuedAt, and expiresAt claims
- Failed attempts must be rate-limited: max 5 per 15 minutes per IP

### Non-Functional Requirements
- P99 latency < 200ms under 500 concurrent users
- Compliant with OWASP Authentication Cheat Sheet

From this spec, an AI model can generate a complete TypeScript implementation, a Jest test suite with edge case coverage, OpenAPI documentation, and even infrastructure-as-code for deployment. What might take a senior developer two days to implement correctly from scratch can be scaffolded in minutes — with the human's role shifting to review and refinement rather than initial construction.

GitHub's research into Copilot usage found that developers using AI assistance completed tasks 55% faster on average. With structured specs providing richer context than ad-hoc prompts, Infonex clients consistently see even greater acceleration.

Why AI Needs Structure: The Context Window Problem

One of the most common failure modes with AI code generation is vagueness. When developers ask an LLM to "build a login system," the model has to make dozens of implicit decisions — about security, data models, error handling — that may not align with the actual requirements. The output is plausible code that needs significant rework.

OpenSpec solves this by front-loading the context. A well-structured spec eliminates ambiguity before the model generates a single line of code. This maps directly to how modern LLMs work: given a context window of 100K-200K tokens (as available in Claude 3.5 or GPT-4 Turbo), a detailed spec allows the model to maintain coherence across an entire feature implementation, not just a single function.

Techniques like RAG (Retrieval-Augmented Generation) extend this further — allowing AI to pull in relevant patterns from your existing codebase, ensuring generated code matches your architecture, naming conventions, and internal libraries. The result isn't generic code; it's code that looks like your engineers wrote it.

The Engineering Team Transformation

Spec-driven development doesn't replace engineers — it elevates them. The highest-value engineering work has always been thinking clearly about problems: understanding domain logic, identifying edge cases, designing for failure. OpenSpec makes that thinking explicit and executable.

In practice, teams adopting this workflow report a significant shift in where time is spent:

  • Before OpenSpec: 60% writing boilerplate and CRUD, 40% on business logic and architecture
  • After OpenSpec: 15% reviewing and refining AI-generated scaffolding, 85% on domain logic, testing strategy, and system design

Air Liquide's engineering team — working with Infonex on a large-scale industrial IoT platform — used OpenSpec workflows to cut their API development cycle from three weeks per endpoint to under two days. The spec documents themselves became living artifacts that the business, QA, and operations teams could all understand and contribute to.

Getting Started: Practical Steps for Engineering Leaders

If you're considering adopting spec-driven development in your organisation, here's how to start without disrupting existing workflows:

  1. Pilot on a greenfield feature. Choose a well-scoped, self-contained feature and write a full OpenSpec document before touching code. Measure the time from spec-complete to code-review-ready.
  2. Establish spec templates. Standardise the structure of your specs so AI tools can reliably parse them. Consistency in format dramatically improves generation quality.
  3. Integrate with your CI/CD pipeline. Use spec acceptance criteria as the basis for automated test generation — tools like Copilot Workspace and Continue.dev can wire specs directly into your IDE.
  4. Measure the translation gap. Track how often AI-generated code passes first-review without significant rework. This is your primary signal that spec quality is improving.

Conclusion

Spec-driven development with OpenSpec represents a genuine shift in how software gets built — not an incremental improvement, but a rearchitecting of the developer workflow itself. The teams that master this approach will be able to ship more, ship faster, and maintain higher quality than those still treating AI as a fancy autocomplete tool.

The technology is mature enough today. The constraint is methodology, not capability. Engineering leaders who invest in structured specification practices now will build a durable competitive advantage — one that compounds as AI models continue to improve.

Ready to Accelerate Your Development Velocity?

Infonex specialises in AI-accelerated development, RAG pipelines, and spec-driven workflows for enterprise engineering teams. Our clients — including Kmart and Air Liquide — have achieved 80% faster development cycles by combining OpenSpec methodology with our deep AI implementation expertise.

We offer a free consulting session to help your team assess where AI can have the greatest impact on your development velocity — with no obligation and no sales pitch, just practical guidance from engineers who've done it at scale.

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