Spec-driven vibe coding: A practical alternative to prompt-and-patch development

While AI coding agents can generate working software in minutes, growing repositories often lead to lost context, accumulated technical debt, and inconsistent decisions. Spec-driven vibe coding solves this by introducing a lightweight source of truth, preserving the rapid, exploratory nature of vibe coding while adding just enough structure for repeatable implementation and review. This guide outlines the approach, compares it to formal Spec-Driven Development, and provides a practical seven-step workflow with a reusable specification template for different project risk profiles.

What is spec-driven vibe coding?

Spec-driven vibe coding is an AI-assisted workflow in which conversational code generation follows a written, version-controlled specification defining required behavior, constraints, non-goals, and acceptance criteria. The specification remains a persistent source of truth across sessions, contributors, and agents, reducing reliance on temporary chat context without making AI-generated output deterministic.

It is more structured than prompt-and-patch development, where requirements may exist only inside a conversation. It is also lighter than formal Spec-Driven Development, which adds stronger governance, traceability, verification, and change control.

The specification provides:

• Expected behavior: What users or connected systems must be able to do.
• Scope and non-goals: What the agent should build and explicitly avoid.
• System constraints: Compatibility, architecture, data, security, or performance boundaries.
• Durable context: Information stored in the repository rather than an ephemeral chat history.
• Acceptance criteria: Observable conditions used to evaluate the implementation.
• A review baseline: A stable artifact for comparing plans, code, and tests.

A version-controlled specification is stored with the repository, reviewed through pull requests, and reused by different sessions or contributors. It becomes a living specification when teams update it after approving behavioral changes.

A long prompt is not automatically a specification. Prompts instruct an agent during the current interaction. A maintained specification records approved intent beyond that interaction.

The term remains emerging practitioner language rather than a universally standardized methodology. Andrej Karpathy introduced “vibe coding” in February 2025 to describe conversational development where the developer increasingly accepts AI-generated changes without inspecting each line. Vivek Haldar subsequently documented a specification-plus-design workflow for preserving intent before asking an agent to implement a project.

Vibe coding vs. Spec-driven vibe coding vs. Formal SDD

The three approaches optimize for different outcomes:

• Vibe coding follows Prompt → Generate → Run → Patch.
• Spec-driven vibe coding follows Specify → Plan → Generate → Test → Review.
• Formal Spec-Driven Development follows Authoritative specification → Design → Controlled implementation → Verification → Governance.

Spec-driven vibe coding is a middle layer, not simply formal SDD with fewer documents.

A lightweight specification usually governs a bounded feature, product, or development workflow. It helps preserve context and makes changes easier to review, but it may not include controlled baselines, formal change approval, independent verification evidence, or audit records.

Formal SDD treats specifications as authoritative lifecycle artifacts. Requirements traceability means each requirement can be connected to relevant design decisions, implementation tasks, tests, and approval evidence. This is especially important when multiple teams, external auditors, or regulated processes are involved.

A Markdown file is not equivalent to formal verification, threat modeling, compliance review, or independent validation. It can provide a basis for those activities, but it does not perform them.

Consider four B2B software contexts:

• An experimental CRM lead-routing rule may only need vibe coding and manual validation.
• An internal reporting workflow benefits from a lightweight specification and regression tests.
• A customer-facing SaaS billing feature requires stronger review, observability, rollback, and security controls.
• A regulated identity or payment system may require formal SDD, independent validation, and auditable change management.

The appropriate workflow depends on the cost of misunderstanding or failure, not on whether one methodology appears more modern.

How spec-driven vibe coding works

A practical spec-driven vibe coding workflow uses seven stages:

1. Define the goal and non-goals.
2. Write the minimum viable specification.
3. Ask the agent to produce a technical plan.
4. Implement in bounded tasks.
5. Generate and run verification.
6. Review against the specification.
7. Update the specification after approved changes.

1.  Define the goal and non-goals

Start with the business or system outcome, not the preferred implementation.

For example, “improve lead routing” is too vague. A more useful goal is: “Assign inbound enterprise leads to regional account owners within 60 seconds, based on country and company size.”

Non-goals prevent scope expansion. The same specification might exclude territory redesign, CRM migration, and historical lead reassignment. This step gives the AI coding agent a bounded problem instead of inviting it to invent adjacent requirements.

2.  Write the minimum viable specification

A minimum viable specification contains enough detail to remove decision-critical ambiguity. It should define:

