OpenSpec 到底干了啥

github.com/Fission-AI/... hashrocket.com/blog/posts/...

之前调研过 spec-kit, 社区有另外一个 Spec-Driven Development OpenSpec 也有不错的规模，这里也做一个分析做个横向对比

亮点

命令简洁，通过全局命令行 openspec 来预制执行环境，这点比 spec-kit 的 shell 脚本方便快捷多
命令缩减到 3 个，比 spec-kit 清晰，但是执行效果待验证
提出 Knowledge Base 概念，通过 archive 能够沉淀知识库

准备

Shell 复制代码

# 按照 openspec
npm install -g @fission-ai/openspec@latest

cd your_project

# 初始化 openspec
openspec init

# 初始化项目描述信息
introspect my current project and fill openspec/project.md

命令行

Bash 复制代码

Usage: openspec [options] [command]

AI-native system for spec-driven development

Options:
  -V, --version                    output the version number
  --no-color                       Disable color output
  -h, --help                       display help for command

Commands:
  init [options] [path]            Initialize OpenSpec in your project
  update [path]                    Update OpenSpec instruction files
  list [options]                   List items (changes by default). Use --specs to list specs.
  view                             Display an interactive dashboard of specs and changes
  change                           Manage OpenSpec change proposals
  archive [options] [change-name]  Archive a completed change and update main specs
  spec                             Manage and view OpenSpec specifications
  validate [options] [item-name]   Validate changes and specs
  show [options] [item-name]       Show a change or spec
  help [command]                   display help for command

常用命令（AI Agent 或者 User 都能使用）

openspec init

初始化 openspec，OpenSpec 会询问你使用的是哪种 AI 工具，仅在 Claude Code 中添加了 3 个 AI 指令

openspec update

动态 openspec 更新指令、命令，这个挺好的给了我一些启发，相比于 spec-kit 的 sh，简化了不少

Updated OpenSpec instructions (openspec/AGENTS.md, AGENTS.md)
Updated AI tool files: CLAUDE.md
Updated slash commands:
- .claude/commands/openspec/proposal.md
- .claude/commands/openspec/apply.md
- .claude/commands/openspec/archive.md

openspec archive

把完成 ADDED Requirements 任务归档，用于后续任务的使用

Shell 复制代码

> openspec archive
✔ Select a change to archive add-localstorage-hook     ✓ Complete
Task status: ✓ Complete

Specs to update:
  local-storage-management: create
✔ Proceed with spec updates? Yes
Applying changes to openspec/specs/local-storage-management/spec.md:
  + 1 added
Totals: + 1, ~ 0, - 0, → 0
Specs updated successfully.
Change 'add-localstorage-hook' archived as '2025-12-11-add-localstorage-hook'.

openspec view

查看 OpenSpec 控制面板

Shell 复制代码

> openspec view
OpenSpec Dashboard

════════════════════════════════════════════════════════════
Summary:
  ● Specifications: 1 specs, 1 requirements
  ● Active Changes: 1 in progress
  ● Completed Changes: 0
  ● Task Progress: 8/11 (73% complete)

Active Changes
────────────────────────────────────────────────────────────
  ◉ optimize-readme                [███████████████░░░░░] 73%

Specifications
────────────────────────────────────────────────────────────
  ▪ local-storage-management       1 requirement

════════════════════════════════════════════════════════════

初始化

初始化阶段只生成了 2 个文件 AGENTS.md 和 project.md，project.md 文件需要根据项目进行定制内容

Shell 复制代码

your_project/openspec
├── AGENTS.md
├── changes
|  └── archive
├── project.md    # 项目信息
└── specs

project.md

可以用如下命令进行补充

Plain 复制代码

introspect my current project and fill openspec/project.md

AGENTS.md

描述了整个执行环境和内容

先提案 ：在 changes/ 里写好变更说明、任务清单、规范更新。
再实现：按清单一步步完成，确保符合规范。
最后归档 ：部署后把变更移到 archive/ 并更新正式规范。

