Sorry, your browser cannot access this site
This page requires browser support (enable) JavaScript
Learn more >

🚀 OpenSpec完全指南：AI编程助手的规范驱动开发工具

技术开发工具AI编程教程

发布于：Oct 14, 2025

详细介绍OpenSpec这个规范驱动开发工具，如何帮助人类和AI编程助手在编写代码前就达成共识，实现确定性和可审查的输出。涵盖安装、配置、使用流程和最佳实践。

📋 前言

AI编程助手虽然功能强大，但当需求分散在聊天历史中时，输出结果往往难以预测。OpenSpec通过轻量级的规范工作流，在开始编写代码前就锁定意图，为你提供确定性的、可审查的输出结果。

OpenSpec是一个开源项目，由Fission AI开发，旨在统一人类和AI编程助手对要构建内容的理解。本文将全面介绍OpenSpec的功能特性、安装方法、使用流程以及最佳实践，帮助你提升AI辅助开发的效率和质量。

🔍 OpenSpec简介

什么是OpenSpec？

OpenSpec是一个规范驱动开发工具，专门为AI编程助手设计。它通过结构化的变更文件夹（提案、任务和规范更新）来保持范围的明确性和可审计性，让人类和AI利益相关者在工作开始前就达成一致。

核心价值

🎯 统一理解：

  • ✅ 人类和AI在开始工作前对规范达成一致
  • ✅ 结构化的变更文件夹保持范围明确
  • ✅ 提供共享可见性，了解提案、活跃或已归档的内容

🔧 工具集成：

  • ✅ 支持你已使用的AI工具：自定义斜杠命令和上下文规则
  • ✅ 无需API密钥，轻量级设置
  • ✅ 适用于现有项目（棕色领域优先）

🚀 核心特性

1. 轻量级工作流

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
┌────────────────────┐    │    Draft Change    │    │    Proposal    │
└────────┬───────────┘    │         share intent with your AI         │
         ▼               └────────────────────┘
┌────────────────────┐    │  Review & Align   │
│  Review & Align   │    │ (edit specs/tasks) │◀──── feedback loop ──────┐
└────────┬───────────┘    └────────┬───────────┘                     │
         │ approved plan                                   │
         ▼                                                │
┌────────────────────┐                                 │
│  Implement Tasks   │──────────────────────────┘
│ (AI writes code)   │
└────────┬───────────┘
         │ ship the change
         ▼
┌────────────────────┐
│  Archive & Update │
│    Specs (source) │
└────────────────────┘

2. 与其他工具的对比

特性 OpenSpec spec-kit Kiro
适用场景 棕色领域(1→n) 绿色领域(0→1) 绿色领域(0→1)
安装难度 ⭐⭐⭐⭐⭐ ⭐⭐⭐ ⭐⭐⭐
API密钥需求 ❌ ✅ ✅
变更跟踪 ✅ 完整 ⭐⭐ 基础 ⭐⭐ 基础
跨规范更新 ✅ 优秀 ⭐⭐ 受限 ⭐⭐ 受限

🛠️ 支持的AI工具

原生斜杠命令支持

这些工具内置了OpenSpec命令，选择OpenSpec集成即可使用：

工具 命令
Claude Code /openspec:proposal, /openspec:apply, /openspec:archive
Cursor /openspec-proposal, /openspec-apply, /openspec-archive
OpenCode /openspec-proposal, /openspec-apply, /openspec-archive
Kilo Code /openspec-proposal.md, /openspec-apply.md, /openspec-archive.md
Windsurf /openspec-proposal, /openspec-apply, /openspec-archive
Codex /openspec-proposal, /openspec-apply, /openspec-archive
GitHub Copilot /openspec-proposal, /openspec-apply, /openspec-archive
Amazon Q Developer @openspec-proposal, @openspec-apply, @openspec-archive

AGENTS.md兼容工具

这些工具自动从openspec/AGENTS.md读取工作流指令：

  • Amp • Jules • Gemini CLI • 其他工具

🚀 安装与初始化

前置条件

  • Node.js >= 20.19.0 - 运行 node --version 检查版本