• Required behavior.
• Inputs and outputs.
• Relevant actors or integrations.
• System constraints.
• Edge cases and failure behavior.
• Dependencies.
• Acceptance criteria.
• Security and privacy requirements.

“Minimum viable” does not mean documenting as little as possible. The required detail should increase with data sensitivity, integration complexity, expected lifespan, and consequence of failure. Store the specification in the repository so it remains available across models, sessions, and contributors.

3.  Ask the agent to produce a technical plan

The agent should create a reviewable technical plan before modifying major components. The plan should identify:

• Affected files, modules, and services.
• Dependencies and data flows.
• Implementation sequence.
• Migration or backward-compatibility concerns.
• Unknowns and ambiguous requirements.
• Proposed testing and verification levels.

Require the agent to surface uncertainty rather than silently invent requirements. A human should approve the plan before significant code changes begin.

This control is particularly important when an agent proposes schema changes, new dependencies, authentication changes, or broad refactoring.

4.  Implement in bounded tasks

Divide the approved plan into small, reviewable tasks. Each task should reference the requirement it supports and identify the files or modules it may change.

Useful implementation controls include:

• Restricting edits to relevant components.
• Prohibiting unrelated refactoring.
• Reviewing dependency additions separately.
• Running tests after each material task.
• Pausing when implementation conflicts with the approved plan.

There is no universal task-size limit. The correct boundary is the smallest meaningful change that can be reviewed and verified independently.

5.  Generate and run verification

Tests should map back to the acceptance criteria, not merely reproduce the generated implementation.

Verification may include:

• Unit tests for isolated behavior.
• Integration tests for APIs, databases, or external systems.
• Acceptance tests for user-visible outcomes.
• Regression tests for existing behavior.
• Security checks for sensitive inputs and permissions.
• Manual validation for workflows that cannot be fully automated.

AI-generated tests require human review. The same model can misunderstand a requirement, implement that misunderstanding, and then generate tests confirming its own incorrect assumption.

For higher-risk systems, independent test design or separate review agents can reduce circular validation. They still do not remove the need for engineering judgment.

6.  Review against the specification

Review the result against intended behavior rather than asking only whether the application runs.

The review should examine:

• Delivered behavior and unmet criteria.
• Deviations from the technical plan.
• New or changed dependencies.
• Security and privacy implications.
• Side effects on existing components.
• Relevance of the tests.
• Documentation and operational changes.
• The agreed definition of done.

“The code runs” is not sufficient acceptance for software supporting customers, revenue, sensitive data, or critical business operations.

7.  Update the specification

Approved behavioral changes must update the specification. Record unresolved deviations rather than allowing them to disappear into chat history.

Where practical, commit related specification, implementation, and acceptance-test changes together. This preserves requirements traceability and prevents generated code from becoming the only reliable description of system behavior.

This maintenance step turns a static document into a living specification.

What should a useful AI coding specification include?

A useful AI coding specification defines behavior and boundaries without prescribing every implementation detail. Longer documents are not automatically better. The objective is to remove ambiguity that could materially change the result.

The following tool-agnostic template is suitable for a bounded feature and can be stored directly in a repository.

# Feature or Project Name

## Goal
Describe the user, system, or business outcome.

## Non-Goals
List behavior, systems, and changes that are outside scope.

## Users or System Actors
Identify users, services, administrators, or integrations involved.

## Required Behavior
Describe what the system must do in observable terms.

## Inputs and Outputs
Define relevant requests, events, data, responses, or files.

## Constraints
List compatibility, architecture, performance, or platform constraints.

## Edge Cases and Failure Behavior
Describe invalid inputs, unavailable dependencies, timeouts, retries,
partial failures, and expected error handling.

## Dependencies
List services, libraries, APIs, databases, and required permissions.

## Acceptance Criteria
- [ ] Observable condition one
- [ ] Observable condition two
- [ ] Observable failure condition
- [ ] Existing supported behavior remains unchanged

## Testing Requirements
Define required unit, integration, acceptance, regression, and manual tests.

## Security and Privacy
Describe authentication, authorization, sensitive data, logging,
retention, and applicable compliance requirements.

## Definition of Done
State the required code review, tests, documentation, deployment,
observability, and approval conditions.

Omit irrelevant fields rather than adding empty boilerplate. Expand security, privacy, deployment, and recovery requirements as system risk increases.

