Vibe Coding and Spec-Driven Development: How Engineers Get Production Code from AI

What is vibe coding?

Vibe coding is building software in conversation with an AI coding tool. The developer describes what the code should do, the tool writes it, and the developer runs the result and asks for the next change. The code appears very fast.

In an engineer's hands the result is good. The engineer knows what to ask for, recognizes a weak design when the tool proposes one and checks the output before it goes further. The tool supplies the speed. The understanding comes from the person.

The weak spot is the input. A single sentence followed by a finished application is an extreme that does not hold up. Where the input leaves gaps, the tool fills them with its own guesses.

What are the risks of vibe coding?

Generated code fails in recognizable ways when the understanding behind it is never written down. These are problems of the input. They appear with any tool.

• It looks finished. The demo runs on the happy path. Edge cases, errors and load were never described, and nobody checked them. The distance from the demo to working software is larger than it looks.
• Changes break what worked. As requirements grow, a new function breaks old ones. Nothing written tells the tool what must stay true.
• Non-functional requirements are skipped. Security, performance, reliability and observability rarely appear in a prompt. They rarely appear in the code either.
• Every piece is built differently. Where practices, reference architectures and standard components are not written down, each developer and each AI session writes code its own way. Maintenance gets harder with every new piece.
• The architecture is missing. In most companies a formal architecture does not exist or has gone out of date. The tool then invents one for each request.

Without a written specification the work drifts into chaos: many tools, random prompts, a good result today and a poor one tomorrow.

What is spec-driven development?

Spec-driven development is a way of building software with AI in which a written specification comes before the code. The team defines what to build and why, turns that into a technical plan and a list of tasks, and then lets the AI generate the code and the tests from them.

The specification becomes the main artifact, and the code follows it. When requirements change, the specification changes first, and the code is updated to match.

We see spec-driven development as the right way to write software with AI, and we work this way ourselves: specifications first, code second. A specification also needs something behind it: real requirements and a real architecture. A specification written without them moves the guessing one step earlier.

Vibe coding vs spec-driven development

Both use an AI tool to write the code. They differ in what goes into the tool and in what remains after the work.

In practice the two combine. An engineer vibe codes inside a specification: the specification fixes what must be true, and the conversation with the tool fills in the code. Between the one-sentence prompt and a full formal project there is a middle path, and a short, complete specification is that path.

When vibe coding alone is enough

Not every piece of code deserves a specification. A script that runs once, an experiment that exists to learn whether something works, a tool one engineer uses for a week and throws away: for these, vibe coding alone is the right choice, and a specification would be waste.

The rule we apply is to write a specification when the code will outlive the session that produced it. Four signs:

• Someone other than the author will change it.
• It will run in production or touch production data and other systems.
• It will be extended as requirements grow.
• It has to follow the project's standards for security, performance and reliability.

A prototype built by vibe coding is often the best input to the specification that follows: the code showed what the component has to do, and the production version is then generated from the specification rather than grown out of the prototype.

What is GitHub Spec Kit?

Spec Kit is an open-source toolkit from GitHub for spec-driven development with AI coding agents. It gives the work a fixed order:

1. Principles. Rules that apply to the whole project, written once. Spec Kit calls this document the constitution.
2. Specification. What to build and why, without the technology.
3. Plan. The technical plan, including the stack.
4. Tasks. The plan broken into pieces of work.
5. Implementation. The agent writes the code task by task, and the result is checked, with the cycle repeated until the check passes.

It works with GitHub Copilot and with other AI coding agents, and it is a good place to start.

Other tools with built-in specs

Kiro, the AI development environment from AWS, builds a spec for every feature as three files: requirements with user stories and acceptance criteria, a design with the architecture, sequence diagrams, data flow, error handling and testing strategy, and a task list. The order is the same as in Spec Kit, and it is now the common shape of spec-driven tools.

A tool supplies the order of the work. The content of each document still comes from the engineer and from the company's own standards, and that content decides the quality of the code.

What should a component specification contain?

We write a component specification for each piece of software that AI will generate, from a template of our own. Its first chapter says what the document is for: it is the main input for AI-assisted coding, and it has to hold enough detail for an AI model to generate production-ready code that follows the project's standards.

The template is itself a sequence of prompts. An AI working as a software architect fills it from what the engineer provides: a recorded description of the component (spoken aloud is fine), the company's design profile, the solution architecture and a reference design where one exists. The engineer reviews every chapter.

• Purpose. Why the component exists, the business problem it solves and its place in the system.
• Requirements. The functions it must provide, and the non-functional requirements by type: performance, scalability, availability, reliability, security, data protection, observability, maintainability, deployability, configuration and versioning.
• Structure. The internal parts, their responsibilities and the external systems the component depends on, with class diagrams.
• Behavior. Each transaction step by step, with a sequence diagram.
• Interfaces. Operations, message formats with examples, errors, versioning rules and access control.
• Packaging and deployment. Configuration, packaging, and the steps to install, upgrade, remove and run the component locally.
• Implementation details. Code structure, technology stack and design patterns.
• Testing and validation. The test types, what each one covers and the tools that run them.

