BD TECH.

Writing

From vibe coding to spec-driven: an AI-native architecture built on specs, skills and self-verification loops

Published he

First published on Medium in April 2026. Figures, tool names and sources revised in October 2026.

How do you build reliable systems when the code is written by probabilistic agents? The real work isn't writing better prompts.

From typing machine to technical-debt machine

In 2024 the industry settled on a simple picture: AI is a fast typist. The developer describes what they want in plain language and the model delivers. That was the promise of vibe coding, a straight line from intent to code.

Two years on, the data tells a different story.

  • A large empirical study posted to arXiv in March 2026 followed 302,600 AI-authored commits across 6,299 repositories. Those commits introduced 484,366 issues. Most of them (89%) are code smells rather than outright bugs, and 22.7%, roughly 110,000, were still present in the latest version of the code.
  • An August 2025 analysis by Sonar had leading models write more than 4,400 Java tasks. Over 70% of the vulnerabilities in Llama 3.2 90B's code were rated BLOCKER, the highest severity. For GPT-4o the figure was 62.5%.

The models aren't bad. The problem is one of paradigm. A probabilistic model given a vague specification produces code that passes its unit tests and still breaks the architecture, the API contracts and the security patterns. Those failures surface only in production.

Developers found they weren't saving time. They had traded writing code for reviewing and patching it, round after round.

This post maps the architectural answer taking shape across the industry and proposes a distilled version of it.

1. What changed

The term spec-driven development (SDD) took hold in mid-2025, when Kiro, Spec Kit and Tessl launched within two months of each other. A year later it has grown into a crowded field with dozens of frameworks. A few of them:

  • GitHub Spec Kit: open source with about 140,000 stars, built around a command per stage: specify, plan, tasks, implement.
  • Kiro (AWS): an IDE, generally available since November 2025, that turns intent written in natural language into requirements in EARS notation ("WHEN … THE SYSTEM SHALL …").
  • OpenSpec: a lighter loop of propose, apply and archive. It is deliberately fluid, with no gates between phases.
  • BMAD-METHOD: multi-agent orchestration with named personas (analyst, product manager, architect, developer) that hand context to each other through Markdown documents: a PRD, an architecture document, story files.
  • Agent Skills: the SKILL.md format Anthropic published as an open standard in December 2025. The agentskills.io site now lists more than forty tools that read it, among them Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot and Kiro. Community libraries such as Antigravity Awesome Skills offer more than 2,600 ready-made skills.

They all rest on one principle:

Don't have an AI write code from a prompt. Give it a specification that says precisely what, and deterministic tools that handle the how.

That moves the question from "which model is smartest?" to "what context makes any model reliable?". The discipline is called context engineering. SDD supplies the method; context engineering supplies the frame: designing the whole environment, meaning what the agent knows, when it knows it, and how it checks its own work.

2. Four pillars of specification

The framework below distills the patterns that recur across those tools. It organizes a project around four kinds of structured specification, with a fifth, cross-cutting layer of stewardship.

Structure     Design       Content     Behavior
YAML, JSON    DESIGN.md,   Markdown,   state
Schema        tokens       JSON        machines
    └─────────────┴─────┬─────┴───────────┘
                        ▼
  Skill (SKILL.md): reads the specs, calls the
  scripts; hooks hold the mandatory steps
                        ▼
  the agent generates an artifact
                        ▼
  deterministic verification
      fail → back to the skill, repair
      pass ↓
  a human reviews the clean output

Pillar one: structure

  • The question: which components exist, and how do they connect?
  • The format: YAML for configuration and hierarchy; JSON Schema for data and API contracts.
  • The role: the project's constitution, a declarative blueprint that sets the boundaries. A machine-readable format matters because it can be checked: a schema either validates or it doesn't, while a paragraph of prose can only be interpreted.

Pillar two: design

  • The question: what experience does the system deliver?
  • The format: a dedicated DESIGN.md plus design tokens.
  • The role: visual consistency. Tokens (color, type, spacing) live in a separate file that every component imports. That makes them an enforceable contract: change one token and the whole system follows.

Pillar three: content, media and data

  • The question: what does the system display?
  • The format: Markdown for content, JSON for structured data.
  • The role: separating content from code. A physical separation is also a logical one. It keeps the agent from tangling a content update with a code change, a common source of hallucinated edits.

Pillar four: behavior and logic

  • The question: how does the system behave?
  • The format: a hybrid that separates what from how.
    • What: declarative logic (state machines, workflows, invariants) in YAML.
    • How: computation (complex algorithms, external integrations) packaged in skills or MCP servers.

The split exists because YAML is excellent for describing states and miserable for expressing algorithms. The AI becomes the orchestrator that calls hardened, deterministic functions.

3. Every pillar needs a human owner

A technical architecture without a matching organizational structure is half a solution. Each pillar, and the engine underneath, needs a person who sets the standards the AI executes. The human writes the rules and the specifications; the AI is the arm that carries them out.

