Description
Spec-first Agentic Development introduces a structured approach to working with AI coding agents, ensuring that every change is initiated by a clearly defined and reviewed specification. This methodology aims to enhance the reliability and maintainability of code developed by AI agents by integrating human oversight and automated checks throughout the development lifecycle.
Read More
The core principle involves starting every development task with a written specification stored in the repository. This spec outlines the goal, relevant facts (including file and line references), steps to be taken, and precise 'done' criteria. Before any code is written, a fresh reviewer examines the spec against the existing codebase to verify its accuracy and feasibility. Once approved, an AI agent proceeds to build the feature on its own isolated branch and worktree. The final commit is only allowed to land in the main repository after all predefined checks and tests pass, ensuring code quality and adherence to the spec.
This system differs significantly from traditional 'vibe coding' by replacing ad-hoc prompts with a reviewed, persistent specification. It logs each decision made by the agent with its reasoning, providing a clear audit trail and reducing the need for post-development documentation. Specs are designed to pin down intent and architecture rather than being overly precise code generators, with tests and commit gates supplying the necessary precision. Old specs are treated as immutable change records, similar to commits, and are not updated, preventing staleness.
Spec-first Agentic Development supports parallel development, allowing multiple agents to work on different specs simultaneously using unique branch and worktree IDs. The process is uninterrupted, as reviewed specs pre-answer open questions, enabling agents to build directly to the done criteria. The entire workflow is structured, with one spec corresponding to one branch and one commit, simplifying pull requests and ensuring consistency. State is maintained in `context.yaml`, making work resumable even after restarts.
The method, templates, and the Claude Code plugin are all MIT licensed, making it a cost-free solution. While the Claude Code plugin automates bookkeeping and gate functions, the methodology can also be adopted with other agents like Codex, Cursor, or Copilot by following `AGENTS.md` and installing a git commit-msg hook for the gate. This approach was developed and refined through the creation of Agent Smith, an open-source agentic software factory, demonstrating its practical application and effectiveness.
- CategoryAI Coding Assistants
- Pricing ModelFree
- DeploymentCloud
- PlatformsWeb
Spec-first Agentic Development's Core Features
Specification-driven development for AI coding agents
Reviewed specs checked against code before building
Isolated worktrees for each development task
Gated commits requiring all checks to pass
Persistent specs stored in the repository
Decision logging with reasoning for traceability
Support for parallel development with unique branch IDs
Resumable workflows with state stored in context.yaml
MIT licensed method, templates, and Claude Code plugin
Compatibility with Codex, Cursor, Copilot, and terminal
Git commit-msg hook for enforcing commit gates
Automated evidence checking for spec citations
Structured pull requests for single or series of specs
Contexts and rules generated from existing codebase
No hand-written code required for Agent Smith's build process
How to use Spec-first Agentic Development?
Install Plugin/Hook: Install the Claude Code plugin or the git commit-msg hook in your project clone.
Bootstrap Project: Run /spec-first:bootstrap-project to generate contexts and rules from your existing code.
Create Spec: Define a new task with a goal, steps, facts, and done criteria using the create-spec skill.
Review Spec: Have a fresh reviewer check the spec against the code for accuracy and feasibility.
Apply Spec: The agent builds the spec on its own branch and worktree, following project rules.
Deliver Spec: Commit the changes through the gate, ensuring all checks pass, and open a pull request.
Deliver Series: For larger changes, use /spec-first:deliver-series to manage and deliver multiple interdependent specs.
Spec-first Agentic Development's Use Cases
- AI Agent Code Development
- Ensuring Code Quality
- Managing Complex Projects
- Enhancing Code Traceability
- Facilitating Code Reviews
- Automating Development Workflows
- Onboarding New Developers
- Integrating with Existing Tools
