🚀 OpenSpec 完整学习教学文档

规范驱动的AI编程助手开发框架详解

📋 目录

🔍 OpenSpec简介

什么是OpenSpec？

OpenSpec 是一个开源的规范驱动开发工具，专门为AI编程助手设计。它通过轻量级的工作流程，确保人类开发者和AI助手在编写任何代码之前就能对需求达成明确共识。

核心价值

🎯 统一理解 🔧 工具集成 📊 变更管理
✅ 人类和AI在开始工作前对规范达成一致 ✅ 支持主流AI工具的斜杠命令 ✅ 结构化的变更文件夹保持范围明确
✅ 提供共享可见性，了解提案、活跃或已归档的内容 ✅ 无需API密钥，轻量级设置 ✅ 完整的变更生命周期管理
✅ 减少因需求不明确导致的返工 ✅ 适用于现有项目（棕色领域优先） ✅ 便于审计和追踪历史变更

与其他工具对比

graph LR
    A[OpenSpec] --> B[棕色领域 1→n]
    C[Spec Kit] --> D[绿色领域 0→1]
    E[Kiro] --> F[绿色领域 0→1]
  
    G[OpenSpec优势] --> H[完整变更跟踪]
    G --> I[无需API密钥]
    G --> J[跨规范更新优秀]

🧩 核心概念

1. 双文件夹模型

OpenSpec使用双重目录结构来管理规范和变更：

openspec/
├── specs/                   # 当前真理源规范
│   └── auth/
│       └── spec.md         # 正式规范文档
├── changes/                 # 变更提案
│   └── feature-name/
│       ├── proposal.md     # 变更提案
│       ├── tasks.md        # 实施任务
│       ├── design.md       # 技术设计（可选）
│       └── specs/          # 规范差异
│           └── auth/
│               └── spec.md  # 显示增量差异
├── project.md              # 项目级约定
└── AGENTS.md               # AI工具指令

2. 规范格式标准

规范使用标准Markdown格式，包含以下元素：

# 认证系统规范

## Purpose
认证和会话管理。

## Requirements

### Requirement: 用户认证
系统 SHALL 在成功认证时签发JWT令牌。

#### Scenario: 有效凭据
- WHEN 用户提交有效凭据
- THEN 返回JWT令牌
- AND 令牌包含用户ID
- AND 令牌24小时内有效

3. Delta格式

变更通过"差异"格式显示，清晰标明变更类型：

  • 🟢 ADDED Requirements - 新增功能需求
  • 🟡 MODIFIED Requirements - 现有功能的修改
  • 🔴 REMOVED Requirements - 已废弃的功能

🚀 安装与初始化

系统要求

要求项 最小版本 推荐版本
Node.js 20.19.0 Latest LTS
Git 2.30+ Latest
操作系统 macOS/Linux/Windows macOS/Linux

安装方式（多选一）

方式 A：免安装模式（推荐新手）
# 使用 npx（无需安装）
npx openspec@latest --version
npx openspec@latest list

# 或使用 pnpm
pnpm dlx openspec@latest --version
方式 B：npm 全局安装
npm install -g @fission-ai/openspec@latest
openspec --version
方式 C：pnpm 全局安装（Windows推荐）
pnpm install -g @fission-ai/openspec@latest
openspec --version

项目初始化

步骤1：创建OpenSpec目录
cd your-project
openspec init

初始化过程中会：

  1. 📝 提示选择AI工具（Claude Code、Cursor等）
  2. 🔧 自动配置斜杠命令
  3. 📁 创建openspec/目录结构
  4. 📄 生成AGENTS.md和project.md文件
步骤2：验证安装
openspec list
openspec doctor
步骤3：本地化配置（推荐）

让AI助手将英文配置文件翻译为中文：

请把openspec文件夹下AGENTS.md、project.md内容翻译成中文

🔄 核心工作流程

OpenSpec遵循四步工作流程：
反馈循环
任务检查
起草变更提案
审查与对齐
实施任务
归档与更新

阶段1：起草变更提案

# 使用AI助手创建提案
/openspec:proposal Add user authentication feature

# AI自动创建：
# - proposal.md (为什么变更)
# - tasks.md (实施清单)
# - 规范差异文件 (变更内容)

阶段2：审查与对齐

# 查看变更详情
openspec show feature-name

# 验证规范格式
openspec validate feature-name

# 与AI迭代完善
You: 能否为角色和团队过滤器添加验收标准？
AI: 我来更新规范差异，添加详细的验收场景

阶段3：实施任务

# 开始实施
/openspec:apply feature-name

# AI按tasks.md逐项执行：
# Task 1.1 ✓
# Task 1.2 ✓
# Task 2.1 ✓