步骤1：全局安装CLI

1
2
3
4
5
# 使用npm全局安装
npm install -g @fission-ai/openspec@latest

# 验证安装
openspec --version

步骤2：在项目中初始化OpenSpec

1
2
3
4
5
# 进入项目目录
cd my-project

# 运行初始化
openspec init

初始化过程：

  • 📝 提示选择原生支持的AI工具
  • 🔧 自动配置所选工具的斜杠命令
  • 📁 创建openspec/目录结构
  • 📄 在项目根目录写入管理的AGENTS.md存根

验证设置

1
2
3
4
5
6
7
8
# 查看活动变更文件夹
openspec list

# 验证设置并查看活动变更
openspec list

# 检查工具集成状态
openspec doctor

🎯 完整工作流程示例

1. 创建提案

向AI助手请求创建变更提案：

1
2
3
4
5
# 使用自然语言
You: Create an OpenSpec change proposal for adding profile search filters by role and team

# 使用斜杠命令（支持的工具）
/openspec:proposal Add profile search filters

AI操作：

  • 创建openspec/changes/add-profile-filters/文件夹
  • 生成proposal.md、tasks.md和规范差异文件

2. 验证和审查

1
2
3
4
5
6
7
8
# 确认变更文件夹存在
openspec list

# 验证规范格式
openspec validate add-profile-filters

# 审查提案、任务和规范差异
openspec show add-profile-filters

3. 优化规范

迭代规范直到符合需求：

1
2
3
4
You: Can you add acceptance criteria for the role and team filters?

AI: I'll update the spec delta with scenarios for role and team filters.
# 编辑 openspec/changes/add-profile-filters/specs/profile/spec.md 和 tasks.md

4. 实施变更

规范就绪后开始实施：

1
2
3
4
You: The specs look good. Let's implement this change.

# 使用斜杠命令
/openspec:apply add-profile-filters

AI操作：

  • 从openspec/changes/add-profile-filters/tasks.md实施任务
  • 标记任务完成：Task 1.1 ✓, Task 1.2 ✓, Task 2.1 ✓…

5. 归档完成的变更

实施完成后归档变更：

1
2
3
4
You: Please archive the change

# 使用斜杠命令
/openspec:archive add-profile-filters

或手动执行：

1
openspec archive add-profile-filters --yes

结果：

1
✓ Change archived successfully. Specs updated. Ready for the next feature!

📁 目录结构

AI生成的OpenSpec文件结构

当请求AI助手”添加双因素认证”时，会创建：

1
2
3
4
5
6
7
8
9
10
11
12
openspec/
├── specs/
│   └── auth/
│       └── spec.md              # 当前认证规范（如果存在）
└── changes/
    └── add-2fa/                # AI创建的完整结构
        ├── proposal.md         # 为什么和什么变更
        ├── tasks.md            # 实施检查清单
        ├── design.md           # 技术决策（可选）
        └── specs/
            └── auth/
                └── spec.md      # 显示增量的差异

AI生成的规范示例

openspec/specs/auth/spec.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# Auth Specification

## Purpose
Authentication and session management.

## Requirements

### Requirement: User Authentication
The system SHALL issue a JWT on successful authentication.

### Requirement: Two-Factor Authentication
The system SHALL support TOTP-based two-factor authentication.

## Implementation Details

### JWT Configuration
- Algorithm: RS256
- Expiration: 24 hours
- Issuer: your-app.com

🔧 命令参考

基础命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 查看活动变更文件夹
openspec list

# 规范和变更的交互式仪表板
openspec view

# 显示变更详情（提案、任务、规范更新）
openspec show <change>

# 检查规范格式和结构
openspec validate <change>

# 将完成的变更移至archive/（--yes非交互式）
openspec archive <change> [--yes|-y]

高级命令

1
2
3
4
5
6
7
8
9
10
11
# 检查OpenSpec安装和配置
openspec doctor

# 重新生成工具集成
openspec init --force

# 显示帮助信息
openspec --help

# 显示版本信息
openspec --version

🎯 使用场景和最佳实践

