术语表

这里汇集了 OpenSpec 中的所有术语，并用通俗语言解释。快速浏览一遍，阅读其余文档时会更轻松。

术语按主题分组，每组内按字母顺序排列。

核心名词

规格说明 (spec)。 描述系统某个部分如何运行的文档。规格说明存放在 openspec/specs/ 中，按领域组织，由需求和场景组成。它是“这款软件做什么？”这一问题共同认可的答案。参阅概念。

唯一真实依据 (source of truth)。 整个 openspec/specs/ 目录。它记录系统当前共同认可的行为。变更提出对它的修改；归档则将这些修改应用进去。

变更 (change)。 一个工作单元，以文件夹形式放在 openspec/changes/<name>/ 下。变更包含该项工作的所有内容：提案、设计、任务，以及引入的规格说明修改。一个变更对应一项功能或修复。

产物 (artifact)。 变更中的一份文档。标准产物包括提案、差异规格说明、设计和任务。它们按依赖顺序创建，并以前一项为基础。

差异规格说明 (delta spec)。 变更中的规格说明，只通过 ADDED、MODIFIED 和 REMOVED 部分描述变更内容，而非重述整份规格说明。这让 OpenSpec 能够简洁地修改现有系统。参阅概念。

领域 (domain)。 规格说明的逻辑分组，例如 auth/、payments/ 或 ui/。你可以选择符合自己系统思维方式的领域。

规格说明中的要素

需求 (requirement)。 系统必须具备的一项行为，通常使用 RFC 2119 关键词编写，例如：“系统 SHALL 在 30 分钟后使会话过期。”需求说明的是做什么，而非如何做。

场景 (scenario)。 需求实际运行时的一个具体、可测试示例，通常采用 Given/When/Then（给定/当/则）形式。场景让需求可以验证：你可以据此编写自动化测试。

RFC 2119 关键词。 MUST、SHALL、SHOULD 和 MAY 这些词具有关于需求严格程度的标准化含义。MUST 和 SHALL 表示绝对要求；SHOULD 表示建议，但允许例外；MAY 表示可选。名称来自定义这些关键词的互联网标准文档。

产物

提案 (proposal.md)。 变更的原因和内容：其意图、范围和大致方案。首先创建的产物。

设计 (design.md)。 变更的实现方式：技术方案、架构决策以及预计会修改的文件。简单变更可以省略。

任务 (tasks.md)。 带复选框的实现清单。AI 在 /opsx:apply 期间会逐项执行并勾选。

生命周期

归档 (archive)。 完成变更的过程。其差异规格说明会合并到主规格说明中，变更文件夹则移到 openspec/changes/archive/YYYY-MM-DD-<name>/。归档后，规格说明反映新的实际情况。参阅概念。

同步 (sync)。 将变更的差异规格说明合并到主规格说明中，但不归档该变更。通常会自动执行（归档时会提示同步），也可以通过 /opsx:sync 单独执行，适用于耗时较长的变更。参阅命令。

工作流与命令

OPSX。 当前的标准 OpenSpec 工作流，围绕灵活的操作构建，而非僵化的阶段。它的斜杠命令均以 /opsx: 开头。参阅OPSX 工作流。

斜杠命令 (slash command)。 在 AI 助手聊天中输入的命令，例如 /opsx:propose。斜杠命令驱动工作流，不是终端命令。参阅命令的工作方式。

探索 (/opsx:explore)。 思考伙伴命令。它会读取代码库、比较选项，并把模糊想法梳理成具体计划。它不会编写代码；除非你要求将探索结果记录为变更，或在它提出该建议时表示同意，否则也不会写入其他内容。当你有问题但尚无计划时，建议从此命令开始。参阅先探索。

CLI。 在终端运行的 openspec 程序。它用于设置项目、列出和验证变更、打开仪表板以及归档，是 OpenSpec 的终端端工具。参阅CLI。

技能 (skill)。 包含指令的文件夹 (.../skills/openspec-*/SKILL.md)，AI 助手会自动检测并遵循其中的指令。技能正逐渐成为跨工具交付 OpenSpec 工作流的标准方式。

命令文件 (command file)。 针对具体工具的斜杠命令文件 (.../commands/opsx-*)。这是较早采用的交付机制，目前仍与技能并行支持。通常无需直接编辑这些文件。

配置档案 (profile)。 项目中安装的斜杠命令集合。默认的 Core 包含 propose、explore、apply、update、sync、archive。expanded 集合还增加 new、continue、ff、verify、bulk-archive、onboard。使用 openspec config profile 更改配置档案。

交付方式 (delivery)。 OpenSpec 为你的工具安装技能、命令文件，还是两者都安装。此项在全局范围配置，并通过 openspec update 应用。

自定义

模式 (schema)。 定义工作流包含哪些产物，以及它们之间依赖关系的规范。内置默认值是 spec-driven（提案 → 规格说明 → 设计 → 任务）。你可以从中派生自己的模式，也可以自行编写。参阅自定义。

模板 (template)。 模式中的 Markdown 文件，用于规定 AI 为特定产物生成的内容形式。编辑模板后，AI 会立即采用新输出方式，无需重新构建。

项目配置 (openspec/config.yaml)。 单个项目的设置：默认模式、注入每次规划请求的 context:，以及针对每种产物的 rules:。这是让 OpenSpec 了解技术栈和约定的最简便方式。参阅自定义。

上下文注入 (context injection)。 将项目背景放入 config.yaml 的 context: 字段，使其自动加入 AI 生成的每份产物中。与寄希望于 AI 读取单独文件相比，这种方式更可靠。

依赖图 (dependency graph)。 由产物的 requires: 关系构成的有向图。它是一个 DAG（有向无环图：箭头只向前，不会形成循环），OpenSpec 用它判断接下来可以创建什么。

助力，而非关卡 (enablers, not gates)。 产物依赖关系说明下一步可以做什么，而不是必须做什么这一原则。任何时候都可以回头修改任一产物。参阅核心概念速览。

跨仓库协作（beta）

仅当你的规划跨越多个仓库时，才适用以下术语。目前处于 beta 阶段，大多数用户无需关注。参阅存储库用户指南。

存储库 (store)。 专门用于规划的独立仓库。它拥有你熟悉的 openspec/ 结构（规格说明和变更），以及一个简短的身份文件。你可以在本机按名称注册一次，之后便可从任意位置通过任何 OpenSpec 命令在其中工作。

引用 (reference)。 代码仓库在 openspec/config.yaml 中声明自己会使用某个存储库。引用为只读：代码仓库保留自己的根目录，而 openspec instructions 会增加所引用存储库规格说明的索引，并为每项提供准确的获取命令。

工作上下文 (working context)。 openspec context 为当前仓库汇总的内容：它自己的 OpenSpec 根目录，以及所引用的每个存储库和相应的获取方式。也就是“我正在使用哪些内容？”这一问题的答案。

工作集 (workset)。 在个人机器上创建的一组本地文件夹，可以将它们一起打开（一个存储库和正在使用的代码仓库）。使用 openspec workset create 明确创建；这些本地路径不会提交到共享规划仓库。

另请参阅

• 核心概念速览：一页介绍五个理念
• 概念：详细说明
• 命令的工作方式：斜杠命令与 CLI 的区别