文章目录一、背景与痛点：为什么需要 OpenSpec？二、安装与初始化2.1 安装2.2 初始化2.3 配置项目上下文（可选，建议配置）三、项目结构与关键产物四、核心命令与使用场景4.1 工作流模式选择快速模式（Core Profile）扩展模式（Expanded Profile）4.2 核心命令速查4.3 使用场景场景一：已有项目如何接入 OpenSpec场景二：技术预研阶段的探索式调研场景三：需求方向明确但细节待厘清场景四：需求明确，快速落地实现场景五：开发中断后恢复进度场景六：实现完成后发现问题或遗漏情况一：发现 AI 漏做了某个需求情况二：实现有问题，想指出来让 AI 修情况三：做着做着想追加新需求场景七：多任务并行与切换场景八：系统化 Bug 修复流程场景九：大型重构与架构迁移场景十：多人协作与代码审查协作模式一：同一变更的分工协作协作模式二：并行变更后批量合并五、最佳实践5.1 项目上下文先行配置5.2 善用 explore 避免方向性错误5.3 变更迭代还是新建的判断5.4 变更职责保持单一5.5 规划阶段选用高推理模型5.6 执行前清空对话历史5.7 归档不仅是清理，更是知识沉淀5.8 多变更并行时定期检查状态六、实践思考一、背景与痛点：为什么需要 OpenSpec？AICoding 领域，模型的逻辑推理能力在短小上下文中表现卓越，但在大型工程环境中，模型面临两大挑战：上下文中毒：无关信息污染上下文，模型误将噪声当作重要信息注意力漂移：长对话中逐渐偏离原始需求，产生幻觉或偏离预期单纯依靠增加大语言模型的参数规模已无法解决复杂业务逻辑中的幻觉与失控问题。OpenSpec 倡导的是一种「规格驱动开发」（Spec-Driven Development）范式。其核心理念是：在写任何一行代码之前，先由人类与 AI 共同协商并锁定一份机器可读、人可评审的规格文档。需求是什么、技术方案怎么设计、实现步骤有哪些——全部以 Markdown 文件持久化在项目里。AI 每次开工，不是从你的口头描述出发，而是从这份规格文档出发。同样都是「先写规范再写代码」的开源 SDD 框架，OpenSpec(https://github.com/fission-ai/openspec) 展现出了极高的工程性价比，无论是使用 Claude Code、Cursor 还是 Aider，都可以无缝接入 OpenSpec 的规格管理层。OpenSpec 对存量代码库的需求场景，相当友好，相比 Spec Kit 擅长的新项目场景，对于很多公司的开发更为适合。二、安装与初始化2.1 安装# 前置条件：Node.js 20.19.0+npminstall-g@fission-ai/openspec@latest2.2 初始化# 命令行方式进入到你的项目cdyour-project# 初始化openspec init初始化时 CLI 会问你使用哪些 AI 工具（Claude Code、Cursor、Copilot 等），然后自动往对应目录写入 Skill 和斜杠命令文件。注意：初始化完成后，需要重启 ide 才能生效。完成后项目里多出一个openspec/目录：openspec/ ├── specs/ ├── changes/ └── config.yaml# 项目配置2.3 配置项目上下文（可选，建议配置）这一步经常被跳过，但它对工件质量影响巨大。在openspec/config.yaml里告诉 AI 你的项目是什么样的：schema: spec-driven# Project context (项目上下文)# 此信息将在创建各种 artifacts 时提供给 AI 参考context:|## 项目概述XXX 系统（Engine）是 xxx。 核心功能：## 技术栈## 模块结构## 代码规范## 测试规范## Git提交规范context会注入到所有工件的生成过程中——相当于一次配置，以后再也不用在对话开头反复交代技术栈了。可以让 AI 先生成，然后自己修改：请阅读 openspec/config.yaml 并帮我填写项目详情、技术栈和约定等强烈建议该规范文件在组内按照项目维度持续迭代，如果需要更新规范也尽量让 Claude 自己生成，AI 最能理解 AI 生成的规范。三、项目结构与关键产物openspec 结构如下：openspec/ ├── specs/# 系统当前行为的「源真相」（Source of Truth） ← 「系统现在是什么样的」├── changes/# 每个变更的独立工作目录 ← 「我们打算改什么」├── archive/# 已完成变更的归档目录 ← 「历史记录」└── config.yaml# 项目配置目录说明：目录作用内容示例specs/Main Specs，系统当前行为的权威描述user-auth.md、api-specs.mdchanges/活跃变更的工作目录add-dark-mode/、fix-login/archive/已归档变更的历史记录2026-02-27_add-dark-mode/config.yaml项目级配置文件context、rules 等Specs（主规格）是系统当前行为的权威描述——「源真相」。它回答的是「系统现在是怎么运作的」。Changes（变更）是你正在进行的修改——每个功能、每个 Bug 修复独立一个文件夹，互不干扰。它回答的是「我们打算怎么改」。每个变更（Change）都被组织在独立的文件夹中，包含 4 个工件，它们之间有明确的依赖关系，但不是说你必须按这个顺序来。你完全可以先写 design 再补 specs，或者直接跳到 tasks，流程是灵活的。proposal.md → specs/ → design.md → tasks.md 为什么做？ 做什么？ 怎么做？ 具体步骤proposal.md：描述变更的初衷和范围。specs/：具体的逻辑规格，通常包含 “Scenario（场景）” 描述，通过具体的输入输出消除模糊性。这里存放的是Delta Specs（增量规格），仅描述本次变更涉及的行为变化。design.md：技术设计方案，包括本次变更涉及的数据库变更、接口调整等。tasks.md：原子化的任务清单，作为 AI 的执行路径图。四、核心命令与使用场景OpenSpec 分为默认快速模式和扩展全量模式，新安装默认启用快速模式。整体工作流程图：4.1 工作流模式选择快速模式（Core Profile）适合简单开发场景，仅提供 4 个核心命令，流程极简：/opsx:propose→/opsx:apply→/opsx:archive核心命令：/opsx:propose（创建变更+规划制品）、/opsx:explore（梳理思路）、/opsx:apply（实现任务）、/opsx:archive（完成变更归档）。新手可以通过 onboard 命令学习整个工作流程。扩展模式（Expanded Profile）适合复杂开发、团队协作场景，包含脚手架、校验、批量操作等专属命令。开启方式：依次执行openspec config profile + openspec update# 选择 workflows onlyopenspec config profile# 更新，之后需要重启openspec update扩展模式额外支持：/opsx:new、/opsx:continue、/opsx:ff、/opsx:verify、/opsx:sync、/opsx:bulk-archive等命令。4.2 核心命令速查命令核心用途适用场景/opsx:propose创建变更+规划制品快速模式，简单开发/opsx:explore梳理思路、调研问题需求模糊，技术探索/opsx:new启动变更脚手架扩展模式，新建变更/opsx:continue逐步骤生成下一个制品扩展模式，探索式开发/opsx:ff一次性生成所有规划制品扩展模式，需求清晰/opsx:apply执行任务，实现功能所有模式，开发实现/opsx:verify验证实