1. 功能开发

适用场景：新功能开发、现有功能扩展

工作流程：

  1. 需求分析 → 创建详细的功能提案
  2. 技术设计 → 规范技术实现细节
  3. 任务分解 → 将功能拆分为可执行任务
  4. 代码实施 → AI按照任务逐项实现
  5. 质量审查 → 验证实现符合规范
  6. 变更归档 → 将更新合并到主规范

2. Bug修复

适用场景：复杂Bug修复、系统问题排查

最佳实践：

1
2
3
4
5
6
7
8
# 创建Bug修复提案
/openspec:proposal Fix user authentication timeout issue

# 包含以下内容：
# - 问题重现步骤
# - 根本原因分析
# - 修复方案设计
# - 测试验证计划

3. 重构项目

适用场景：代码重构、架构优化

重构工作流：

  1. 现状分析 → 详细描述当前架构问题
  2. 目标设计 → 定义重构后的理想状态
  3. 迁移计划 → 制定分阶段重构策略
  4. 风险控制 → 识别和缓解重构风险
  5. 实施验证 → 逐步验证重构效果

4. API设计

适用场景：新API开发、API版本升级

API设计规范：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# API Specification: User Management

## Endpoints

### GET /api/users
- Purpose: Retrieve user list
- Authentication: Required
- Parameters: page, limit, filter
- Response: User array with pagination

### POST /api/users
- Purpose: Create new user
- Authentication: Required
- Request Body: User creation data
- Response: Created user object

🔧 高级配置

项目级配置

创建openspec/config.yaml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# OpenSpec项目配置
project:
  name: "my-awesome-project"
  version: "1.0.0"

# 工具集成
tools:
  claude_code:
    enabled: true
    commands:
      - proposal
      - apply
      - archive
  cursor:
    enabled: true

# 工作流配置
workflow:
  auto_validate: true
  require_review: true
  archive_on_complete: true

# 规范模板
templates:
  feature: "templates/feature-proposal.md"
  bugfix: "templates/bugfix-proposal.md"
  refactor: "templates/refactor-proposal.md"

团队协作配置

共享规范模板：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<!-- templates/feature-proposal.md -->
# Feature Proposal: {{feature_name}}

## Overview
{{feature_description}}

## Requirements
### Functional Requirements
- {{req_1}}
- {{req_2}}

### Non-Functional Requirements
- {{nfr_1}}
- {{nfr_2}}

## Acceptance Criteria
- [ ] Criteria 1
- [ ] Criteria 2

## Implementation Tasks
1. [ ] Task 1
2. [ ] Task 2

## Testing Plan
- Unit tests
- Integration tests
- Manual testing

CI/CD集成

GitHub Actions工作流：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# .github/workflows/openspec.yml
name: OpenSpec Validation

on:
  pull_request:
    paths:
      - 'openspec/**'

jobs:
  validate-specs:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4

    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '20'

    - name: Install OpenSpec
      run: npm install -g @fission-ai/openspec@latest

    - name: Validate OpenSpec changes
      run: |
        for change in $(openspec list --format json | jq -r '.active_changes[]'); do
          openspec validate "$change"
        done

🛠️ 故障排除

常见问题及解决方案

Q1: 初始化失败

问题：openspec init 命令失败

解决方案：

1
2
3
4
5
6
7
8
9
10
11
12
# 检查Node.js版本
node --version  # 需要 >= 20.19.0

# 清理npm缓存
npm cache clean --force

# 重新安装OpenSpec
npm uninstall -g @fission-ai/openspec
npm install -g @fission-ai/openspec@latest

# 检查权限
ls -la $(npm config get prefix)/bin/openspec

Q2: 斜杠命令不工作

问题：AI工具无法识别OpenSpec斜杠命令

解决方案：

1
2
3
4
5
6
7
8
9
10
# 重新初始化项目
openspec init --force

# 检查工具配置文件
cat openspec/AGENTS.md

# 验证工具特定配置
ls -la .windsurf/workflows/  # Windsurf
ls -la .kilocode/workflows/  # Kilo Code
ls -la .github/prompts/      # GitHub Copilot