Implementation choices normally belong in a technical design. Include them in the feature specification only when they are genuine constraints, such as an existing API contract or mandatory deployment environment.

Replace subjective terms such as “fast,” “secure,” or “scalable” with observable conditions.

Specification vs. related development artifacts

What not to put in the specification

Avoid:

• Unnecessary implementation details.
• Contradictory requirements.
• Unverified assumptions presented as facts.
• Undefined terms such as “high performance.”
• Temporary commands intended for one agent interaction.
• Tool-specific operating rules that belong in AGENTS.md, CLAUDE.md, or equivalent project instructions.

Benefits, limitations and common failure modes

Spec-driven vibe coding can improve code maintainability by preserving intent and making proposed changes easier to evaluate. It also introduces documentation and review obligations that teams must maintain.

Common failure modes:

Specification theater: The document exists but agents and reviewers do not use it.

• Prevention: Require plans, pull requests, and tests to reference relevant requirements.

Hidden ambiguity: Terms such as “secure,” “real time,” or “user-friendly” remain undefined.

• Prevention: Replace subjective language with observable behavior or measurable constraints.

Spec-code divergence: The implementation changes while the specification remains static.

• Prevention: Include specification updates in the definition of done for behavioral changes.

Oversized implementation requests: The agent changes multiple modules, dependencies, and interfaces at once.

• Prevention: Split the plan into bounded tasks with review checkpoints.

Circular verification: The same model and assumptions produce the specification, code, and tests.

• Prevention: Review acceptance criteria independently and add risk-appropriate human or separate-agent validation.

False assurance: Completed checklists are treated as proof of production readiness.

• Prevention: Evaluate security, deployment, monitoring, recovery, and operational ownership separately.

Context overload: Large repositories are repeatedly inserted into a model’s context window without prioritization.

• Prevention: Provide relevant specifications, plans, interfaces, and files instead of indiscriminate repository dumps.

A written specification can reduce ambiguity, patch loops, and requirements drift. It cannot make probabilistic AI-generated output deterministic or guarantee correct, secure, maintainable software.

When to use vibe coding, spec-driven vibe coding or formal SDD

Choose an engineering methodology according to system risk and the cost of failure. Relevant factors include lifespan, contributors, integration complexity, data sensitivity, revenue dependency, auditability, and regression impact.

A prototype is not automatically low-risk. A temporary application connected to production CRM data, payment systems, identity providers, or customer records may require stronger controls than a larger isolated demo.

Move beyond pure vibe coding when…

Move beyond pure vibe coding when one or more of the following occurs:

1. Context drift: The agent fixes one component while breaking another.
2. Recurring regressions: New features repeatedly invalidate previous behavior.
3. Multiple contributors: More than one person or agent must interpret the requirements.
4. Production intent: Real users or business operations will depend on the software.
5. Sensitive data: The system handles credentials, personal data, financial data, or confidential records.
6. Critical integrations: Failures could disrupt CRM, billing, identity, or operational systems.
7. Revenue dependency: Defects can block transactions, renewals, or customer access.
8. Auditability requirements: The organization must demonstrate why and how changes were approved.

These triggers provide a practical answer to how to transition from vibe coding to production code: Preserve approved intent, introduce plan approval, connect tests to acceptance criteria, and escalate independent controls according to risk.

Risk-based verification levels

Production readiness requires evidence across testing, security, deployment, observability, recovery, and ownership. Test coverage alone does not establish that evidence.

For secure lifecycle guidance, the NIST Secure Software Development Framework provides risk-based practices covering software preparation, protection, production, and vulnerability response.

Operationalizing the workflow with AgentKit

Teams can apply this methodology using repository files and standard AI coding tools alone. AgentKit is an optional operational layer for teams that want reusable roles, skills, configurations, and approval-driven workflows across different agents and repositories.

Instead of rebuilding prompts for every session, teams can organize specialized coding agents around persistent repository artifacts. Planning, frontend, backend, database, testing, debugging, and review activities can remain separate while following the same approved specification.

The value is not that every task becomes automatic. The value is a more repeatable human-in-the-loop development structure with explicit handoffs.

A practical repository pattern

/docs
product-spec.md
technical-design.md
architecture-decisions.md

/plans
current-plan.md
completed/

/tests
acceptance/
integration/

AGENTS.md or tool-specific project instructions

Each location serves a different purpose:

