项目概述
OpenSpec是一个AI驱动的规范开发系统，旨在让人工智能和人类开发者在编写代码之前就需求达成一致。它通过轻量级的规范工作流锁定意图，提供可审查、确定性的输出结果。
核心执行流程
工作流概览
┌────────────────────┐
│ 1. 创建提议 │ ← 需求提出和初步规划
│ (Proposal) │
└────────┬───────────┘
│ 与AI共享意图
▼
┌────────────────────┐
│ 2. 审核规范 │ ← 规范细化和审查确认
│ (Review) │◀──── 反馈循环 ──────┐
└────────┬───────────┘ │
│ 批准计划 │
▼ │
┌────────────────────┐ │
│ 3. AI实施 │───────────────────────┘
│ (Implement) │ 代码实现和任务执行
└────────┬───────────┘
│ 部署变更
▼
┌────────────────────┐
│ 4. 测试验证 │ ← 质量保证和测试
│ (Testing) │
└────────┬───────────┘
│ 验证通过
▼
┌────────────────────┐
│ 5. 归档文档 │ ← 文档更新和知识沉淀
│ (Archive) │
└────────────────────┘
详细工作流进度
第一阶段：创建提议 (Create Proposal)
目标
- 捕获功能需求和变更意图
- 创建结构化的变更提议
- 为后续工作奠定基础
关键文件结构
openspec/
├── changes/
│ └── [change-name]/
│ ├── proposal.md # 变更提议：为什么、什么内容、影响范围
│ ├── tasks.md # 实施检查清单
│ ├── design.md # 技术决策（可选）
│ └── specs/ # 规范变更内容
│ └── [capability]/
│ └── spec.md # 规范增量
操作步骤
-
发起变更请求
# 向AI助手提出需求 "我想添加用户个人资料搜索功能，按角色和团队筛选" -
AI生成变更结构
- 自动创建变更目录
- 生成proposal.md、tasks.md等核心文件
- 建立规范的增量格式
-
验证创建结果
openspec list # 确认变更文件夹存在 openspec validate change-name # 验证规范格式
提议文件模板 (proposal.md)
## Why
[说明为什么需要这个变更]
## What Changes
- [具体变更内容1]
- [具体变更内容2]
## Impact
- [影响的规范和代码]
- [影响范围：破坏性/非破坏性]
第二阶段：审核规范 (Review & Refine)
目标
- 确保规范准确性和完整性
- 通过审查迭代完善需求
- 获得 stakeholder 认可
审核流程
-
查看变更详情
openspec show change-name # 审查提议、任务和规范增量 -
规范细化
- 添加验收标准
- 完善场景描述
- 明确技术要求
-
迭代优化
# 与AI助手交互完善规范 "可以为角色和团队筛选器添加验收标准吗？"
规范格式要求
需求结构：
### Requirement: [需求名称]
系统应该 [核心行为描述]
#### Scenario: [场景描述]
- **WHEN** [条件或触发器]
- **THEN** [期望结果]
- **AND** [附加结果或条件]
增量格式：
## ADDED Requirements- 新增功能## MODIFIED Requirements- 修改现有功能## REMOVED Requirements- 移除功能## RENAMED Requirements- 重命名需求
第三阶段：AI实施 (AI Implementation)
目标
- 基于确认的规范实施代码
- 系统性完成tasks.md中的任务
- 确保实现符合规范要求
实施流程
-
启动实施
# 使用斜杠命令（支持的AI工具） /openspec:apply change-name # 或自然语言请求 "请实施这个变更" -
任务执行
- AI逐项完成tasks.md中的任务
- 按照规范要求编写代码
- 标记完成的任务（✓）
-
任务跟踪格式
## 1. 数据库设置 - [ ] 1.1 添加筛选器列到用户表 - [ ] 1.2 创建搜索索引 ## 2. 后端实现 - [✓] 2.1 添加搜索端点 - [ ] 2.2 实现筛选逻辑
实施最佳实践
- 参考规范：严格遵循specs/中的规范要求
- 增量开发：按照任务清单逐步实施
- 质量检查：每个任务完成后进行自检
- 文档更新：同步更新相关技术文档
第四阶段：测试验证 (Testing & Validation)
目标
- 确保实现符合功能要求
- 验证代码质量和技术标准
- 为部署做好准备
验证流程
-
规范一致性验证
openspec validate change-name # 验证规范格式和一致性 -
功能测试
- 手动功能测试
- 自动化测试执行
- 边界条件验证
-
代码审查
- 代码质量检查
- 架构一致性验证
- 性能评估
验证标准
功能验证：
- ✓ 所有需求场景都已实现
- ✓ 验收标准全部满足
- ✓ 边界情况处理正确
技术验证：
- ✓ 代码符合项目规范
- ✓ 测试覆盖率达标
- ✓ 性能指标满足要求
第五阶段：归档文档 (Archive & Documentation)
目标
- 将变更合并到主规范中
- 更新系统文档
- 为历史记录提供审计轨迹
归档流程
-
准备归档
# 确认所有任务完成 openspec show change-name # 执行归档操作 openspec archive change-name --yes -
自动化处理
- 解析增量变更
- 更新主规范文件
- 移动变更到archive目录
-
文档更新
- 更新API文档
- 刷新用户指南
- 更新架构文档
归档结果
openspec/
├── specs/ # 更新后的主规范
│ └── [capability]/
│ └── spec.md # 包含新变更的完整规范
└── changes/
└── archive/
└── 2025-10-25-[change-name]/ # 历史记录
├── proposal.md
├── tasks.md
└── specs/
MacOS系统使用技巧
环境准备
1. 系统要求
# 检查Node.js版本（需要 >= 20.19.0）
node --version
# 如果版本过低，使用Homebrew安装
brew install node@20
2. 安装OpenSpec CLI
# 全局安装
npm install -g @fission-ai/openspec@latest
# 验证安装
openspec --version
3. 项目初始化
# 进入项目目录
cd /path/to/your/project
# 初始化OpenSpec
openspec init
# 选择支持的AI工具：
# ☑ Claude Code (原生斜杠命令)
# ☑ CodeBuddy (CLI工具)
# ☑ Cursor (编辑器集成)
# ☑ AGENTS.md (通用支持)
AI工具配置
支持的AI工具及配置方式
| 工具名称 | 配置方式 | 斜杠命令 | MacOS兼容性 |
|---|---|---|---|
| Claude Code | 自动配置 | /openspec:proposal/openspec:apply/openspec:archive | ✅ 原生支持 |
| CodeBuddy | .codebuddy/commands/ | 同上 | ✅ CLI集成 |
| Cursor | 自动配置 | /openspec-proposal/openspec-apply/openspec-archive | ✅ 编辑器集成 |
| Cline | .clinerules/ 目录 | 规则文件 | ✅ 兼容支持 |
| Windsurf | .windsurf/workflows/ | 工作流文件 | ✅ 兼容支持 |
| GitHub Copilot | .github/prompts/ | 提示文件 | ✅ 兼容支持 |
配置验证
# 列出活跃变更
openspec list
# 检查工具配置状态
openspec --help
日常工作流技巧
1. 项目管理
# 查看交互式仪表板
openspec view
# 列出所有规范
openspec list --specs
# 批量验证
openspec validate --all
2. 变更管理
# 快速创建变更（使用斜杠命令）
/openspec:proposal 添加用户认证功能
# 验证特定变更
openspec validate add-user-auth
# 查看变更详情
openspec show add-user-auth
3. 团队协作
# 更新AI指令（团队成员工具切换时）
openspec update
# 导出变更记录
openspec show change-name --json > change-report.json
高级使用技巧
1. 批量操作
# 验证所有变更和规范
openspec validate --all --strict
# 并发验证控制
OPENSPEC_CONCURRENCY=4 openspec validate --all
2. 集成到CI/CD
# 在GitHub Actions中使用
- name: Validate OpenSpec specs
run: |
npm install -g @fission-ai/openspec@latest
openspec validate --all --strict
3. 自定义配置
# 非交互式初始化
openspec init --tools "claude-code,cursor"
# 跳过规范更新的归档（适用于工具性变更）
openspec archive tooling-change --skip-specs
故障排除
常见问题解决
-
斜杠命令不显示
# 重启AI工具 # 检查openspec init是否正确执行 openspec list -
权限错误
# 检查目录权限 ls -la openspec/ # 确保可写权限 chmod -R u+w openspec/ -
版本冲突
# 更新到最新版本 npm install -g @fission-ai/openspec@latest # 更新项目指令 openspec update
调试技巧
# 启用详细输出
openspec validate change-name --json
# 检查文件结构
find openspec/ -name "*.md" | head -10
# 验证格式规范
openspec validate --strict
最佳实践总结
项目管理最佳实践
-
渐进式采用
- 从新功能开始使用OpenSpec
- 逐步扩展到现有功能维护
- 保持规范与代码同步
-
团队协作
- 统一使用相同的AI工具配置
- 定期运行
openspec update - 建立变更审查流程
-
质量保证
- 每个变更都进行验证
- 保持规范的完整性
- 定期归档完成的变更
开发工作流建议
-
需求阶段
- 明确功能边界和验收标准
- 与AI充分沟通需求细节
- 创建结构化的变更提议
-
开发阶段
- 严格按照tasks.md执行
- 及时更新任务进度
- 遇到问题及时调整规范
-
测试阶段
- 全面验证功能实现
- 检查规范一致性
- 确保代码质量标准
-
部署阶段
- 及时归档完成的变更
- 更新相关文档
- 保留历史变更记录
MacOS特定优化
-
终端集成
- 使用iTerm2或Terminal.app
- 配置适当的字体和主题
- 设置命令别名提高效率
-
编辑器集成
- VS Code + OpenSpec扩展
- Cursor原生集成
- 配置markdown预览
-
自动化脚本
# 创建alias简化常用命令 echo 'alias osl="openspec list"' >> ~/.zshrc echo 'alias osv="openspec view"' >> ~/.zshrc echo 'alias osa="openspec archive"' >> ~/.zshrc source ~/.zshrc
总结
OpenSpec提供了一个完整的规范驱动开发工作流，特别适合在MacOS环境下与各种AI工具配合使用。通过五个核心阶段（创建提议、审核规范、AI实施、测试验证、归档文档），团队可以：
- 提高开发效率：明确的规范减少返工
- 增强代码质量：系统性的验证和审查
- 改善团队协作：统一的规范和流程
- 保持文档同步：自动化归档和更新
成功采用OpenSpec的关键在于渐进式实施、团队培训和持续改进。随着规范的积累，项目的可维护性和可扩展性将显著提升。
