How to Use OpenSpec for Spec-Driven AI Development Workflow

Mar 27, 2026

AI coding assistants like Claude Code and GitHub Copilot are incredibly fast at generating code. But here’s the problem I kept running into: after a week of AI-assisted development, I couldn’t answer simple questions like “Why did we add this service?” or “What scenarios did we consider?”

I’d look at my git history and see a bunch of commits with vague messages. The code worked, but the reasoning behind each change was lost. This became especially painful when I needed to modify something I’d built weeks earlier—I had no context on what decisions were made or why.

That’s when I discovered OpenSpec, a spec-driven development framework that enforces documentation at every stage of the development process. Let me show you how it works.

The Core Problem: Lost Context in AI Development

When I use AI coding assistants, the typical workflow looks like this:

Me: "Add a background service that starts on app launch"
AI: *generates code*
Me: *commits with message "Add background service"*
[3 weeks pass]
Me: "Why does this service exist? What happens if it fails to start?"
Git: *shrugs in commit history*

The code gets written, but the why and how decisions disappear into the ether. This becomes critical in team environments where multiple developers need to understand the reasoning behind changes.

OpenSpec’s Solution: The Artifact Chain

OpenSpec solves this by forcing you to create a chain of artifacts for every change. Each artifact has a specific responsibility:

proposal.md     → Why are we doing this?
    ↓
design.md       → How will we do it technically?
    ↓
specs/*.md      → What exactly are we building?
    ↓
tasks.md        → What are the implementation steps?
    ↓
implementation  → The actual code changes
    ↓
archive         → Preserved history for future reference

Let me show you a real example of how this works.

Installing OpenSpec

First, install the OpenSpec CLI:

npm install -g @fission-ai/openspec@latest

Once installed, OpenSpec provides slash commands that integrate with AI coding assistants. These commands guide the AI through the artifact creation process.

The Workflow: A Practical Example

Let’s say I want to add a feature that checks and starts a background service on app launch. Here’s how OpenSpec transforms this from a vague idea into documented, traceable code.

Step 1: Generate All Artifacts

Instead of asking the AI to “just add the feature,” I use the fast-forward command:

/opsx:ff Check and start UniCloudService background service on launch

The AI generates four artifacts automatically:

1. proposal.md — The “Why”

# Proposal: Start UniCloudService on Launch

## Goals
- Ensure UniCloudService starts automatically when app launches
- Handle edge cases gracefully (not registered, already running, start failure)

## Non-Goals
- Modifying the UniCloudService implementation itself
- Adding configuration options for the startup behavior

## Impact
- Users won't need to manually start the service
- App remains functional even if service fails to start

2. design.md — The “How”

# Design: UniCloudService Startup

## Technical Approach
- Reuse existing ServiceUtils for service management
- Add startup logic in Application.onCreate()
- Use non-blocking async call for service start

## Alternatives Considered
1. Blocking start on main thread — rejected: UI would freeze
2. Scheduled periodic checks — rejected: unnecessary complexity

## Risk Assessment
- Service start failure: handled with fallback
- Race conditions: ServiceUtils already handles this

3. specs/*.md — The “What”

# Spec: UniCloudService Startup

## Scenario 1: Service Not Registered
WHEN the app launches and UniCloudService is not registered
THEN register the service and start it

## Scenario 2: Service Already Running
WHEN the app launches and UniCloudService is already running
THEN do nothing (no-op)

## Scenario 3: Service Not Running
WHEN the app launches and UniCloudService is registered but not running
THEN start the service

## Scenario 4: Service Start Failure
WHEN the app launches and UniCloudService fails to start
THEN log the error and continue (non-blocking)

4. tasks.md — The Steps

# Tasks: UniCloudService Startup

- [ ] Add startup check in Application.onCreate()
- [ ] Implement ServiceUtils.startIfNotRunning()
- [ ] Add error handling and logging

Step 2: Implement the Tasks

Now I can ask the AI to implement each task:

/opsx:apply

The AI:

Implements the first unchecked task
Verifies the implementation against the specs
Marks the task as complete
Moves to the next task

This verification step is crucial—the AI checks that its implementation actually matches the WHEN/THEN scenarios defined in the specs.

Step 3: Archive the Change

Once all tasks are complete:

/opsx:archive

This moves everything to an archive directory with a timestamp:

openspec/
├── specs/                          # Main specs (project knowledge base)
│   └── disk-mount/spec.md
│
└── changes/
    ├── start-unicloud-service/     # Active change
    │   ├── proposal.md
    │   ├── design.md
    │   ├── specs/
    │   │   └── unicloud-service-startup/spec.md
    │   └── tasks.md
    │
    └── archive/                    # Archived changes
        └── 2026-03-25-start-unicloud-service/
            ├── proposal.md
            ├── design.md
            ├── specs/
            │   └── unicloud-service-startup/spec.md
            └── tasks.md

Now, three months later, when someone asks “Why did we add this startup check?”, I can find the answer in seconds.

The Delta Spec System: Keeping Knowledge Synchronized

One feature that sets OpenSpec apart is its delta spec system. When you create a change, you create “delta specs” that describe only what’s different from the main specs. When you archive a change, these deltas are synchronized back to the main specs.

Main Specs (project knowledge)
        ↑
        │ sync on archive
        │
Delta Specs (change-specific)

This means your project’s knowledge base evolves with each change, staying current and comprehensive.

Available OpenSpec Commands

Here’s a quick reference of all the commands:

Command	Purpose	When to Use
`/opsx:explore`	Free-form exploration	When you need to understand the codebase before making changes
`/opsx:propose`	Generate proposal and artifacts	For standard changes that need documentation
`/opsx:ff`	Fast-forward: all artifacts at once	For well-understood changes you want to implement quickly
`/opsx:apply`	Implement tasks one by one	When you’re ready to write code
`/opsx:verify`	Verify against specs	After implementation to ensure correctness
`/opsx:archive`	Archive completed changes	When a change is fully implemented and verified

Why This Matters for Teams

In my solo projects, OpenSpec seemed like overkill at first. But in team environments, it becomes invaluable:

New team members can understand the “why” behind every feature by reading archived proposals and designs.
Code reviews have context — reviewers can read the spec to understand what scenarios were considered.
Debugging is faster — when something breaks, you can trace back to the design decisions.
Compliance and audits — every change has a documented trail from proposal to implementation.

When OpenSpec Might Be Overkill

I’ll be honest—OpenSpec isn’t necessary for every project:

Prototypes and throwaway code: The artifact chain adds overhead.
Trivial fixes: Typo corrections don’t need proposals.
Solo projects with short lifespan: If you’re the only one who’ll ever see the code.

But for anything that needs to last or be maintained by others, the upfront cost of documentation pays for itself many times over.

Getting Started

If you want to try OpenSpec:

Install it globally: npm install -g @fission-ai/openspec@latest
Start with /opsx:explore on your existing project to understand how it analyzes code
Try /opsx:ff on a small feature to see the full artifact chain
Review what it generates before running /opsx:apply

The key insight is that OpenSpec shifts you from “write code first, document later (maybe)” to “document thoroughly, then implement against that documentation.” Your future self (and your teammates) will thank you.

Spec-Driven Development: Similar to test-driven development, but focuses on specifications before tests
Artifact-Based Workflows: Common in enterprise environments (RFCs, ADRs) but OpenSpec makes it accessible for AI-assisted development
Delta Synchronization: Borrowed from distributed systems concepts, keeping local changes synchronized with a central knowledge base

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!