OpenSpec 完整学习教学文档

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

目录

• OpenSpec简介
• 核心概念
• 安装与初始化
• 核心工作流程
• 命令参考手册
• 实战案例演练
• 高级配置技巧
• 团队协作指南
• 故障排除与FAQ
• 最佳实践总结

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

该命令将自动执行以下操作：

• 提示选择所使用的AI工具（如Claude Code、Cursor等）
• 配置对应的斜杠命令支持
• 生成 openspec/ 文件夹及其子结构
• 创建 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

系统将自动生成以下文件：

• proposal.md —— 变更背景与目标说明
• tasks.md —— 实施任务清单
• 规范差异文件 —— 明确具体的变更内容

阶段2：审查与对齐

确认规范细节并进行迭代完善：

# 查看具体变更信息
openspec show feature-name

# 检查规范格式是否合规
openspec validate feature-name

示例交互：

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

命令参考手册

基础命令概览

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

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 specs

实战案例演练

（内容略，待补充实际应用场景示例）

高级配置技巧

（内容略，待补充自定义规则、模板扩展等内容）

团队协作指南

（内容略，待补充多人协作流程、权限管理建议）

故障排除与FAQ

（内容略，待补充常见问题解决方案）

最佳实践总结

（内容略，待补充高效使用经验汇总）

AI工具斜杠命令详解

使用 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”文生图能力，利用AI驱动流程实现高效迭代。

第一步：需求收集

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

第二步：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中描述的参数一致性

第三步：执行变更任务

/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 ... (进行中)

第四步：人工验证与测试

启动本地服务进行功能校验：

# 构建并运行项目
npm run build
npm run dev

# 使用API调试工具（如Apifox）发起请求
curl -X POST http://localhost:3000/api/generate-image \
-d '{"model": "high_aes_general_v40", "prompt": "测试图片"}'

第五步：项目归档处理

/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

代码审查流程整合

设置标准化的 Pull Request 模板：

.github/pull_request_template.md

## OpenSpec 变更检查清单

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

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

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

常见问题排查与FAQ

典型故障解决方案

Q1: 初始化失败

现象描述：

openspec init

执行命令时报错，无法正常初始化环境。

解决方法：

node --version  # 确保Node.js版本 >= 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模型

| 原则 | 含义       | 实践要点                             |
|------|------------|--------------------------------------|
| C   | Concise    | 内容简洁清晰，避免重复和冗长表达     |
| L   | Logical    | 结构逻辑严密，前后一致、条理分明     |
| E   | Executable | 方案具备可实施性，支持自动化测试     |
| A   | Auditable  | 变更记录完整，便于追溯与审计         |
| R   | Reviewable | 易于人工阅读和评审，降低理解成本     |

???? 质量保障检查清单

【规范撰写阶段】
- 明确目标，界定变更范围
- 验收标准具体且可验证
- [ ] 任务拆分粒度适中合理
- [ ] 技术选型已完成初步评估
- 测试策略覆盖主要场景

【开发实施阶段】
- AI依据任务列表逐步执行
- [ ] 每个步骤均有验证机制
- [ ] 异常处理方案已定义
- [ ] 代码符合质量规范要求
- [ ] 相关文档实时同步更新

【归档完成阶段】
- 所有子任务均已验证通过
- 规范差异已正确合并
- 完整保留变更历史记录
- 影响分析报告已生成
- 团队知识库同步刷新

???? 团队协作文化建设建议

???? 小步快跑
- 优先选择小型功能模块进行试点应用

???? 数据支撑决策
- 主动收集流程使用数据与成效指标

???? 持续迭代优化
- 根据实际反馈持续改进工作流

???? 推动知识流通
- 构建内部最佳实践共享资料库

???? 建立正向激励
- 设立质量提升专项奖励机制

???? 成功衡量指标体系

| 指标类型 | 衡量维度           | 目标值     |
|----------|--------------------|------------|
| 效率     | 需求明确耗时       | 缩短50%    |
| 质量     | 返工发生频率       | 下降60%    |
| 协作     | 团队共识达成程度   | 提升80%    |
| 维护     | 文档更新及时率     | 达到95%    |

???? 推荐学习与参考资源

官方网站与社区平台：
- OpenSpec官方网站
- OpenSpec GitHub仓库
- Fission AI官网
- OpenSpec Discord社区

支持的AI开发工具列表：
- Claude Code
- Cursor编辑器
- GitHub Copilot
- Amazon Q Developer

权威技术文档与指南：
- IEEE标准830-1998 - 软件需求规范
- 敏捷开发宣言
- DevOps实践指南

???? 总结与价值提炼

OpenSpec通过引入规范化驱动的开发模式，显著提升了AI编程的可控性和协作效率。该框架不仅解决了AI输出不稳定的问题，还构建了人机协同的标准作业路径。

核心优势回顾：

?
统一认知基础
- 在编码启动前实现团队对齐

?
结构化流程管理
- 所有变更均可追踪、可回溯

?
广泛工具兼容
- 无缝集成主流AI辅助开发环境

?
输出质量可控
- 以规范为基准保障成果一致性

?
标准化协作机制
- 提供清晰的人机交互流程

快速入门操作命令汇总：

# 第一步：全局安装
npm install -g @fission-ai/openspec@latest

# 第二步：进入项目目录并初始化
cd your-project
openspec init

# 第三步：创建首个变更提案
/openspec:proposal Add user authentication

# 第四步：执行开发任务
/openspec:apply add-user-authentication

# 第五步：完成归档
/openspec:archive add-user-authentication

关键成功要素总结：
- 高层支持与团队认同
- 初期试点聚焦简单场景
- 持续收集反馈并优化流程
- 强化培训与知识传递
- 结合绩效机制推动落地

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

在AI辅助开发日益普及的今天，建立科学、可延续的工作范式成为提升效率的关键。通过系统化的规范管理与工具链协同，团队能够实现更高效、一致且可持续的开发流程。

???? 规范优先
在任何项目启动初期，首要任务是制定明确、可执行的技术规范。统一的编码标准、接口定义和文档结构有助于减少歧义，确保AI生成内容的准确性与一致性。

????? 工具熟练
熟悉并掌握各类支持AI编程的集成工具，是发挥其最大效能的前提。合理配置IDE插件、自动化脚本及API连接方式，能够让AI能力无缝融入现有开发环境。

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[跨规范更新优秀]

???? 团队协作
构建团队级别的规范管理体系，确保所有成员遵循同一套准则。通过共享模板、评审机制和知识沉淀，提升整体协作效率与代码质量。

???? 迭代完善
建立基于实际反馈的持续优化机制。通过收集使用中的问题与建议，不断调整和细化规范内容，形成动态演进的良性循环。

???? 持续改进
结合项目实践中的经验教训，定期复盘工作流程，识别瓶颈环节，并进行针对性优化，推动开发模式的逐步升级。

本文档结合OpenSpec官方资料与真实项目实践整理而成，适合在实际工作中反复查阅与参考。