Pillar AI-native role Traditional equivalent Responsibility
Structure Application builder Solution architect, tech lead Defines hierarchy and API contracts. Authors project-structure-skill.
Design Design engineer UX engineer, design lead Defines tokens and maintains DESIGN.md. Authors design-tokens-skill.
Content and data Content lead Content strategist, data engineer Defines data structures and Markdown standards. Authors content-md-skill.
Behavior Behavior engineer Domain expert, backend engineer Defines state machines and workflows. Authors state-machine-skill.

A quick diagnostic. Who in your organization catches a hex color hard-coded where a token belongs? Who blocks an API contract that changed without a version bump? Who notices a workflow with a dead state, or invalid data slipping into a JSON file? Without explicit ownership, every failure becomes the last developer's problem. That is the pattern that leaves tens of thousands of AI-introduced issues sitting in production code.

The fifth role: the skills steward

Beyond the domain owners, the skills steward (or platform engineer) owns the deterministic engine itself:

  • the scripts that enforce the specs (validate.py, test.py);
  • the cross-cutting skills: validation, testing, committing;
  • versioning and quality control for the whole skills library.

4. Skills: the engine that runs the specs

A specification describes what the system should be. A skill is what reads the specification and knows what to do with it. It moves the model from parametric guesswork to controlled knowledge.

4.1 How a skill works

A skill is a folder: an entry point (SKILL.md), deterministic scripts and templates. Its front matter enables progressive disclosure: the model sees only the skill's description, and loads the full instructions only when a task matches it. That saves context and cuts noise.

4.2 Three mechanisms of compliance

  1. Progressive disclosure. The model knows only what bears on the task in front of it.
  2. Enforced steps. Clients such as Claude Code expose hooks: lifecycle interceptors that run before or after a tool call. A PreToolUse hook can block a write, hand the model a structured error, or demand human approval before a destructive action. That is the difference between "the model should validate" and "the model cannot proceed without validating". (I wrote up one concrete case in the post on RepoGuards.)
  3. Deterministic verification. The checking scripts are written by people, in Python or JavaScript. The model can't hallucinate a pass; it has to receive a structured success signal from the script.

4.3 A skill group per pillar

Every component type gets its own skill group, maintained by the pillar's owner:

  • Structure (application builder): project-structure-skill checks hierarchy and dependencies; api-contract-skill manages OpenAPI and JSON Schema versions.
  • Design (design engineer): design-tokens-skill enforces tokens and blocks hard-coded values; component-style-skill applies them to UI components.
  • Content and data (content lead): content-md-skill checks front matter and formatting; data-json-skill checks the integrity of structured lists.
  • Behavior (behavior engineer): state-machine-skill checks valid transitions and event coverage; mcp-integration-skill handles retries and auth against external APIs.

4.4 Skills are one layer of several

Skills aren't the whole architecture. Claude Code's documentation lays out its extension layers by what they cost in context:

  • CLAUDE.md: loaded into every request. The most expensive layer.
  • Skills: only their descriptions are always present; the body loads on demand.
  • MCP servers: cheap until a tool is used, since tool search is on by default.
  • Subagents: run in a context of their own, isolated from the main one.
  • Hooks: cost nothing unless they return output.

Skills and MCP complement each other rather than compete. A skill describes the playbook, an MCP server performs the action, and a hook enforces the order.

5. The self-verification loop

What breaks the cycle of frustration is a generate, verify, repair loop:

  1. The agent generates an artifact from the spec.
  2. A deterministic verifier runs: a linter, a type checker, a custom script.
  3. Fail: the agent receives a structured error and repairs.
  4. Pass: a human reviews the final, clean output.

The developer doesn't look at attempt one, two or three. They see only the output that passed every check. Everything before it stays inside the loop.

App Factory, the skills library the box below describes, works this way. Before any store upload, pull_and_diff pulls the live listing and compares it with the local copy, and stops if the two sides changed differently. copy-edit counts the claims in each language and fails a translation that has one claim fewer than the English. Neither check asks the model whether it did well. Each runs a script, and the script returns pass or fail.

6. Skills and MCP as knowledge assets

Value is shifting from static code to knowledge packaged so an agent can use it.

  • Distribution: MCP registries such as Smithery and Glama, and plugin marketplaces in Claude Code, have become the place to find capabilities, much as an app store is for apps.
  • Expertise as a product: domain knowledge (how a payment provider's API behaves, how an infrastructure tool is driven) can now be shipped as a reusable skill or MCP server instead of a wiki page.
  • Context debt: the technical debt of 2026 isn't only tangled code. It is the absence of context engineering. A team without a maintained internal skills library can't use AI safely, and can't use it at scale.

Summary: context engineering as a discipline

The move toward spec-driven development is AI engineering growing up. It went from phrasing questions (prompt engineering), to phrasing requirements (SDD), to designing the whole environment (context engineering).

The four pillars, structure, design, content and behavior, give the direction. Skills, MCP and hooks are the engine. The verify-and-repair loop is the brakes. At the center is the human expert: no longer a fast typist, but the one who sets the standards for systems that build themselves.

Sources and further reading