Q3: 规范验证失败

问题：openspec validate 报告格式错误

解决方案：

1
2
3
4
5
6
7
8
# 查看详细错误信息
openspec validate <change-name> --verbose

# 检查规范结构
openspec show <change-name> --structure

# 使用模板重新生成
openspec generate-template --type feature > openspec/changes/<change-name>/proposal.md

Q4: 归档操作失败

问题：openspec archive 无法完成

解决方案：

1
2
3
4
5
6
7
8
# 检查变更状态
openspec list

# 验证所有任务已完成
openspec show <change-name> --tasks

# 强制归档（谨慎使用）
openspec archive <change-name> --force --yes

调试技巧

启用详细日志：

1
2
3
4
5
6
# 设置环境变量
export OPENSPEC_DEBUG=true
export OPENSPEC_LOG_LEVEL=debug

# 运行命令查看详细输出
openspec list --verbose

检查项目状态：

1
2
3
4
5
# 完整的项目健康检查
openspec doctor --verbose

# 查看工具集成状态
openspec integrations --check

📊 最佳实践建议

1. 规范写作原则

CLEAR原则：

  • Concise（简洁） - 规范应该简洁明了
  • Logical（逻辑） - 保持逻辑一致性
  • Executable（可执行） - 规范必须可实施
  • Auditable（可审查） - 变更历史可追踪
  • Reviewable（可审查） - 易于人工审查

2. 团队协作流程

代码审查集成：

1
2
3
4
5
# 在PR中包含OpenSpec变更
echo "OpenSpec changes included in this PR:" > pull-request-template.md
echo "- [ ] Review proposal.md" >> pull-request-template.md
echo "- [ ] Validate tasks.md" >> pull-request-template.md
echo "- [ ] Check spec deltas" >> pull-request-template.md

版本控制最佳实践：

1
2
3
4
5
6
7
8
9
# 忽略临时文件
echo "openspec/changes/*/temp/" >> .gitignore
echo "openspec/changes/*/draft/" >> .gitignore

# 提交规范文件
git add openspec/specs/
git add openspec/changes/*/proposal.md
git add openspec/changes/*/tasks.md
git commit -m "feat: add user authentication spec"

3. 质量保证

自动化检查：

1
2
3
# 在CI/CD中集成规范验证
openspec validate --all || exit 1
openspec lint --strict || exit 1

人工审查清单：

  • 规范目标明确
  • 验收标准具体
  • 任务分解合理
  • 技术方案可行
  • 测试计划完整

🔗 相关资源

官方资源

集成工具

相关规范和标准

🎉 总结

OpenSpec通过规范驱动开发的方式，为AI辅助编程带来了革命性的改进。它不仅解决了AI输出不可预测的问题，还建立了人类与AI协作的标准化流程。

核心价值回顾

✅ 统一理解 - 在编码前就达成共识
✅ 结构化管理 - 变更历史清晰可追踪
✅ 工具集成 - 支持主流AI开发工具
✅ 质量保证 - 通过规范确保输出质量
✅ 团队协作 - 标准化的协作流程

快速开始命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 1. 安装OpenSpec
npm install -g @fission-ai/openspec@latest

# 2. 初始化项目
cd your-project
openspec init

# 3. 创建第一个变更提案
/openspec:proposal Add user authentication

# 4. 实施变更
/openspec:apply add-user-authentication

# 5. 归档完成
/openspec:archive add-user-authentication

关键成功因素

  1. 规范优先 - 始终先定义清晰的规范
  2. 迭代完善 - 通过反馈循环持续改进规范
  3. 工具熟练 - 掌握支持的AI工具的集成方式
  4. 团队协作 - 建立团队级的规范管理流程
  5. 持续改进 - 根据使用经验优化工作流程

开始使用OpenSpec，让你的AI编程助手更加可预测、可控制、可审查！

🚀 开启规范驱动的AI编程新纪元！

更新于：Oct 25, 2025

教程

Claude Code

开发工具

OpenSpec

AI编程助手

规范驱动开发

Fission AI

评论