Advanced AI Programming: A Step‑by‑Step OpenSpec Development Guide

What Is OpenSpec?

OpenSpec is a specification‑driven development tool created for AI coding assistants. It enforces a lightweight workflow that requires developers to write clear requirements (Specs) before the AI generates code, preventing mis‑understandings and “code mountains.”

Core Characteristics

Spec First : Define requirements up front to avoid rework.

Lightweight & Easy : No API keys, minimal setup.

Broad Compatibility : Works with Cursor, Claude Code, and other mainstream AI tools.

Change Traceability : Records modification history via proposal documents.

Installation & Preparation

Ensure Node.js ≥ 20.19.0 is installed: node -v Install OpenSpec globally: npm install -g @fission-ai/openspec Verify the installation: openspec --version Initialize a project in the repository root: openspec init This command asks which AI tools you use, configures slash commands, and creates an openspec/ folder.

Standard Directory Structure

openspec/
├── AGENTS.md      # Agent onboarding guide
├── project.md     # Project‑level context (tech stack, architecture, coding standards)
├── specs/         # Active feature specifications
│   ├── login.md
│   └── user-profile.md
├── changes/       # In‑progress change plans
│   └── feature-login/
│       ├── proposal.md   # Why the change is needed
│       ├── tasks.md      # Implementation steps
│       └── design.md     # Optional technical design
└── archive/       # Completed and archived changes

Key Files Explained

project.md

: Provides the AI with “brain background” – tech stack (e.g., Vue 3, TailwindCSS, Pinia), directory conventions, and coding standards. AGENTS.md: Gives the AI operational instructions, such as how to handle @specs/xxx.md references and the requirement to obey the rules defined in project.md.

Document Editing Rules (Syntax Rules)

OpenSpec relies on strict Markdown headings so the parser can locate requirements and scenarios.

Requirement Format

Each feature starts with: ### Requirement: <Name> Example:

# ## Requirement: Username Validation
The username must be unique.

Scenario Format

Every requirement must contain at least one scenario, introduced with a four‑hash heading:

#### Scenario: Empty Input
GIVEN the user leaves the field blank
WHEN the login button is clicked
THEN show error "Username and password cannot be empty"
AND do not send a request

Incorrect formats (e.g., missing the four‑hash heading) may cause the AI to miss critical logic.

Hands‑On: Using OpenSpec in Cursor

Cursor is highlighted as a suitable IDE because it can read the Spec files and generate code accordingly.

Step 1 – Create a Spec File

# Login Form Component Spec
## Goal
Create a Vue 3 login component.
### Requirement: UI Structure
The login component must contain all user interaction elements.
#### Scenario: Default Display
GIVEN the login page is opened
THEN show a username input, a password input (type="password"), a login button, and a "Forgot password" link.
### Requirement: Validation Logic
User input must satisfy basic validation rules.
#### Scenario: Empty Value Check
GIVEN username or password is empty
WHEN the login button is clicked
THEN display error "Username and password cannot be empty"
AND do not trigger a login request.
### Requirement: Style Guidelines
The component must follow the design system.
#### Scenario: Visual Style
GIVEN the component is rendered
THEN style it with TailwindCSS, center it, use a white background, and apply rounded‑card styling.

Step 2 – Generate Code in Cursor

Open the Cursor chat panel (Cmd+L / Ctrl+L) and send the prompt:

@specs/login-form.md please generate the file src/components/LoginForm.vue based on this Spec.

Cursor will reference the Spec via the @ symbol and produce code that matches the listed requirements.

Standard vs. Conversational Writing

Standard – Precise headings, exhaustive edge‑case coverage; yields highly reliable AI output.

Conversational – Free‑form description; faster to write but may miss details, suitable for simple UI demos.

Hands‑On: Using OpenSpec in Antigravity

Antigravity, a multi‑agent IDE, is suited for more complex refactoring tasks.

Step 1 – Define a Refactor Spec

# API Refactor Spec
## Goal
Refactor <code>src/api/pass-user.js</code> to TypeScript style.
### Requirement: Response Interception
All API requests must handle responses uniformly.
#### Scenario: Interceptor Configuration
GIVEN any API request is made
THEN process the response through an <code>axios</code> interceptor, returning the <code>data</code> field on success and showing a unified error message on failure.
### Requirement: Type Definitions
All interfaces must have explicit TypeScript types.
#### Scenario: Interface Definition
GIVEN a new API function is defined
THEN provide a Request Interface and a Response Interface.
### Requirement: Function Signature
Keep the original function name but restructure parameters.
#### Scenario: Parameter Destructuring
GIVEN the original API function is refactored
THEN rename the signature to <code>function login({ username, password })</code>.

Step 2 – Invoke the Agent

I need to refactor the API module. Refer to refactor-api.md and modify src/api/pass-user.js accordingly.

The Antigravity agent reads the Spec, proposes an implementation plan, and, after confirmation, rewrites the code automatically.

Advanced Tip: Automated Self‑Correction

After code generation, you can ask the AI to verify the implementation against the Spec:

Has the code been written? Please check specs/login-form.md line by line and fix any missing requirements.

This “self‑correction” loop dramatically improves code quality.

Conclusion

OpenSpec is a lightweight workflow tool that turns ideas into detailed, machine‑readable specifications.

Installation is straightforward, and the tool integrates seamlessly with Cursor and Antigravity.

Using the strict Requirement / Scenario format yields reliable AI‑generated code; the conversational style is optional for simple tasks.

The approach clarifies development intent, reduces rework, and makes future maintenance and feature addition transparent.