OpenSpec 入门指北
- 免费干货
- 2小时前
- 6热度
- 0评论
什么是 OpenSpec
- 核心概念
- 工作流详解
- 工件（Artifacts）系统
- Schema 模式
- 命令接口
- Delta Spec 增量规格
- 归档机制
- 与 Claude Code 的集成
- 完整生命周期示例
- 最佳实践
- 常见问题
什么是 OpenSpec
OpenSpec 是一个文档驱动的工作流系统，它将复杂项目分解为结构化的阶段，通过工件（artifact）之间的依赖关系来管理项目进度。
核心理念
传统方式: 想法 → 直接写代码 → 补文档（经常跳过）
OpenSpec: 想法 → 为什么做 → 怎么做 → 做什么 → 实施步骤 → 写代码
OpenSpec 的核心哲学是：文档不是代码的副产品，而是开发的起点。
解决的问题
| 问题 | OpenSpec 的解决方案 |
|---|---|
| 需求不清晰就开始编码 | 强制先写 proposal 和 specs |
| 设计决策没有记录 | design.md 记录所有技术决策 |
| 任务进度无法追踪 | tasks.md 的复选框系统 |
| 变更历史无法追溯 | 归档机制保留完整上下文 |
| 团队协作缺乏共识 | 结构化文档作为沟通基础 |
核心概念
1. 变更（Change）
OpenSpec 将所有工作组织为"变更"。每个变更是一个独立的目录，包含完成该工作所需的所有文档：
openspec/changes/<change-name>/
├── .openspec.yaml # 变更配置（schema、状态）
├── proposal.md # 为什么做（Why）
├── design.md # 怎么做（How）
├── specs/ # 做什么（What）
│ ├── capability-1/
│ │ └── spec.md
│ └── capability-2/
│ └── spec.md
└── tasks.md # 实施清单2. 工件（Artifact）
工件是工作流中的基本单元，每个工件有：
- 唯一 ID：如
proposal、design、specs、tasks - 输出路径：文件在变更目录中的位置
- 状态：
ready（可创建）、blocked（等待依赖）、done（已完成） - 依赖关系：哪些工件必须先完成
3. Schema（模式）
Schema 定义了工作流的结构——哪些工件存在、它们之间的依赖关系、实施前需要完成哪些工件。
OpenSpec 内置的 spec-driven schema 定义如下：
┌─────────────────────────────────────────────────────┐
│ spec-driven Schema │
├─────────────────────────────────────────────────────┤
│ │
│ proposal (无依赖) │
│ │ │
│ ├──────────────────┐ │
│ ▼ ▼ │
│ design specs │
│ (依赖 proposal) (依赖 proposal) │
│ │ │ │
│ └────────┬─────────┘ │
│ ▼ │
│ tasks │
│ (依赖 design + specs) │
│ │ │
│ ▼ │
│ apply │
│ (需要 tasks 完成) │
│ │
└─────────────────────────────────────────────────────┘
4. 状态机
每个工件在生命周期中经历以下状态转换：
┌─────────┐
│ ready │ ← 依赖已满足，可以创建
└────┬────┘
│ 开始创建
▼
┌─────────┐
│ creating│ ← 正在创建中
└────┬────┘
│ 创建完成
▼
┌─────────┐
│ done │ ← 已完成
└─────────┘
┌──────────┐
│ blocked │ ← 依赖未满足，等待中
└────┬─────┘
│ 依赖完成
▼
┌──────────┐
│ ready │
└──────────┘
工作流详解
OpenSpec 工作流由五个核心命令组成，每个命令对应一个阶段：
阶段总览
┌────────────────────────────────────────────────────────────────┐
│ OpenSpec 工作流 │
├────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ EXPLORE │───▶│ PROPOSE │───▶│ APPLY │───▶│ ARCHIVE │ │
│ │ 探索 │ │ 提案 │ │ 实施 │ │ 归档 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ 思考讨论 创建工件 执行任务 保存记录 │
│ 澄清需求 定义范围 编写代码 同步规格 │
│ 比较方案 设计架构 更新进度 归档历史 │
│ │
└────────────────────────────────────────────────────────────────┘阶段 1: Explore（探索）
命令: /opsx:explore [change-name]
目的: 在正式创建变更之前，深入思考问题空间。
探索模式的行为准则：
| 准则 | 说明 |
|---|---|
| 好奇，不预设 | 自然提问，不遵循脚本 |
| 开放话题 | 同时探索多个方向，让用户选择感兴趣的 |
| 可视化 | 大量使用 ASCII 图表帮助理解 |
| 适应性 | 跟随有趣的话题，新信息出现时转向 |
| 耐心 | 不急于下结论，让问题自然浮现 |
| 基于实际 | 探索真实代码库，不只空谈理论 |
探索模式可以做什么：
- ✅ 阅读文件、搜索代码、调查代码库
- ✅ 创建 OpenSpec 工件（记录思考成果）
- ❌ 编写应用代码或实现功能
探索模式何时结束：
- 想法足够清晰，可以创建提案
- 用户获得了需要的信息，自行离开
- 决定继续深入探索
阶段 2: Propose（提案）
命令: /opsx:propose <description>
目的: 创建变更并生成所有必需的工件。
执行步骤：
步骤 1: 创建变更目录
openspec new change "<name>"
→ 创建 openspec/changes/<name>/.openspec.yaml
步骤 2: 获取工件构建顺序
openspec status --change "<name>" --json
→ 解析依赖图，确定创建顺序
步骤 3: 按依赖顺序创建工件
┌─────────────────────────────────────────┐
│ 3a. 获取工件指令 │
│ openspec instructions <id> --json │
│ → 获取 template, instruction, rules │
│ │
│ 3b. 读取依赖工件（如果存在） │
│ → 获取上下文信息 │
│ │
│ 3c. 创建工件文件 │
│ → 使用 template 作为结构 │
│ → 遵循 instruction 的指导 │
│ → 应用 rules 作为约束 │
│ → context/rules 不写入输出文件 │
│ │
│ 3d. 验证工件创建成功 │
│ → 检查文件是否存在 │
└─────────────────────────────────────────┘
步骤 4: 检查是否满足 apply 条件
→ 所有 applyRequires 中的工件状态为 done
步骤 5: 显示最终状态
→ 报告变更名称、位置、已创建的工件工件创建的关键规则：
┌─────────────────────────────────────────────────────────────┐
│ 工件创建黄金法则 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ✅ template → 用作文件结构骨架 │
│ ✅ instruction → 遵循其指导填充内容 │
│ ✅ context/rules → 作为写作约束（不写入文件） │
│ ✅ dependencies → 先读取，获取上下文后再创建 │
│ │
│ ❌ 不要复制 context 块到输出文件 │
│ ❌ 不要复制 rules 块到输出文件 │
│ ❌ 不要在依赖完成前创建工件 │
│ │
└─────────────────────────────────────────────────────────────┘阶段 3: Apply（实施）
命令: /opsx:apply [change-name]
目的: 执行 tasks.md 中的任务清单，逐步实现变更。
执行流程：
步骤 1: 选择变更
→ 从参数推断 / 从上下文推断 / 列出可选项让用户选择
步骤 2: 检查状态
openspec status --change "<name>" --json
→ 确认 schemaName 和工件状态
步骤 3: 获取实施指令
openspec instructions apply --change "<name>" --json
→ 获取 contextFiles、进度、任务列表
步骤 4: 读取上下文文件
→ 读取 proposal、specs、design、tasks
步骤 5: 循环执行任务
┌─────────────────────────────────────────┐
│ FOR EACH pending task: │
│ │
│ 5a. 显示当前任务 │
│ "Working on task 3/7: ..." │
│ │
│ 5b. 执行代码变更 │
│ → 保持变更最小化、聚焦 │
│ → 一次只做一个任务 │
│ │
│ 5c. 标记任务完成 │
│ - [ ] → - [x] │
│ │
│ 5d. 继续下一个任务 │
│ │
│ PAUSE IF: │
│ → 任务不清晰：请求澄清 │
│ → 发现设计问题：建议更新工件 │
│ → 遇到错误：报告并等待指导 │
│ → 用户中断：暂停 │
└─────────────────────────────────────────┘
步骤 6: 显示完成状态
→ 报告本次完成的任务数
→ 如果全部完成：建议归档实施模式的关键原则：
| 原则 | 说明 |
|---|---|
| 持续推进 | 一直执行任务直到完成或阻塞 |
| 先读后做 | 始终先读取上下文文件再开始 |
| 最小变更 | 每次只做一个任务，保持变更聚焦 |
| 即时标记 | 完成任务后立即更新复选框 |
| 遇阻即停 | 不猜测，遇到不清晰的要求就暂停 |
阶段 4: Archive（归档）
命令: /opsx:archive [change-name]
目的: 将完成的变更移入归档目录，保留完整历史记录。
归档流程：
步骤 1: 选择变更（如果未指定）
→ 列出活跃变更供用户选择
步骤 2: 检查工件完成状态
→ 如果有未完成的工件，显示警告
→ 用户确认后继续
步骤 3: 检查任务完成状态
→ 统计 [ ] 和 [x] 的数量
→ 如果有未完成任务，显示警告
→ 用户确认后继续
步骤 4: 评估 Delta Spec 同步状态
→ 检查是否存在 delta specs
→ 如果存在，比较与主规格的差异
→ 提示用户是否同步
步骤 5: 执行归档
mkdir -p openspec/changes/archive
mv openspec/changes/<name>
→ openspec/changes/archive/YYYY-MM-DD-<name>/
步骤 6: 显示归档摘要
归档目录结构：
openspec/changes/archive/
├── 2024-12-01-generate-project-documentation/
│ ├── .openspec.yaml
│ ├── proposal.md
│ ├── design.md
│ ├── specs/
│ │ ├── installation-guide/spec.md
│ │ ├── project-structure/spec.md
│ │ └── ...
│ └── tasks.md
├── 2024-12-15-add-user-auth/
│ └── ...
└── ...工件（Artifacts）系统
Proposal（提案）
文件: proposal.md
目的: 回答"为什么做这个变更？"
## Why
<!-- 1-2 句话说明问题或机会 -->
## What Changes
<!-- 变更列表，具体说明新增、修改、删除的内容 -->
<!-- 破坏性变更标记为 **BREAKING** -->
## Capabilities
### New Capabilities
<!-- 新增能力，每个对应 specs/<name>/spec.md -->
-`<kebab-case-name>`: <简要描述>
### Modified Capabilities
<!-- 需求发生变更的现有能力 -->
## Impact
<!-- 影响的代码、API、依赖、系统 -->
关键要素：
- Why: 变更的动机和价值
- What Changes: 具体的变更范围
- Capabilities: 新增/修改的能力列表（驱动 specs 创建）
- Impact: 影响范围分析
Design（设计）
文件: design.md
目的: 回答"如何实现这个变更？"
## Context
<!-- 背景、当前状态、约束、利益相关者 -->
## Goals / Non-Goals
**Goals:**
<!-- 本设计要实现的目标 -->
**Non-Goals:**
<!-- 明确排除的范围 -->
## Decisions
<!-- 关键技术选择及理由，包含被否决的替代方案 -->
## Risks / Trade-offs
<!-- 已知限制和风险 -->
<!-- 格式: [Risk] → Mitigation -->
## Migration Plan
<!-- 部署步骤、回滚策略 -->
## Open Questions
<!-- 待解决的决策或未知项 -->关键要素：
- Context: 当前状态和约束条件
- Goals / Non-Goals: 明确包含和排除的范围
- Decisions: 技术决策及理由（为什么选 A 不选 B）
- Risks: 已知风险和缓解措施
Specs（规格）
文件: specs/<capability>/spec.md
目的: 回答"系统应该做什么？"
## ADDED Requirements
### Requirement: <需求名称>
<!-- 需求描述：系统 SHALL/MUST ... -->
#### Scenario: <场景名称>
-**WHEN** <!-- 条件 -->
-**THEN** <!-- 预期结果 -->
## MODIFIED Requirements
### Requirement: <需求名称>
<!-- 完整更新后的内容 -->
## REMOVED Requirements
### Requirement: <需求名称>
**Reason**: <!-- 移除原因 -->
**Migration**: <!-- 迁移方案 -->规格编写规则：
| 规则 | 说明 |
|---|---|
| SHALL/MUST | 使用规范性语言，避免 should/may |
| 4 个井号 | Scenario 必须用 ####，不能用 3 个或列表 |
| 可测试性 | 每个场景都是潜在的测试用例 |
| 完整性 | MODIFIED 必须包含完整更新后的内容 |
Tasks（任务）
文件: tasks.md
目的: 将实施工作分解为可追踪的小任务
## 1. 任务组名称
- [ ] 1.1 任务描述
- [ ] 1.2 任务描述
## 2. 任务组名称
- [ ] 2.1 任务描述
- [x] 2.2 已完成的任务任务编写规则：
- 使用
- [ ]格式（OpenSpec 解析此格式追踪进度） - 任务粒度要小，一个会话内可完成
- 按依赖关系排序（先做的在前）
- 完成后立即标记
- [x]
Schema 模式
spec-driven Schema
这是 OpenSpec 最常用的模式，定义了四个核心工件：
# .openspec.yaml
schema:spec-driven
artifacts:
-id:proposal
output:proposal.md
dependencies: []
-id:design
output:design.md
dependencies: [proposal]
-id:specs
output:specs/**/*.md
dependencies: [proposal]
-id:tasks
output:tasks.md
dependencies: [design, specs]
apply:
requires: [tasks]依赖图解析算法
function resolveBuildOrder(artifacts):
ready = [a for a in artifacts if a.dependencies is empty]
blocked = [a for a in artifacts if a.dependencies not all done]
for artifact in ready:
createArtifact(artifact)
markDone(artifact)
# 重新检查 blocked 列表
updateBlockedStatus()状态检查算法
function getArtifactStatus(artifact):
missingDeps = [d for d in artifact.dependencies if not isDone(d)]
if missingDeps is empty:
return 'ready'
else:
return { status: 'blocked', missingDeps }命令接口
CLI 命令一览
| 命令 | 用途 | 示例 |
|---|---|---|
openspec new change |
创建新变更 | openspec new change "add-auth" |
openspec status |
查看变更状态 | openspec status --change "add-auth" --json |
openspec instructions |
获取工件创建指令 | openspec instructions proposal --change "add-auth" --json |
openspec list |
列出所有变更 | openspec list --json |
指令 JSON 结构
openspec instructions 返回的 JSON 包含：
{
"artifactId":"proposal",
"outputPath":"proposal.md",
"template":"## Why\n\n<!-- ... -->\n## What Changes\n...",
"instruction":"创建提案文档，说明变更原因...",
"context":"项目背景信息（约束条件，不写入文件）",
"rules":"工件特定规则（约束条件，不写入文件）",
"dependencies":[],
"description":"初始提案文档"
}关键字段说明：
| 字段 | 用途 | 是否写入文件 |
|---|---|---|
template |
文件结构骨架 | ✅ 是 |
instruction |
内容编写指导 | ❌ 否（仅指导写作） |
context |
项目背景约束 | ❌ 否（仅约束写作） |
rules |
工件特定规则 | ❌ 否（仅约束写作） |
dependencies |
需先读的工件 | ❌ 否（仅指示顺序） |
Delta Spec 增量规格
Delta Spec 是 OpenSpec 实现增量变更管理的核心机制。
概念
Delta Spec 记录的是变更的增量部分，而非完整规格。它描述了：
- ADDED: 新增的需求
- MODIFIED: 修改的需求（包含完整更新后的内容）
- REMOVED: 移除的需求
- RENAMED: 重命名的需求
结构示例
## ADDED Requirements
### Requirement: 用户可以通过邮箱注册
系统 SHALL 允许用户使用邮箱地址注册新账户。
#### Scenario: 成功注册
-**WHEN** 用户提交有效的邮箱和密码
-**THEN** 系统创建账户并发送验证邮件
#### Scenario: 邮箱已存在
-**WHEN** 用户提交已注册的邮箱
-**THEN** 系统返回错误提示"该邮箱已被注册"
## MODIFIED Requirements
### Requirement: 用户登录
系统 SHALL 支持多种登录方式，包括密码登录和验证码登录。
#### Scenario: 密码登录
-**WHEN** 用户提交正确的邮箱和密码
-**THEN** 系统创建会话并返回访问令牌
#### Scenario: 验证码登录
-**WHEN** 用户提交邮箱和正确的验证码
-**THEN** 系统创建会话并返回访问令牌
## REMOVED Requirements
### Requirement: 用户名登录
**Reason**: 统一使用邮箱作为唯一标识，简化系统
**Migration**: 用户需要使用邮箱重新注册同步机制
Delta Spec 最终会合并到主规格中：
openspec/changes/<name>/specs/capability/spec.md (Delta)
│
│ sync
▼
openspec/specs/capability/spec.md (Main)合并算法：
function mergeDeltaSpecs(mainSpec, deltaSpec):
for each operation in deltaSpec:
if ADDED:
mainSpec.addRequirement(operation.requirement)
if MODIFIED:
mainSpec.replaceRequirement(operation.name, operation.content)
if REMOVED:
mainSpec.removeRequirement(operation.name)
if RENAMED:
mainSpec.renameRequirement(operation.from, operation.to)
return mainSpecMODIFIED 的完整性要求
⚠️ 关键规则: MODIFIED 需求必须包含完整更新后的内容，不是差异片段。
❌ 错误做法（部分内容）:
### Requirement: 用户登录
系统 SHALL 支持验证码登录。
✅ 正确做法（完整内容）:
### Requirement: 用户登录
系统 SHALL 支持多种登录方式，包括密码登录和验证码登录。
#### Scenario: 密码登录
- **WHEN** 用户提交正确的邮箱和密码
- **THEN** 系统创建会话并返回访问令牌
#### Scenario: 验证码登录
- **WHEN** 用户提交邮箱和正确的验证码
- **THEN** 系统创建会话并返回访问令牌归档机制
归档流程
完成的变更
│
▼
检查工件完成状态 ──→ 不完整？──→ 警告用户 ──→ 确认后继续
│
▼
检查任务完成状态 ──→ 有未完成任务？──→ 警告用户 ──→ 确认后继续
│
▼
评估 Delta Spec 同步 ──→ 有 Delta？──→ 提示同步 ──→ 用户选择
│
▼
执行归档
mv openspec/changes/<name>
→ openspec/changes/archive/YYYY-MM-DD-<name>/
│
▼
显示归档摘要归档目录结构
openspec/changes/archive/
├── 2024-12-01-generate-project-documentation/
│ ├── .openspec.yaml
│ ├── proposal.md
│ ├── design.md
│ ├── specs/
│ │ ├── api-documentation/spec.md
│ │ ├── deployment-guide/spec.md
│ │ ├── docker-deployment/spec.md
│ │ ├── installation-guide/spec.md
│ │ ├── project-structure/spec.md
│ │ └── troubleshooting-guide/spec.md
│ └── tasks.md
└── 2024-12-15-add-user-auth/
└── ...归档命名规则
- 格式:
YYYY-MM-DD-<change-name> - 示例:
2024-12-01-generate-project-documentation - 如果目标已存在：报错，建议重命名或使用不同日期
与 Claude Code 的集成
Skill 系统
OpenSpec 通过 Claude Code 的 Skill 系统与 AI 助手深度集成：
.claude/
├── skills/
│ ├── openspec-propose/SKILL.md # 创建提案
│ ├── openspec-apply-change/SKILL.md # 实施任务
│ ├── openspec-archive-change/SKILL.md # 归档变更
│ └── openspec-explore/SKILL.md # 探索模式
└── commands/
└── opsx/
├── propose.md # /opsx:propose
├── apply.md # /opsx:apply
├── archive.md # /opsx:archive
└── explore.md # /opsx:explore命令映射
| 用户命令 | Skill 文件 | 功能 |
|---|---|---|
/opsx:propose <desc> |
openspec-propose | 创建变更 + 生成所有工件 |
/opsx:apply [name] |
openspec-apply-change | 执行任务清单 |
/opsx:archive [name] |
openspec-archive-change | 归档完成的变更 |
/opsx:explore [name] |
openspec-explore | 进入探索模式 |
AI 助手的角色
在 OpenSpec 工作流中，AI 助手扮演以下角色：
┌─────────────────────────────────────────────────────────────┐
│ AI 在 OpenSpec 中的角色 │
├─────────────────────────────────────────────────────────────┤
│ │
│ Explore 阶段 → 思考伙伴：提问、探索、比较、可视化 │
│ Propose 阶段 → 文档工程师：按模板生成结构化文档 │
│ Apply 阶段 → 实施者：执行任务、编写代码、更新进度 │
│ Archive 阶段 → 管理员：验证完成度、同步规格、归档 │
│ │
└─────────────────────────────────────────────────────────────┘
上下文感知
AI 助手在 OpenSpec 工作流中具有上下文感知能力：
┌─────────────────────────────────────────────────────────────┐
│ 上下文感知机制 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 读取现有工件作为上下文 │
│ → proposal.md 了解变更动机 │
│ → design.md 了解技术决策 │
│ → specs/ 了解需求规格 │
│ → tasks.md 了解当前进度 │
│ │
│ 2. 遵循 Schema 定义的约束 │
│ → 按依赖顺序创建工件 │
│ → 使用 template 作为结构 │
│ → 应用 rules 作为写作约束 │
│ │
│ 3. 维护工件一致性 │
│ → proposal 的 Capabilities 驱动 specs 创建 │
│ → design 的 Decisions 指导 tasks 分解 │
│ → specs 的 Requirements 映射到 tasks 的实现 │
│ │
└─────────────────────────────────────────────────────────────┘完整生命周期示例
以 "添加用户认证功能" 为例，展示完整的 OpenSpec 生命周期：
1. 探索阶段
用户: /opsx:explore 我想添加用户认证功能
AI: 用户认证是个大领域，让我帮你理清思路...
┌─────────────────────────────────────────────────┐
│ 认证方式光谱 │
├─────────────────────────────────────────────────┤
│ │
│ 简单 ◀──────────────────────────────▶ 复杂 │
│ │
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌──────┐ │
│ │ Session│ │ JWT │ │ OAuth │ │ SSO │ │
│ └────────┘ └────────┘ └────────┘ └──────┘ │
│ │ │ │ │ │
│ 有状态 无状态 第三方 企业级 │
│ │
└─────────────────────────────────────────────────┘
你们的系统目前是怎么处理用户身份的？
预期用户规模多大？
是否需要支持第三方登录？2. 提案阶段
用户: /opsx:propose 添加基于 JWT 的用户认证系统
AI: 正在创建变更 "add-jwt-auth"...
✅ 创建变更目录: openspec/changes/add-jwt-auth/
✅ 创建 proposal.md
✅ 创建 design.md
✅ 创建 specs/jwt-auth/spec.md
✅ 创建 specs/user-management/spec.md
✅ 创建 tasks.md
所有工件已创建！准备实施。
运行 /opsx:apply add-jwt-auth 开始实施。
3. 实施阶段
用户: /opsx:apply add-jwt-auth
AI: 正在实施: add-jwt-auth (schema: spec-driven)
Progress: 0/12 tasks complete
Working on task 1/12: 添加 JWT 依赖到 pom.xml
✓ Task complete
Working on task 2/12: 创建 JwtTokenProvider 工具类
✓ Task complete
Working on task 3/12: 创建 JwtAuthenticationFilter
✓ Task complete
...
Progress: 12/12 tasks complete ✓
所有任务完成！可以归档此变更。
运行 /opsx:archive add-jwt-auth 归档。4. 归档阶段
用户: /opsx:archive add-jwt-auth
AI: 正在归档: add-jwt-auth
✅ 工件状态: 4/4 完成
✅ 任务状态: 12/12 完成
✅ Delta Spec: 2 个能力需要同步
✅ 同步到主规格完成
─────────────────────────────────────
## Archive Complete
**Change:** add-jwt-auth
**Schema:** spec-driven
**Archived to:** openspec/changes/archive/2024-12-01-add-jwt-auth/
**Specs:** ✓ Synced to main specs
所有工件完成。所有任务完成。
─────────────────────────────────────最佳实践
工件编写
| 实践 | 说明 |
|---|---|
| 保持简洁 | proposal 控制在 1-2 页，聚焦"为什么" |
| 记录决策 | design.md 必须包含被否决的替代方案 |
| 可测试性 | 每个 spec 场景都是潜在测试用例 |
| 小任务 | 每个 task 应该在一个会话内完成 |
| 即时更新 | 完成任务后立即标记 [x] |
变更管理
| 实践 | 说明 |
|---|---|
| 一次一个变更 | 避免同时推进多个不相关的变更 |
| 小步快跑 | 大变更拆分为多个小变更 |
| 及时归档 | 完成后立即归档，保持工作区整洁 |
| 命名规范 | 使用 kebab-case，描述性命名 |
命名规范
变更命名（kebab-case）:
✅ add-user-auth
✅ fix-cart-calculation
✅ refactor-payment-service
❌ AddUserAuth
❌ fix bug
❌ refactor
能力命名（kebab-case）:
✅ user-authentication
✅ cart-management
❌ UserAuth
❌ cartMgmt团队协作
┌─────────────────────────────────────────────────────────────┐
│ 团队协作最佳实践 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 变更即文档 │
│ → 每个变更都是自解释的文档单元 │
│ → 新成员可以通过阅读变更了解项目历史 │
│ │
│ 2. 代码审查 + 文档审查 │
│ → 审查代码时同时审查对应的 specs 和 design │
│ → 确保实现符合设计意图 │
│ │
│ 3. 归档即知识库 │
│ → 归档的变更是项目的知识积累 │
│ → 遇到类似问题时可以参考历史变更 │
│ │
│ 4. 主规格同步 │
│ → 定期将 delta specs 同步到主规格 │
│ → 保持主规格与实际实现一致 │
│ │
└─────────────────────────────────────────────────────────────┘常见问题
Q: 可以跳过某个阶段吗？
A: 技术上可以，但不推荐。每个阶段都有其价值：
- 跳过 Explore → 可能遗漏重要需求
- 跳过 Propose → 缺乏范围定义，容易蔓延
- 跳过 Design → 技术决策没有记录
- 跳过 Specs → 需求不清晰，测试困难
- 跳过 Tasks → 实施缺乏计划
Q: 一个变更可以包含多个能力吗？
A: 可以。在 proposal 的 Capabilities 部分列出所有新能力，每个能力对应一个 specs/<name>/spec.md 文件。
Q: 如何修改已有的变更？
A:
- 如果变更还未归档：直接编辑对应的工件文件
- 如果变更已归档：创建新变更来修改现有能力（使用 MODIFIED/REMOVED）
Q: Delta Spec 和主规格有什么区别？
A:
- Delta Spec: 记录变更的增量部分，存在于变更目录中
- 主规格: 当前系统的完整规格，存在于
openspec/specs/中 - 归档时，Delta Spec 会合并到主规格
Q: 任务可以并行执行吗？
A: 可以。只要任务之间没有依赖关系，可以同时进行。但在 AI 助手的实施模式下，通常是顺序执行的。
Q: 如何处理变更中的阻塞？
A:
- 记录阻塞原因（在 tasks.md 中注释）
- 如果需要更新设计或规格，先更新对应工件
- 解决阻塞后继续执行
- 如果阻塞无法解决，考虑拆分变更
Q: 归档后还能修改吗？
A: 归档的变更是只读的历史记录。如果需要修改已归档变更涉及的功能，应该创建新的变更。
参考资源
- OpenSpec 规范: 参见
.claude/skills/目录下的 SKILL.md 文件 - 项目示例: 参见
openspec/changes/archive/目录下的归档变更 - 命令速查:
/opsx:explore [name] → 进入探索模式
/opsx:propose <desc> → 创建变更提案
/opsx:apply [name] → 实施变更任务
/opsx:archive [name] → 归档完成的变更Github 开源：https://github.com/Fission-AI/OpenSpec
转自：https://mp.weixin.qq.com/s/bevsuhfcrJ-O4X6AxlNMxg
EdgeOne
ESA