5K

Specification-Driven Agent Development

Makes a version-controlled spec file the agent's main input, scaffolds code from it, and links each artifact back to a spec clause

emerging Updated 2026-10-13 By Nikola Balic (@nibzard) Based on Jory Pestorious (AI Engineer World's Fair 2025)
View .md Edit on GitHub
Add to Pack
or

Saved locally in this browser for now.

Cite This Pattern
APA 
Nikola Balic (@nibzard) (2026). Specification-Driven Agent Development. In *Awesome Agentic Patterns*. Retrieved October 14, 2026, from https://agentic-patterns.com/patterns/specification-driven-agent-development
BibTeX 
@misc{agentic_patterns_specification-driven-agent-development,
  title = {Specification-Driven Agent Development},
  author = {Nikola Balic (@nibzard)},
  year = {2026},
  howpublished = {\url{https://agentic-patterns.com/patterns/specification-driven-agent-development}},
  note = {Awesome Agentic Patterns}
}

Use when

  • Loose prompts cause agents to drift from stakeholder intent
  • Requirements can be written as Markdown, OpenAPI, or JSON Schema
  • Team needs audit trails from code back to requirements

Avoid when

  • Requirements are too coarse or unknown to specify
  • Quick exploratory work where writing a spec costs more than it saves

Problem

Hand-crafted prompts or loose user stories leave room for ambiguity; agents can wander, over-interpret, or produce code that conflicts with stakeholder intent.

Solution

Adopt a spec-first workflow in which a formal specification file (e.g., Markdown, OpenAPI, JSON Schema) is the agent's primary input and source of truth.

  • Parse spec → agent builds an explicit task graph.
  • Scaffold project structure & stub code straight from the spec.
  • Enforce that every generated artifact links back to a spec clause.
  • Iterate only by editing the spec, not by re-prompting ad-hoc.
if new_feature_requested:
    write_spec(update)
    agent.sync_with(spec)

Core Framework (SPEC/EXPOSURE/TASK DELTA):

  • SPEC: Version-controlled markdown capturing intent and values
  • EXPOSURE: What customers experience; spec is permanent, code is temporary
  • TASK DELTA: Continuous loop evaluating SPEC ↔ PRODUCT to identify gaps

Vendor tooling (2025-2026): GitHub Spec Kit drives a /specify → /plan → /tasks → /implement command sequence from a constitution and spec documents, and AWS Kiro ships spec-driven agentic development in the editor.

How to use it

Write specifications first (Markdown files in git), then let agents scaffold from them. Documentation IS the spec—write it before code.

Use tiered review: AI for patterns, humans for logic. Parallelize via git worktrees or multiple agents coordinating through shared spec files.

Pitfalls: coarse or under-specified requirements still propagate errors.

Trade-offs

  • Pros: repeatable, audit-friendly, easy diffing.
  • Cons: up-front spec writing effort; initial ramp-up for teams new to spec formats.

References