让行为变化可审阅
把一项工作的意图、行为增量、设计和任务保存在独立 change 中，实现前后都能核对。
Tool profile + deep guide · 02 / 05
OpenSpec
一个面向 AI coding assistants 的轻量规格框架：用主 specs 表达当前事实，用 changes 表达候选变化，并在归档时把增量规格合入长期事实。
研究档案 + 深入指南官方项目 · Fission-AI/OpenSpec核对日期 · 2026-08-21
01 · Why included
为什么纳入 SDD 相关研究
官方事实
OpenSpec 明确围绕 specs、change artifacts、delta specs 和 archive 组织开发，是本研究中最直接处理“当前系统事实如何随变更演进”的对象。
02 · Problem
解决什么问题
维护长期规格事实
归档不是简单移动文件；它使 delta specs 成为主 specs 的一部分，并保留变更历史。
03 · Core assets
核心资产
openspec/specs/已经生效的系统行为与当前事实来源。
openspec/changes/<name>/候选变更及 proposal、specs、design、tasks。
archive完成后的 change 历史，以及 delta 与主 specs 的合并结果。
04 · Workflow
第一版理解的基本工作流
- Explore
调查问题、比较方案和澄清边界，可选。 - Propose
创建 change，并形成进入实施前所需的规划 artifacts。 - Apply
依据 artifacts 实施，持续更新任务状态。 - Verify / update / sync
按需要核对实现、修正规划或提前同步规格。 - Archive
结束 change 生命周期，把变化合入主 specs 并保留历史。
05 · Installation
安装与运行形态
npx openspec@latest init运行 CLI、创建 OpenSpec 项目结构，并为所选 coding agent 生成适配的 skills 或 commands。
npx skills add Fission-AI/OpenSpec安装 skills.sh 兼容的 workflow skills；它不会等价完成 CLI、项目脚手架和完整工具配置。
06 · CLI & host
是否必须安装 CLI
准确区分
完整 workflow 需要可调用 OpenSpec CLI，但不要求一定全局安装
官方将 CLI 描述为工作流引擎，skills/commands 是驱动入口。只阅读方法或手工维护 Markdown 可以不用 CLI，但这不等于完整运行官方 workflow。
宿主 coding agent需要，用于调用 OpenSpec skills 或 commands。
OpenSpec CLI完整状态、校验、同步和归档流程需要可调用。
全局安装不是唯一方式；可以使用 npx、包管理器或 Nix 等官方方式。
继续深入
下方已经合并完整概念、调用方式与 13 个 Skill：查看安装与调用细节
07 · Early strengths
初步优势
- 把“当前事实”和“候选变化”分开，适合持续演进的代码库。
- 每个 change 独立成目录，便于审阅、并行和历史追踪。
- 支持多个 coding agents，并把相同工作流映射成对应 skills 或 commands。
08 · Limits
限制与风险
- CLI 与宿主 skill 文件需要保持版本和配置同步。
verify关注 artifacts 与实现一致性，不替代测试、TDD 或代码审查。- 与其他会生成 design/tasks 的方法组合时，容易出现双重权威和规划漂移。
09 · Scenarios
可能适用的场景
当团队需要跨多次变更维护可审阅的产品行为规格、保留 change 历史，或在棕地项目中逐步建立规格事实时，OpenSpec 可能更有价值。只需要一次性实现纪律而不维护长期规格时，应比较其额外成本。
10 · Relations
与其他工具的初步关系
初步观察
OpenSpec 更靠近“做什么、系统事实如何变化”。Superpowers 更偏可靠执行；Spec Kit 也有结构化规格阶段；Trellis 同样在仓库保存 specs 与任务。它们之间的重叠和权威边界需要同题实验后再判断。
OpenSpec · Deep guide
从心智模型到 13 个 Skill
这一部分面向第一次接触 SDD 的读者，也可作为有经验开发者的工作流速查表。正文离线可读；搜索、筛选、复制与目录定位由本地 JavaScript 渐进增强。
01 · Mental model
把“当前事实”和“候选变化”分开
OpenSpec 不是代码生成器或测试框架，而是人、团队与 AI 之间的一层轻量协议：先把预期行为和变化边界落盘，再围绕它推进实现。
Specs 记录系统现在如何表现；Changes 记录系统准备如何改变。
openspec/specs/
当前事实 · Source of truth
按能力域保存已经生效的 requirements 与 scenarios。
archive←merge delta
openspec/changes/<name>/
候选变更 · Change package
集中保存 proposal、delta specs、design 和 tasks。
当前行为
由 Requirement 与 Scenario 组成，是已经生效的系统事实。
独立工作
一次功能、修复或调整一个目录，可与其他 change 并行。
规划产物
proposal 讲原因，specs 讲行为，design 讲方案，tasks 讲步骤。
只写变化
用 ADDED、MODIFIED、REMOVED 表达增量，不重写全系统。
依赖图
规定产物及其依赖；默认 spec-driven，也可按团队流程扩展。
变化成为事实
将 delta 合入主 specs，并把完整 change 移入历史目录。
02 · Setup & invocation
终端里安装，Codex 对话里驱动
CLI 是工作流引擎，Skill 是让 coding agent 调用引擎的操作说明；二者角色不同。
终端 · 安装与初始化
完整工作流需要 CLI 可调用，但不强制全局安装。
npm install -g @fission-ai/openspec@latest
cd your-project
openspec init
openspec --versionnpx openspec@latest init 也可以直接运行最新 CLI。
Codex · 调用 Skill
初始化生成或安装 skill 后，在对话中调用工作流入口。
$openspec-propose add-dark-mode
$openspec-apply-change add-dark-mode
$openspec-verify-change add-dark-mode
$openspec-archive-change add-dark-mode$openspec-* 不是 shell 命令，不要粘贴到终端。
只安装 skills 可以吗？
npx skills add Fission-AI/OpenSpec 只安装 skills.sh 兼容的操作说明。可以用于阅读或宿主发现，但完整的状态读取、校验、同步和归档仍要求 OpenSpec CLI 可调用。相比之下，Superpowers 的核心能力主要由宿主 skills 提供，没有同等角色的独立工作流 CLI。
03 · Workflow map
两条路径：快速完成，或逐份控制
Core 适合日常工作，Expanded 适合教学、审计和逐个批准 artifacts；二者最终都落到 apply、verify 和 archive。
一次生成规划，直接进入实施
01explore调查与澄清，可选可选
02propose一次生成实施前 artifacts规划
03apply-change按 tasks 实施代码
04archive-change同步规格并保留历史收尾
建立 change 后逐份推进
01new-change只建立容器和状态开始
02continue / ff逐份或一次补齐 artifacts规划
03apply / update实施并修正规划迭代
04verify / archive核对后归档收尾
propose vs new + ff
propose 是快捷入口；new-change 只建容器，ff-change 再补齐规划。
sync vs archive
sync-specs 提前更新主规格但保留 active change；archive 才结束生命周期。
verify vs tests
verify-change 核对实现与 artifacts 的映射；它不替代运行测试、TDD 和代码审查。
04 · Complete example
用“新增暗色模式”走完一次 change
这个例子展示规格如何从候选变化成为长期事实，而不是规定唯一的 UI 实现。
探索问题
用
$openspec-explore确认主题范围、系统现状和待决问题，不写生产代码。建立规划
用
$openspec-propose add-dark-mode生成 proposal、delta specs、design 和 tasks；其中新增“用户可切换主题”的 requirement 与 scenarios。按任务实施
用
$openspec-apply-change add-dark-mode读取上下文、逐项修改代码和测试，并勾选 tasks。发现新信息时修正
若实施中确定必须跟随系统主题，用
$openspec-update-change add-dark-mode同步调整规格、设计和任务。归档前核对
用
$openspec-verify-change add-dark-mode检查完整性、正确性和一致性，同时实际运行项目测试。归档成为事实
用
$openspec-archive-change add-dark-mode将 delta 合入主 specs，并把 change 移到日期化历史目录。
05 · Skill catalog
13 个 Skill：分别是什么、何时用
先按意图直接定位；需要查找时可再用名称、用途或关键词筛选。
显示 13 / 13
没有匹配的 Skill。
核心工作流
日常快速路径 · 6 项openspec-explore
进入思考伙伴模式，调查问题、理解代码库、比较方案和澄清需求，不创建正式 change artifacts。
适合目标模糊、技术路径未定，或实施中需要暂停并重新调查。
$openspec-explore边界、产物与衔接
- 读取
- 代码、已有 specs、active changes 和必要的项目上下文。
- 产物
- 调查结论、方案权衡和待确认问题；可画图，但不生成正式 artifacts。
- 边界
- 不实施、不承诺方案，也不自动创建 change。
- 下一步
- 明确后转
propose或回到正在进行的 change。
openspec-propose
创建命名 change，并一次生成进入实施前所需的 proposal、delta specs、design 与 tasks。
适合范围已较清楚，希望快速获得一套可审阅的完整规划。
$openspec-propose add-dark-mode边界、产物与衔接
- 读取
- 项目上下文、现有 specs、schema 和 artifact instructions。
- 创建
- change 目录及实现所需的全部规划 artifacts。
- 边界
- 只做规划，不修改生产代码；生成完成后停止并等待审阅。
- 下一步
- 批准后调用
apply-change。
openspec-apply-change
读取 change 上下文并按 tasks 实施代码，在工作中持续更新完成状态。
适合规划已经可实施，需要开始或继续完成其中的任务。
$openspec-apply-change add-dark-mode边界、产物与衔接
- 读取
- CLI 返回的 apply context、proposal、specs、design 与 tasks。
- 修改
- 代码、测试和任务勾选状态。
- 边界
- 遇到模糊、缺失或矛盾的规划时应暂停，不自行掩盖偏差。
- 下一步
- 规划需修正则
update-change；完成后验证并归档。
openspec-update-change
根据实施中发现的新信息，修正现有 change 的 specs、design 或 tasks，使规划重新与现实一致。
适合实现揭示遗漏、假设变化或 artifact 之间出现矛盾。
$openspec-update-change add-dark-mode边界、产物与衔接
- 读取
- 现有 change artifacts、实现进度和用户给出的新事实。
- 修改
- 受影响的 planning artifacts，并保持依赖一致。
- 边界
- 不是绕过评审的补丁；重大范围变化仍需明确确认。
- 下一步
- 回到
apply-change继续实施。
openspec-sync-specs
把 active change 的 delta specs 同步到主 specs，同时保留 change 继续工作。
适合变更尚未结束，但主规格需要提前反映已经确定的行为。
$openspec-sync-specs add-dark-mode边界、产物与衔接
- 读取
- change delta specs 与对应的主 capability specs。
- 修改
- 主 specs 中相应的新增、修改和删除部分。
- 边界
- 不归档、不结束生命周期；active change 仍然存在。
- 下一步
- 继续实施，结束时仍调用
archive-change。
openspec-archive-change
在工作完成后核对状态、同步 delta specs，并把 change 移入日期化归档目录。
适合实现和验证完成，要让候选变化成为长期事实并保留历史。
$openspec-archive-change add-dark-mode边界、产物与衔接
- 读取
- artifact 完成度、tasks、delta specs 和主 specs。
- 修改
- 同步主规格，并将 change 移至 archive 历史。
- 边界
- 不完整或未验证的 change 必须先警告并获得明确选择。
- 下一步
- 生命周期结束；新需求建立新的 change。
展开式工作流
精细控制与审计 · 6 项openspec-new-change
创建一个新的 change 容器、选择 schema 并显示 artifact 状态，但不生成规划内容。
适合希望逐份控制和审阅 artifacts，而不是一次得到完整规划。
$openspec-new-change add-dark-mode边界、产物与衔接
- 读取
- 项目配置、可用 schemas 与当前 active changes。
- 创建
- 命名 change 的目录与元数据，不创建 proposal/design/tasks。
- 边界
- 只初始化容器；不规划、不实施。
- 下一步
- 用
continue-change逐份推进，或用ff-change快进。
openspec-continue-change
查看 artifact 依赖和当前状态，只创建下一份已解锁的产物，便于逐份确认。
适合团队希望在 proposal、specs、design、tasks 之间设置清晰审阅点。
$openspec-continue-change add-dark-mode边界、产物与衔接
- 读取
- artifact 状态、instructions 和已完成的依赖文件。
- 创建
- 依赖已满足的下一份 artifact。
- 边界
- 不跳过依赖、不硬编码产物，也不自动实施。
- 下一步
- 重复调用直到 implementation-ready，再转
apply-change。
openspec-ff-change
在已有 change 上沿依赖图快速生成所有进入实施前所需的剩余 planning artifacts。
适合已经用
new 建立 change，但决定不再逐份确认，想直接准备实施。$openspec-ff-change add-dark-mode边界、产物与衔接
- 读取
- 当前 artifact 状态、依赖图、已有产物和 instructions。
- 创建
- 依赖允许的所有剩余规划产物，直到可实施。
- 边界
- 只完成规划，不实施；已有内容不会因“快进”被忽略。
- 下一步
- 审阅后调用
apply-change。
openspec-verify-change
从完整性、正确性与一致性检查实现是否匹配 tasks、requirements、scenarios 与 design。
适合准备归档，希望获得按严重度排序、带代码证据的核查报告。
$openspec-verify-change add-dark-mode边界、产物与衔接
- 读取
- apply context、tasks、delta specs、design、代码与测试证据。
- 产物
- 按 CRITICAL / WARNING / SUGGESTION 分组的核查报告。
- 边界
- 不替代运行测试、TDD 或人工 code review。
- 下一步
- 修复问题或更新 change；通过后
archive-change。
openspec-bulk-archive-change
一次检查并归档多个 changes，识别同一 capability 的冲突，并结合实现证据决定合入顺序。
适合多条并行工作同时结束，需要集中处理规格合并和归档。
$openspec-bulk-archive-change边界、产物与衔接
- 读取
- active changes、artifact/task 状态、delta specs、实现证据和主 specs。
- 修改
- 统一确认后，按冲突决议同步规格并逐项归档。
- 边界
- 不自动选择 changes；不完整项和冲突必须明确警告。
- 产物
- 每个 change 的 archived / skipped / failed 结果。
openspec-onboard
在当前真实代码库选择一项小任务，边解释边走完探索、规划、实现与归档的完整周期。
适合第一次系统学习 OpenSpec，希望看到真实文件和命令如何串起来。
$openspec-onboard边界、产物与衔接
- 读取
- 代码库结构和候选小任务，避免范围过大或风险过高的工作。
- 产物
- 真实 change artifacts、实现改动和归档记录，并穿插解释。
- 边界
- 是交互式教学，会在用户确认后对真实项目做实际工作。
- 下一步
- 按日常 Core 或 Expanded 路径独立工作。
项目维护
OpenSpec 官方项目 · 1 项release-openspec
驱动 OpenSpec 项目自身的可恢复发布状态机：审计 changeset、版本 PR、beta/正式包和 GitHub Release。
适合Fission-AI/OpenSpec 维护者准备或继续发布官方包；普通业务项目不使用。
$release-openspec边界、产物与衔接
- 读取
- 官方仓库的 GitHub、CI、changesets、版本 PR、npm 和 release 状态。
- 操作
- 按安全状态机推进下一步，并在审批、权限或异常处暂停。
- 边界
- 不属于普通 change 生命周期，也不是发布你的应用。
- 下一步
- 报告当前状态、相关 URL 和需要的人类动作，方便后续恢复。
06 · Boundaries
七个最容易踩的坑
多数误用来自输入位置、流程边界和两套规划同时存在。
把
$openspec-*输进终端：它是 Codex skill 调用；终端使用openspec ...CLI。只装 skill，不准备 CLI：workflow skill 不是独立执行引擎，完整流程需要 OpenSpec CLI 可调用。
以为 propose 会顺手实现：它有明确 planning boundary，完成 artifacts 后必须停止。
把 verify 当成测试套件：它检查规格映射与实现证据，不替代执行测试、TDD 或 code review。
混淆 sync 与 archive：sync 保持 change 活跃；archive 才结束生命周期并保存历史。
两套 design/tasks 都当真：与其他方法组合时应指定唯一权威，否则规划会漂移。
用 release-openspec 发布业务应用：它只服务 OpenSpec 官方仓库自身的包发布。
11 · Next research
后续研究问题
- 在真实棕地项目中，从第一个 change 开始需要多少前置整理？
- 多个并行 changes 修改同一 capability 时如何处理冲突？
- CLI 和生成的 Codex skills 升级后怎样避免漂移？
- 与 Superpowers、Spec Kit 或 Trellis 组合时，哪些 artifacts 应成为唯一权威？
12 · Official sources
官方来源与版本边界
OpenSpec 仍在迭代，命令、profile 和 Skill 边界应以官方仓库当前版本为准；本页用于建立心智模型和快速查询。