• /docs: Approved product intent, technical design, and architecture decisions.
• /plans: Current and historical implementation plans.
• /tests: Behavioral, integration, and regression verification.
• AGENTS.md: Stable operating instructions for supported tools and agents.

This structure is a suggested pattern, not a universal requirement. A small project may need only one specification, one plan, and a focused test suite.

Where AgentKit fits and where it does not

AgentKit is best suited to:

• Experienced developers managing several AI-assisted workflows.
• Solo founders turning prototypes into maintained products.
• Small teams coordinating work across multiple agents.
• Agencies that need repeatable delivery standards.
• Teams switching among Claude Code, OpenAI Codex, GitHub Copilot, Cursor, or comparable tools.

Capabilities differ across these products and may change quickly. Teams should verify current behavior using the providers’ primary documentation rather than assuming identical autonomy, context, or security controls.

AgentKit may be unnecessary for:

• One-off disposable experiments.
• Teams with an established orchestration system.
• Projects where one bounded prompt is sufficient.
• Environments that cannot support the required integrations or security model.

AgentKit can organize AI agentic workflows, reusable skills, and persistent repository artifacts. It does not replace engineering leadership, security expertise, compliance review, or independent validation.

A specification is a guardrail, not proof of correctness

Use vibe coding when the primary objective is rapid, low-risk exploration. Introduce spec driven vibe coding when context loss, misunderstanding, or regression becomes costly. Move toward formal SDD when regulation, auditability, security, or multi-team coordination requires stronger lifecycle controls. These approaches solve different problems; none is universally superior.

A specification preserves intent and provides a review baseline. It does not prove that the resulting software is correct, secure, maintainable, or production-ready. Testing, code review, security controls, observability, rollback planning, and human accountability remain necessary.

Frequently asked questions

What is spec-driven vibe coding?

Spec-driven vibe coding is an AI-assisted development workflow that combines the speed of exploratory "vibe coding" with the structure of a maintained, version-controlled specification. It ensures AI agents remain focused on the user’s intent by using persistent repository artifacts rather than relying solely on ephemeral chat history.

Is spec-driven vibe coding the same as formal spec-driven development (SDD)?

No. Spec-driven vibe coding is a lightweight middle ground. While formal SDD integrates strict lifecycle governance, traceability, and compliance controls, spec-driven vibe coding focuses on preserving intent across sessions and contributors using readable, repository-based documentation without the heavy overhead of formal software engineering standards.

Why should I move beyond pure vibe coding?

You should transition when your project faces context drift, increasing regression patterns, or when the cost of failure rises. Pure vibe coding often hits a "three-month wall" where technical debt compounds and the lack of a formal source of truth makes it impossible to maintain system integrity.

Does a specification prevent AI coding hallucinations?

No. A specification reduces ambiguity and provides a baseline for human review, but it cannot make AI output deterministic. AI agents can still misinterpret requirements or generate insecure code; therefore, human oversight, automated verification, and standard security practices remain mandatory for production systems.

What should be included in an AI coding specification?

A minimum viable specification should include the project goal, non-goals, required behavior, inputs/outputs, constraints, edge cases, failure behavior, dependencies, and observable acceptance criteria. Keep details proportional to the system's risk profile-longer specifications are not automatically better or more effective.

When is formal spec-driven development (SDD) necessary?

Formal SDD is required for projects with high stakes, such as regulated industries, multi-team platforms, or systems handling sensitive financial and identity data. In these environments, you need strong auditability, independent verification, and lifecycle governance that goes beyond what a repository Markdown file can provide.

How do I operationalize this workflow?

You can operationalize this by establishing a clear directory structure (e.g., /docs for specs, /plans for implementation tasks, /tests for verification). Using agentic tools to enforce human approval gates at the planning and acceptance stages ensures that code is only generated against approved specifications.

Read more:

• Vibe coding product spec: Build faster with AI clarity
• Agentic coding vs vibe coding: A practical guide for developers
• Vibe coding vs traditional coding: Which approach wins?

Conclusion

In conclusion, spec-driven vibe coding offers a practical, middle-ground approach that bridges the gap between rapid, unconstrained prompt-and-patch development and rigid, formal Spec-Driven Development.

By maintaining a lightweight, version-controlled specification as a living source of truth in the repository, development teams can effectively mitigate context loss and technical debt while preserving the agility of AI-assisted creation. Ultimately, preserving intent through clear acceptance criteria and human approval gates ensures that software remains maintainable, reliable, and ready to scale as project risks evolve.