命令细节

仅在添加了 3 个 AI 指令，而 Spec Kit 则生成了 8 个指令：

/openspec:proposal - 搭建一个新的 OpenSpec 变更框架并严格验证
/openspec:apply - 实施已批准的 OpenSpec 变更并保持任务同步
/openspec:archive - 归档已部署的 OpenSpec 变更和更新规范。

proposal.md

翻译如下

Markdown 复制代码

---
name: OpenSpec: 变更提案
description: 搭建并严格验证一个新的 OpenSpec 变更方案。
category: OpenSpec
tags: [openspec, change]
---
<!-- OPENSPEC:START -->
**原则**
- 先采用直接、简洁、可落地的实现方式，只有在确有需要或明确提出时才增加复杂度。
- 变更范围要紧扣需求，不做无关扩展。
- 如果需要更多 OpenSpec 规范说明，请查阅 `openspec/AGENTS.md`（位于 `openspec/` 目录，若未找到可运行 `ls openspec` 或 `openspec update`）。
- 对于描述不清或可能存在歧义的地方，先提出问题确认，再修改文件。
- 提案阶段不写任何代码，仅需编写设计类文档（proposal.md、tasks.md、design.md 及规格变更说明）。代码实现仅在提案获批后进入应用阶段。

**工作步骤**
1. 阅读 `openspec/project.md`，运行 `openspec list` 和 `openspec list --specs`，并查看相关代码或文档（如用 `rg`/`ls`）以了解当前实际行为；记录需要进一步确认的缺失信息。
2. 为本次变更选择一个唯一且以动词开头的 `change-id`，并在 `openspec/changes/<id>/` 下建立 `proposal.md`、`tasks.md` 和（如有必要）`design.md`。
3. 将变更拆解为明确的功能或需求，如果涉及多方面内容，则拆分为多个独立的规格变更（spec delta），并说明它们的关系和执行顺序。
4. 若方案涉及多个系统、新架构模式或需在编写规格前进行权衡讨论，将相关设计理由记录在 `design.md`。
5. 在 `changes/<id>/specs/<capability>/spec.md` 中编写规格变更说明（每个能力一个文件夹），使用 `## ADDED|MODIFIED|REMOVED Requirements` 标注变化，并为每个需求至少提供一个 `#### 场景：`，在相关能力之间建立必要的交叉引用。
6. 编写 `tasks.md` 为有序的小型、可验证的任务清单，这些任务应能为用户带来可见进展，包含验证（测试、工具）步骤，并注明依赖关系以及可并行的工作。
7. 使用 `openspec validate <id> --strict` 进行严格验证，在共享提案之前解决所有问题。

**参考**
- 验证失败时，可使用 `openspec show <id> --json --deltas-only` 或 `openspec show <spec> --type spec` 查看详细信息。
- 在编写新需求前，可用 `rg -n "Requirement:|Scenario:" openspec/specs` 搜索已有需求，避免重复。
- 借助 `rg <keyword>`、`ls` 或直接阅读文件探索代码库，确保提案与目前的实现保持一致。
<!-- OPENSPEC:END -->

过程

读取 Agents.md 获取规范
读取 project.md 获取规范
执行 openspec list 获取当前状态

输出

生成 openspec/changes/**/**/spec.md 文件
生成 openspec/changes/**/**/proposal.md 文件
生成 openspec/changes/**/**/tasks.md 文件

apply

翻译如下

Markdown 复制代码

---
name: OpenSpec: 应用
description: 实现已批准的 OpenSpec 更改，并保持任务同步。
category: OpenSpec
tags: [openspec, apply]
---
<!-- OPENSPEC:START -->
**防护原则**
- 优先采用简单、最小化的实现，只有在被请求或明确需要时才增加复杂性。
- 保持更改范围紧密，专注于所请求的结果。
- 如果需要更多 OpenSpec 约定或澄清，请参阅 `openspec/AGENTS.md`（位于 `openspec/` 目录中------如果看不到，可运行 `ls openspec` 或 `openspec update`）。

