From Vibe Coding to Kiro Spec-Driven Development: Bringing Engineering Determinism to AI Projects

Vibe and Spec sessions

A Vibe session is an exploratory sandbox where developers converse with an LLM, iteratively adjusting prompts and probing model limits. The output is informal, chaotic, and unsuitable for production. A Spec session is a deterministic, version‑controlled YAML specification that formally defines an AI task. Migrating from Vibe to Spec solidifies a prototype into a reusable, testable component.

Outer ring – project‑management layer

Each feature lives under a directory .kiro/specs/<em>feature</em>, which serves as the single source of truth. The directory contains: requirements.md – explains *why* the feature is needed (user stories, business goals, acceptance criteria). design.md – explains *how* the feature will be built (architecture, data model, API design). tasks.md – explains *what* to implement (breakdown into assignable engineering tasks).

All three files are versioned, providing unified documentation for product, architecture, and engineering teams.

Inner ring – AI runtime layer

Within the same feature directory, one or more .spec.yml files describe an AI task that the Kiro runtime can execute. Each spec includes:

Schema – Pydantic models define strict input and output contracts (e.g., input must be a string ≥ 50 characters; output must be a JSON object with a sentiment enum and a confidence_score float between 0 and 1). The schema enables automatic validation and parsing.

Instructions – the core logic is broken into templated, step‑wise statements rather than a monolithic prompt, improving robustness and maintainability.

Tools – external Python functions that the LLM may invoke (e.g., API calls, database queries, complex calculations). Tools turn the LLM into a reasoning engine that can interact with the outside world.

Examples – concrete input‑output pairs that guide the model.

Spec files are treated as first‑class code: they reside alongside .py files in Git, benefit from version control, code review, CI/CD validation, and automated testing. Each change to AI behavior is recorded as a git commit, eliminating “prompt drift” and knowledge fragmentation.

Runner execution loop

Input validation – the Runner checks incoming data against the input schema.

Dynamic prompt compilation – it assembles an optimized prompt from the spec’s instructions, tools, and examples.

LLM call – the compiled prompt is sent to the language model.

Output validation & parsing – the response is validated against the output schema; on mismatch the Runner can auto‑repair or retry according to spec rules.

Tool execution – if the response indicates a tool call, the Runner safely executes the corresponding Python function and feeds the result back for further reasoning.

This “validate → compile → call → validate → execute” cycle provides a resilient, predictable execution environment, contrasting with the “launch‑and‑forget” style of traditional prompt engineering.

Practical example – refactoring a resume parser

A legacy resume parser can be reimplemented as resume_parser.spec.yml. The spec defines the required input schema (e.g., raw resume text), output schema (e.g., JSON with fields such as name, experience, skills), step‑wise instructions for extracting sections, and tools for normalizing dates or querying external skill taxonomies. The example demonstrates how a chaotic Vibe prototype becomes a deterministic, testable component.