OpenSpec新手入门教程
什么是OpenSpec？
OpenSpec 是一个为AI编码助手设计的**规范驱动开发(Specification-driven Development)**工具，它通过轻量级的工作流程，确保人类开发者和AI助手在编写任何代码之前就能对需求达成明确共识。
核心特点
- 🚀 轻量级：无需API密钥，最小化设置
- 🔄 现有项目优先：特别适合修改现有功能 (1→n)
- 📋 变更跟踪：提案、任务和规范差异的完整生命周期管理
- 🤖 AI工具集成：支持多种主流AI编码助手
为什么需要OpenSpec？
传统AI编码助手的问题
当您使用AI编码助手时，是否遇到过以下情况：
- ❌ AI根据模糊提示生成不符合需求的代码
- ❌ 遗漏重要功能要求
- ❌ 添加了不必要的功能
- ❌ 代码行为不可预测
OpenSpec的解决方案
OpenSpec通过规范驱动开发解决这些问题：
- ✅ 明确共识：在编码前确定所有要求
- ✅ 结构化变更：所有相关文档集中管理
- ✅ 可审查输出：AI根据明确规范生成代码
- ✅ 版本控制：完整追踪所有变更历史
准备工作
系统要求
- Node.js >= 20.19.0 ，建议24版本
检查Node.js版本
text
node --version如果版本不符合要求，请访问 Node.js官网 更新。
快速开始
第一步：安装OpenSpec CLI
text
npm install -g @fission-ai/openspec@latest验证安装
text
openspec --version第二步：在项目中初始化OpenSpec
text
cd your-project-directory
openspec init初始化过程会：
- 询问您使用的AI工具（Claude Code、Cursor等）
- 自动配置相应的斜杠命令
- 创建
openspec/目录结构 - 生成
AGENTS.md文件
第三步：验证设置
text
openspec list如果您的AI助手没有立即显示新的斜杠命令，请重启它。
核心概念
1. 双文件夹模型
OpenSpec使用两个主要目录：
text
openspec/
├── project.md # 项目规范
├── specs/ # 当前状态 - 已构建内容
│ └── [capability]/ # 单一功能模块
│ ├── spec.md # 需求和场景
│ └── design.md # 技术模式
├── changes/ # 变更提案 - 应该修改的内容
│ ├── [change-name]/
│ │ ├── proposal.md # 原因、内容、影响
│ │ ├── tasks.md # 实施清单
│ │ ├── design.md # 技术决策（可选；见标准）
│ │ └── specs/ # 差异变更，场景描述，伪代码，可用于生成测试用例
│ │ └── [capability]/
│ │ └── spec.md # 新增/修改/移除
│ └── archive/ # 完成的变更
└── project.md # 项目级别约定2. 规范格式
规范使用Markdown格式，包含：
text
# Auth Specification
## Purpose
Authentication and session management.
## Requirements
### Requirement: User Authentication
The system SHALL issue a JWT on successful login.
#### Scenario: Valid credentials
- WHEN a user submits valid credentials
- THEN a JWT is returned3. 变更差异
变更通过"差异"格式显示：
text
# Delta for Auth
## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.
#### Scenario: OTP required
- WHEN a user submits valid credentials
- THEN an OTP challenge is required完整工作流程
OpenSpec遵循四步工作流程：
1️⃣ 起草变更提案
text
# 使用AI助手或直接创建
/openspec:proposal Add profile search filtersAI会自动创建：
openspec/changes/feature-name/proposal.md- 变更说明openspec/changes/feature-name/tasks.md- 实施任务openspec/changes/feature-name/specs/- 规范差异
2️⃣ 审查与对齐
text
# 查看变更详情
openspec show feature-name
# 验证规范格式
openspec validate feature-name与AI助手讨论，直到所有人同意：
您：能否为角色和团队过滤器添加验收标准？ AI：我来更新规范差异，添加角色和团队过滤器的场景。 [编辑相应文件]
3️⃣ 实施任务
text
# 开始实施
/openspec:apply feature-nameAI会按照 tasks.md 中的清单逐步实施，每完成一个任务会标记为 ✓。
4️⃣ 归档与更新规范
text
# 归档完成的变更
openspec archive feature-name --yes归档会将批准的变更合并回 openspec/specs/ 中，并移动到 archive/ 目录。
常用命令
查看和管理变更
text
openspec list # 查看所有活动变更
openspec view # 交互式规范仪表板
openspec show <change-name> # 显示变更详情
openspec validate <change-name> # 验证规范格式归档变更
text
openspec archive <change-name> # 交互式归档
openspec archive <change-name> --yes # 非交互式归档工具管理
text
openspec update # 刷新AI指导，重新生成斜杠命令团队采用指南
1. 初始化团队项目
text
# 在团队仓库中运行
openspec init2. 从新功能开始
要求团队成员将即将到来的工作作为变更提案与AI助手讨论。
3. 增量式发展
每个完成的变更都会归档到记录您系统的实时规范中。
4. 保持工具灵活性
不同团队成员可以使用Claude Code、Cursor或任何AGENTS.md兼容工具，同时共享相同的规范。
5. 工具切换
当有人切换到不同AI工具时，运行：
text
openspec update项目上下文设置（可选但推荐）
初始化后，建议完善项目上下文：
使用示例提示
text
请阅读 openspec/project.md，并帮助我填写关于我的项目、技术栈和约定的详细信息。project.md 内容示例
text
# Project Context
## Tech Stack
- Frontend: React + TypeScript
- Backend: Node.js + Express
- Database: PostgreSQL
- Styling: Tailwind CSS
## Code Conventions
- 使用 TypeScript 严格模式
- 组件名使用 PascalCase
- 函数名使用 camelCase
- 常量使用 UPPER_SNAKE_CASE
## Architecture Patterns
- 采用组件化设计
- 前后端分离
- RESTful API 设计
- 响应式设计原则规范文件理解
Delta格式
差异文件显示规范如何变化：
text
## ADDED Requirements # 新功能
## MODIFIED Requirements # 行为变更（包含完整更新文本）
## REMOVED Requirements # 已废弃功能格式要求
- 使用
### Requirement:作为标题 - 每个要求至少需要一个
#### Scenario:块 - 在要求文本中使用 SHALL/MUST
升级和维护
升级OpenSpec
text
npm install -g @fission-ai/openspec@latest刷新AI指导
text
# 在每个项目中运行
openspec update常见问题
Q1: AI助手没有显示新的斜杠命令怎么办？
A: 重启您的AI编码助手，然后运行 openspec update 刷新指导。
Q2: 可以同时处理多个变更吗？
A: 是的，OpenSpec支持同时存在多个变更提案，但一次只能应用一个。
Q3: 如何修改已归档的规范？
A: 创建一个新的变更提案，通过相同的流程来更新现有规范。
Q4: 团队成员使用不同AI工具可以吗？
A: 可以！OpenSpec的AGENTS.md兼容性确保所有AI工具都能理解相同的规范。
Q5: 怎么关闭向openspce推送数据？
A: 设置环境变量export OPENSPEC_TELEMETRY=0