Specification-First Agentic Development: A New Workflow for AI-Driven Engineering

Core Principles of Specification-First Development

Specification-first agentic development shifts the paradigm of AI coding from iterative prompting to a structured, gate-checked process. By requiring agents to produce a YAML-based specification before implementation, the workflow ensures that goals, constraints, and definitions of 'done' are explicitly reviewed against the existing codebase. This approach aims to eliminate the ambiguity often found in "vibe coding" by forcing the agent to cite specific files and lines of code as evidence for its proposed changes.

The Four-Stage Lifecycle

Every piece of work follows a rigorous four-stage process designed to maintain system integrity:

  1. create-spec: The agent defines the goal, required steps, and facts (with file/line citations) without writing any application code.
  2. review-spec: A fresh agent instance, lacking previous conversation history, evaluates the spec against the current codebase to identify potential conflicts or missing requirements.
  3. apply-spec: The agent implements the code, wiring, and tests based strictly on the reviewed specification.
  4. deliver-spec: The change is pushed through a commit gate that verifies all tests and build stages pass before the pull request is opened.

Parallel Execution and State Management

To scale development, the system utilizes individual branches and worktrees for every spec. Because IDs are generated from the system clock, concurrent agents can work on different features without collision. State is persisted in a context.yaml file, allowing the agent to resume work after interruptions. For larger features, the deliver-series command allows developers to group multiple specs, building them in parallel where dependencies allow, and merging them into a single pull request.

Documentation as a Side Effect

One of the primary advantages of this method is the automatic generation of project history. As the agent builds, it logs every non-obvious decision in a YAML file, capturing the rationale behind architectural choices (e.g., why a specific library was chosen over another). This creates a living record of the project's evolution that exists alongside the code, eliminating the need to maintain separate, stale wiki documentation.

Community Perspectives and Critiques

While the approach offers a structured way to manage agentic workflows, community discussion highlights several common concerns regarding the efficacy of spec-driven development in real-world environments:

  • The "Code is the Spec" Argument: Some developers argue that a truly precise specification is effectively just code, and that attempting to define complex systems in a separate document introduces unnecessary overhead.
  • Discovery and Iteration: Critics note that in many product environments, requirements are not fully known upfront. One user commented: > "The problem is that you typically don't know what you don't know upfront for most product based decisions. Going back and forth in the spec to fix problems is a huge mistake."
  • Alternative Approaches: Proponents of "vibe coding" suggest that generating a quick-and-dirty prototype first is a more effective way to discover requirements, which can then be used as the basis for the final, polished implementation.
  • Tooling Comparisons: Users have compared this approach to existing frameworks like Spec Kit and BMAD, questioning the specific benefits of this implementation over established alternatives. The maintainers emphasize that their system's unique value lies in the pre-build review gate and the automated enforcement of commit-stage checks.

Sources