**步骤**
将这些步骤作为待办事项进行跟踪，并按顺序逐一完成。
1. 阅读 `changes/<id>/proposal.md`，`design.md`（如果存在），以及 `tasks.md`，确认范围和验收标准。
2. 按顺序处理任务，保持修改最小化并专注于所请求的更改。
3. 在更新状态之前确认已完成------确保 `tasks.md` 中的每一项都完成。
4. 在所有工作完成后更新检查清单，使每个任务都标记为 `- [x]` ，并反映真实情况。
5. 在需要更多上下文时参考 `openspec list` 或 `openspec show <item>`。

**参考**
- 如果在实施过程中需要从提案获取额外上下文，请使用 `openspec show <id> --json --deltas-only`。
<!-- OPENSPEC:END -->

过程：

读取 Agents.md 获取规范
阅读openspec/changes/**/**/proposal.md 获取任务

输出：

实现 tasks

archive

Markdown 复制代码

---
name: OpenSpec: Archive
description: 归档已部署的 OpenSpec 变更并更新规范。
category: OpenSpec
tags: [openspec, archive]
---
<!-- OPENSPEC:START -->
**规范约束**
- 优先采用直接、简洁的实现方案，并仅在有明确需求或请求时增加复杂度。
- 将变更范围严格限定在所需的目标之内。
- 如果需要更多 OpenSpec 的约定或说明，请参阅 `openspec/AGENTS.md`（位于 `openspec/` 目录中------如果看不到，可以运行 `ls openspec` 或 `openspec update`）。

**步骤**
1. 确定需要归档的变更 ID：
   - 如果该提示已经包含一个具体的变更 ID（例如在由斜杠命令参数填充的 `<ChangeId>` 块中），去除空格后使用该值。
   - 如果对话中只是模糊引用了一个变更（例如通过标题或摘要），运行 `openspec list` 查找可能的 ID，列出相关候选项，并确认用户想要的那个。
   - 否则，复查对话内容，运行 `openspec list` 并询问用户希望归档哪个变更；在确认变更 ID 前不要继续下一步。
   - 如果仍然无法确定唯一的变更 ID，则停止并告知用户目前无法进行归档。
2. 通过运行 `openspec list`（或 `openspec show <id>`）验证变更 ID，如果该变更缺失、已归档或不适合归档，则停止操作。
3. 运行 `openspec archive <id> --yes` 让 CLI 在无提示的情况下移动变更并更新规范（仅在工具相关工作中使用 `--skip-specs`）。
4. 检查命令输出，确认目标规范已更新且变更已归档到 `changes/archive/` 中。
5. 运行 `openspec validate --strict` 进行验证，如有异常可用 `openspec show <id>` 检查详情。

**参考**
- 在归档前使用 `openspec list` 确认变更 ID。
- 使用 `openspec list --specs` 检查更新后的规范，并在交付前解决任何验证问题。
<!-- OPENSPEC:END -->

当任务完成后可以将 ADDED Requirements 放到 spec 里面

Bash 复制代码

./openspec
├── AGENTS.md
├── changes
|  ├── archive
|  |  ├── 2025-12-11-add-localstorage-hook
|  |  |  ├── proposal.md
|  |  |  ├── specs
|  |  |  └── tasks.md
|  |  └── 2025-12-11-modify-tmates-task-initiation
|  |     ├── proposal.md
|  |     ├── specs
|  |     └── tasks.md
|  └── optimize-readme
|     ├── proposal.md
|     ├── specs
|     |  └── documentation
|     └── tasks.md
├── project.md
└── specs
   └── local-storage-management
      └── spec.md

灵感

统一工具封装 openspec，始终唯一的贯穿整个流程
归档