阶段4：归档与更新

# 归档完成的变更
/openspec:archive feature-name

# 或手动执行
openspec archive feature-name --yes

📚 命令参考手册

基础命令概览

命令 功能 使用场景
openspec list 查看所有活动变更 日常管理
openspec view 交互式规范仪表板 全局概览
openspec show <change> 显示变更详情 详细审查
openspec validate <change> 验证规范格式 质量检查
openspec archive <change> 归档变更 完成流程

高级管理命令

# 系统诊断
openspec doctor --verbose

# 强制重新初始化
openspec init --force

# 更新工具集成
openspec update

# 严格验证（提交前推荐）
openspec validate <change> --strict

# 显示所有规范
openspec list --specs

AI工具斜杠命令

AI工具 命令格式 示例
Claude Code /openspec:command /openspec:proposal
Cursor /openspec-command /openspec-proposal
GitHub Copilot /openspec-command /openspec-proposal
Amazon Q Developer @openspec-command @openspec-proposal

🎮 实战案例演练

场景：扩展API功能

背景信息

假设我们要为一个现有的API项目添加即梦4.0文生图功能。

步骤1：需求收集
/openspec:proposal 请基于curl4.md内容以及现有images.ts代码，新增补充基于high_aes_general_v40模型功能，请修改images.ts实现high_aes_general_v40模型能力。请不要先写代码，先把需求整理好，结合原来的项目梳理项目新增的变革需求。
步骤2：AI生成提案

AI会自动创建：

  • openspec/changes/add-high-aes-v40/proposal.md
  • openspec/changes/add-high-aes-v40/tasks.md
  • openspec/changes/add-high-aes-v40/specs/

示例tasks.md内容：

## 1. 实施high_aes_general_v40模型支持
- [ ] 1.1 在MODEL_MAP中添加jimeng-4.0模型映射
- [ ] 1.2 更新DEFAULT_MODEL配置（如需要）
- [ ] 1.3 验证模型参数配置正确性

## 2. 优化图片生成参数支持
- [ ] 2.1 支持更高的分辨率配置（2560x1440）
- [ ] 2.2 确保与现有参数的兼容性
- [ ] 2.3 添加分辨率比例验证

## 3. 增强批量生成能力
- [ ] 3.1 优化generateImages函数支持批量生成
- [ ] 3.2 确保与现有API接口的兼容性
- [ ] 3.3 添加错误处理和日志记录

## 4. 测试和验证
- [ ] 4.1 单元测试：模型映射功能
- [ ] 4.2 集成测试：图片生成流程
- [ ] 4.3 验证与curl4.md中描述的参数一致性
步骤3：实施变更
/openspec:apply add-high-aes-v40

AI会逐个完成tasks.md中的任务，标记进度：

## 执行进度
- [x] 1.1 在MODEL_MAP中添加jimeng-4.0模型映射 ✓
- [x] 1.2 更新DEFAULT_MODEL配置 ✓
- [x] 1.3 验证模型参数配置正确性 ✓
- [ ] 1.4 ... (进行中)
步骤4：人工验证
# 启动项目进行测试
npm run build
npm run dev

# 使用API工具测试（如Apifox）
curl -X POST http://localhost:3000/api/generate-image \
  -d '{"model": "high_aes_general_v40", "prompt": "测试图片"}'
步骤5：项目归档
/openspec:archive add-high-aes-v40

⚙️ 高级配置技巧

项目级配置

创建 openspec/config.yaml：

project:
  name: "my-awesome-project"
  version: "1.0.0"
  description: "AI驱动的现代Web应用"

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"

团队协作模板

创建共享规范模板 templates/feature-proposal.md：

# 功能提案：{{feature_name}}

## 概述
{{feature_description}}

## 需求分析
### 功能性需求
- {{req_1}}
- {{req_2}}

### 非功能性需求
- {{nfr_1}}
- {{nfr_2}}

## 验收标准
- [ ] 标准1：{{acceptance_1}}
- [ ] 标准2：{{acceptance_2}}

## 实施任务
1. [ ] 任务1：{{task_1}}
2. [ ] 任务2：{{task_2}}

## 测试计划
- 单元测试
- 集成测试
- 手动测试

CI/CD集成

GitHub Actions工作流配置：

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

👥 团队协作指南

团队采用路线图

timeline
    title OpenSpec 团队采用时间线
    Week 1 : 试点项目<br>选择1-2个小项目
    Week 2-3 : 团队培训<br>建立规范模板
    Week 4 : 标准化流程<br>集成CI/CD验证
    Week 5+ : 全面推广<br>持续优化流程

版本控制最佳实践