The template does not ask for everything every time. Its first step reads the inputs and the component's type, size and complexity, and marks each chapter as included or skipped, with a reason. The introduction, purpose and functions are written for every component. A chapter is skipped when the design profile or reference design already covers it. The standards are written once, and each specification stays short.

An example from the template

The worked example in our template is a product catalog service for an e-commerce platform. Its Behavior chapter describes the transaction that returns one product by its identifier:

1. Receive the request with the product identifier and the store context.
2. Validate the parameters: the identifier format and the required fields.
3. Authorize access for the calling user or service.
4. Call the domain service that runs the retrieval.
5. Load the product from the database through the persistence component.
6. Handle the not-found case when the product does not exist in that store.
7. Map the result to the versioned response format.
8. Return the response or the structured error.

Each step names a part of the component from the Structure chapter, and the Interfaces chapter lists the errors the transaction can return. The tool generates code against these steps and has no gap to fill with a guess.

How does a specification improve vibe coding?

Each risk in the list above has a chapter that answers it.

Two more effects matter. The engineer's understanding stops living in one head: a colleague, a reviewer or the next AI session reads the same document. And the specification belongs to you: the same document drives a different AI coding tool, and a change of tool does not mean starting over.

The engineer still writes the code with the tool, function by function. The conversation starts from a document instead of a sentence.

Where do the requirements and the architecture come from?

A specification is the last link of a chain. Business requirements and the design feed the architecture, and the architecture feeds the specification of each component.

Most teams find part of that chain missing. A formal architecture is rare, and where one existed it has gone out of date. Our order of work for such a team:

1. Set up an architecture process and train the people who will run it.
2. Describe the current architecture from the working code, improve it and write it down.
3. Connect it with the business requirements, the design and the coding in one end-to-end development flow.

This is the core of our AI-Powered Solution Architecture work.

Spec-driven development and context engineering

Context engineering is the name now used for the work of giving an AI model the information it needs to do a task well. For code, that information is this chain: the requirements, the architecture, the design profile and the specification of the component. Spec-driven development is context engineering with the context written down in a fixed set of documents. Every session and every tool then gets the same input. AI does not work without proper context, and this is where the context comes from.

Existing code with no specification

Most code that matters was written before anyone wrote a specification for it. The working system is the only specification there is.

The rule we apply is to read the specification out of the code before changing the code. For each component the team is about to touch, its specification is written from the component's actual behavior: what it does today, the interfaces other systems depend on and the qualities it has to keep. Tests that pin that behavior are written before the change. The regenerated code is then checked against the old one. From that point the component is maintained the spec-driven way, and components nobody touches keep running as they are.

What does the engineer do in spec-driven development?

Everything that needs understanding and judgment. The AI writes the code and the tests, and it does that very fast. The engineer does the rest of the work, and the rest is most of software engineering.

1. Understand the problem. The business need, the architecture the component belongs to, the interfaces it must honor and the qualities it must have.
2. Write the specification and decide the design in it: structure, transactions, contracts, stack, patterns.
3. Generate the code with the AI, contracts and interface first, then the business logic, persistence and connections, function by function, with the tests generated alongside.
4. Review the generated code against the specification and the design profile, and change what the tool got wrong.
5. Harden it. Configuration, scalability, security, reliability and observability are added and checked after the logic works.
6. Test it in order. Quality criteria come from the functional and non-functional requirements. Fast and important checks run first, expensive ones last. Defects that slip through go back into the tests.
7. Package, deploy and run it. Code that only runs on the developer's machine is not finished.
8. Maintain it. Requirements change in the specification first, then in the code.

The direction we are working toward is agents that take over more of steps 3 to 7 while engineers set the goals, own the specifications and check the results. The specification is what makes that step possible, because an agent can only follow what is written down.

How does a team start with spec-driven development?

Start with one team and one component, not with a company-wide rule.

1. Pick a pilot. One component with real requirements and a real deadline, built by the engineers who will own it afterward.
2. Write the design profile once. The stack, the reference architecture, design patterns, coding standards, and the packaging and deployment rules. Where the architecture is missing, describe it from the code first.
3. Write the first specification from a template, with the AI drafting and the engineer reviewing every chapter. Skip what is already covered.
4. Build the component the spec-driven way, through the cycle above.
5. Measure against the previous way. Review effort on the generated code, rework, the time a change takes and the defects that escape to testing.
6. Extend. The profile written for the pilot serves every component after it. Add Spec Kit or Kiro for the order of the work, and put the profile into their principles or steering documents.

The profile and the template are what make the second component cheaper than the first.

How EIC builds software with AI

Our engineers build software with AI across the whole cycle, from the requirements to the deployed component. The specification is where the work starts, and the code is still engineered. The documents follow the same discipline: prompts, templates and a fixed order in which each document builds on the ones before it.

We bring the same approach to client teams. AI-Powered Solution Architecture turns requirements into implementation-ready designs and builds the reference designs, patterns and templates that specifications draw on, with architects keeping ownership of the decisions. AI-Powered Test Development builds tests from requirements and coverage rules. AI-Powered Software Factory Transformation connects the whole delivery cycle, from product decisions to release, with clear inputs, outputs and contracts at every stage.

Where the architecture is missing or out of date, we start there, and spec-driven development then has something to stand on.