OpenSpec 使用指南

OpenSpec 核心概念

OpenSpec 是规范驱动开发（Spec-Driven Development）工具，核心思想：

  • Specs（规范） = 已实现的功能（openspec/specs/）
  • Changes（变更） = 待实现的提案（openspec/changes/）
  • Archive（归档） = 已完成并部署的变更

三阶段工作流

阶段 1：创建变更提案（Planning）

何时创建提案：

  • 添加新功能
  • 破坏性变更（API、数据库 schema）
  • 架构或模式变更
  • 性能优化（改变行为）
  • 安全模式更新

何时跳过提案：

  • Bug 修复（恢复预期行为）
  • 拼写、格式、注释
  • 非破坏性依赖更新
  • 配置变更
  • 现有行为的测试

创建提案步骤：

# 1. 探索当前状态
openspec spec list --long    # 查看现有规范
openspec list                 # 查看进行中的变更

# 2. 选择唯一的 change-id（kebab-case，动词开头）
# 例如：add-user-profile, update-auth-flow, remove-old-api

# 3. 创建目录结构
mkdir -p openspec/changes/add-user-profile/specs/user-profile

# 4. 创建文件
# - proposal.md（为什么、改什么、影响）
# - tasks.md（实施清单）
# - design.md（可选，仅在需要技术决策时）
# - specs/[capability]/spec.md（规范增量）

阶段 2：实施变更（Implementation）

实施前检查清单：

实施步骤：

  1. 按顺序完成 tasks.md 中的任务
  2. 确认所有任务完成后，将 tasks.md 中的 - [ ] 改为 - [x]
  3. 重要：在提案被审核批准前不要开始实施

阶段 3：归档变更（Archiving）

部署后归档：

# 归档变更（会更新 specs/）
openspec archive <change-id> --yes

# 仅归档，不更新 specs（工具类变更）
openspec archive <change-id> --skip-specs --yes

# 验证归档后的状态
openspec validate --strict

常用命令速查

# 查看状态
openspec list                  # 列出进行中的变更
openspec list --specs          # 列出所有规范
openspec show [item]          # 查看变更或规范的详细信息

# 验证
openspec validate [item]      # 验证变更或规范
openspec validate --strict    # 严格模式验证

# 归档
openspec archive <change-id> --yes  # 归档变更（非交互式）

# 调试
openspec show [change] --json --deltas-only  # 查看增量详情

规范文件格式

关键格式要求：

## ADDED Requirements
### Requirement: 新功能名称
系统必须提供...

#### Scenario: 成功场景
- **WHEN** 用户执行操作
- **THEN** 预期结果

## MODIFIED Requirements
### Requirement: 现有功能名称
[完整的修改后的需求，包含所有场景]

## REMOVED Requirements
### Requirement: 旧功能名称
**Reason**: 为什么移除
**Migration**: 如何处理迁移

重要提示：

  • 每个需求必须至少有一个 #### Scenario:（4 个 #）
  • 使用 SHALL/MUST 表示规范性需求
  • MODIFIED 时，必须包含完整的需求内容（不是部分增量）

最佳实践

1. 变更 ID 命名

  • 使用 kebab-case：add-user-profile
  • 动词开头：add-, update-, remove-, refactor-
  • 保持唯一性

2. 能力（Capability）命名

  • 使用动词-名词：user-auth, payment-capture
  • 单一职责
  • 10 分钟可理解原则
  • 如果描述需要 "AND"，考虑拆分

3. 何时创建 design.md

仅在以下情况创建：

  • 跨多个服务/模块的变更
  • 新的架构模式
  • 新的外部依赖或重大数据模型变更
  • 安全、性能或迁移复杂性
  • 需要在编码前做技术决策的模糊点

4. 简单优先

  • 默认 < 100 行新代码
  • 单文件实现直到证明不够用
  • 避免不必要的框架
  • 选择成熟、已验证的模式

实际使用示例

假设要添加"用户个人资料"功能：

# 1. 检查现有状态
openspec spec list --long
openspec list

# 2. 创建变更目录
CHANGE=add-user-profile
mkdir -p openspec/changes/$CHANGE/specs/user-profile

# 3. 创建 proposal.md
cat > openspec/changes/$CHANGE/proposal.md << 'EOF'
# Change: Add User Profile

## Why
用户需要管理个人资料信息，包括头像、昵称、简介等。

## What Changes
- 添加用户个人资料 API 端点
- 添加个人资料数据库表
- 添加前端个人资料页面

## Impact
- Affected specs: user-profile
- Affected code: backend/internal/api/user.go, backend/internal/repository/user.go
EOF

# 4. 创建 tasks.md
cat > openspec/changes/$CHANGE/tasks.md << 'EOF'
## 1. Implementation
- [ ] 1.1 创建数据库表结构
- [ ] 1.2 实现 Repository 层
- [ ] 1.3 实现 Service 层
- [ ] 1.4 实现 API 端点
- [ ] 1.5 添加前端页面
- [ ] 1.6 编写测试
EOF

# 5. 创建规范增量
cat > openspec/changes/$CHANGE/specs/user-profile/spec.md << 'EOF'
## ADDED Requirements
### Requirement: User Profile Management
The system SHALL allow users to view and edit their profile information.

#### Scenario: View profile
- **WHEN** user requests their profile
- **THEN** return profile information including avatar, nickname, and bio

#### Scenario: Update profile
- **WHEN** user updates profile information
- **THEN** save changes and return updated profile
EOF

# 6. 验证
openspec validate $CHANGE --strict

常见问题排查

  1. "Change must have at least one delta"

    • 检查 changes/[name]/specs/ 是否存在 .md 文件
    • 确认文件有操作前缀（## ADDED Requirements）

  2. "Requirement must have at least one scenario"

    • 确认场景使用 #### Scenario: 格式（4 个 #）
    • 不要用项目符号或粗体作为场景标题

  3. 验证失败

    • 使用 --strict 模式
    • 查看 JSON 输出：openspec show [change] --json

下一步建议

  1. 熟悉命令：先运行 openspec list 和 openspec spec list --long 了解当前状态
  2. 创建第一个变更：从一个小功能开始，熟悉流程
  3. 阅读现有文档：查看 openspec/project.md 了解项目约定
  4. 使用验证：每次创建变更后运行 openspec validate --strict
posted @ 2025-12-31 11:25  GreeneGe  阅读(660)  评论(0)    收藏  举报

https://github.com/Glf9832