.gitignore 配置
# OpenSpec 临时文件
.openspec/cache/
openspec/changes/*/temp/
openspec/changes/*/draft/

# AI生成的临时内容
*.ai-tmp.*
.ai-backup/
提交规范
# 好的提交信息
git commit -m "feat: add user authentication spec"
git commit -m "fix: update profile filter validation rules"

# 提交前必运行
openspec validate --all --strict

代码审查集成

创建 PR 模板 .github/pull_request_template.md：

## OpenSpec 变更检查清单

- [ ] 已检查 proposal.md 和需求完整性
- [ ] 已验证 tasks.md 任务分解合理性
- [ ] 已审查规范差异的准确性
- [ ] 已通过 openspec validate 检查
- [ ] 相关测试已通过

## 变更影响
- [ ] 影响数据库架构
- [ ] 影响API接口
- [ ] 影响前端组件
- [ ] 需要用户文档更新

## 测试环境
- 测试地址：[填写测试地址]
- 测试账号：[填写测试凭证]

🛠️ 故障排除与FAQ

常见问题解决

Q1: 初始化失败

症状：openspec init 命令失败

# 解决方案
node --version  # 确认版本 >= 20.19.0
npm cache clean --force
npm uninstall -g @fission-ai/openspec
pnpm install -g @fission-ai/openspec@latest  # Windows推荐pnpm
Q2: 斜杠命令不工作

症状：AI工具无法识别OpenSpec命令

# 解决方案
openspec update  # 刷新AI指导
cat openspec/AGENTS.md  # 检查文件内容

# 检查特定工具配置
ls -la .cursor/rules/
ls -la .github/prompts/
Q3: 规范验证失败

症状：openspec validate 报告格式错误

# 详细诊断
openspec validate <change-name> --verbose
openspec show <change-name> --structure

# 重新生成模板
openspec generate-template --type feature > openspec/changes/<name>/proposal.md
Q4: 归档操作失败

症状：openspec archive 无法完成

# 强制归档
openspec archive <change-name> --force --yes

# 检查任务状态
openspec show <change-name> --tasks

调试技巧

启用详细日志
export OPENSPEC_DEBUG=true
export OPENSPEC_LOG_LEVEL=debug
openspec list --verbose
项目健康检查
# 全面的项目诊断
openspec doctor --verbose
openspec integrations --check

性能优化

# config.yaml 性能配置
performance:
  cache_enabled: true
  parallel_validation: true
  max_concurrent_tasks: 4

optimization:
  skip_if_unchanged: true
  incremental_build: true

📈 最佳实践总结

CLEAR原则

原则 含义 实践要点
Concise 简洁 规范应该简洁明了，避免冗余
Logical 逻辑 保持逻辑一致性，前后呼应
Executable 可执行 规范必须可实施和测试
Auditable 可审查 变更历史可追踪和审计
Reviewable 可审查 易于人工审查和理解

质量保证清单

规范编写阶段
  • 目标明确，范围清晰
  • 验收标准具体可测试
  • [ ]任务分解粒度合理
  • [ ]技术方案经过评估
  • 测试计划完整覆盖
实施阶段
  • AI按照任务清单执行
  • [ ]每步都有验证检查
  • [ ]异常情况有处理方案
  • [ ]代码质量符合标准
  • [ ]文档同步更新
归档阶段
  • 所有任务完成验证
  • 规范差异合并正确
  • 变更历史完整记录
  • 影响分析完成
  • 团队知识更新

团队文化建设

推广建议
  1. 🎯 小处着手 - 从简单功能开始试点
  2. 📊 数据驱动 - 收集使用数据和效果指标
  3. 🔄 持续改进 - 根据反馈优化流程
  4. 📚 知识共享 - 建立最佳实践知识库
  5. 🏆 激励机制 - 设立质量改进奖励

成功指标

指标类型 衡量标准 目标值
效率 需求明确时间 减少50%
质量 返工率 降低60%
协作 团队共识度 提升80%
维护 文档更新率 达到95%

🔗 相关资源

官方资源

支持的AI工具

学习资源

🎉 总结

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

核心价值回顾

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

快速开始命令

# 1. 安装
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. 📈 持续改进 - 根据使用经验优化工作流程

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

📚 本文档基于OpenSpec官方文档和实战经验整理，建议收藏并在实际项目中反复参考。

# 学习
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

OpenAI Codex CLI 完全指南：AI 编程助手的终端革命

avatar AI编程社区
cover

GitHub 学生认证（保姆级教学）

avatar AI编程社区
cover

AI能写代码，但提不出好问题：技术人如何用“问题定义力”构建认知护城河？

avatar AI编程社区