背景与痛点：为什么需要 OpenSpec？

AICoding 领域，模型的逻辑推理能力在短小上下文中表现卓越，但在大型工程环境中，模型面临两大挑战：

• ​上下文中毒​：无关信息污染上下文，模型误将噪声当作重要信息
• ​注意力漂移​：长对话中逐渐偏离原始需求，产生幻觉或偏离预期

单纯依靠增加大语言模型的参数规模已无法解决复杂业务逻辑中的幻觉与失控问题。

OpenSpec 倡导的是一种「规格驱动开发」（Spec-Driven Development）范式。​其核心理念是：在写任何一行代码之前，先由人类与 AI 共同协商并锁定一份机器可读、人可评审的规格文档。​需求是什么、技术方案怎么设计、实现步骤有哪些——全部以 Markdown 文件持久化在项目里。AI 每次开工，不是从你的口头描述出发，而是从这份规格文档出发) 展现出了极高的工程性价比，无论是使用 Claude Code、Cursor 还是 Aider，都可以无缝接入 OpenSpec 的规格管理层。OpenSpec 对存量代码库的需求场景，相当友好，相比 Spec Kit 擅长的新项目场景，对于很多公司的开发更为适合。

维度	Spec Kit	OpenSpec
出品方	GitHub	Fission AI
设计思路	严格门控，步步审查	依赖图驱动，灵活迭代
擅长场景	新项目从零开始（Greenfield）	已有代码库增量开发（Brownfield）
规范体量	较重，单阶段可达 800+ 行	较轻，文档约 250 行
流程自由度	线性，不能跳步	非线性，随时可以回改
协作友好度	直接改主规范，多人易冲突	变更隔离，archive 时合并
Token 消耗	较高	较低
变更追踪	无内建机制	Delta Spec + 归档历史

二、安装与初始化

2.1 安装

# 前置条件：Node.js 20.19.0+
npm install -g @fission-ai/openspec@latest

2.2 初始化

# 命令行方式进入到你的项目
cd your-project
# 初始化
openspec init

初始化时 CLI 会问你使用哪些 AI 工具（Claude Code、Cursor、Copilot 等），然后自动往对应目录写入 Skill 和斜杠命令文件。由于我使用的 Claude Code，便选择了对应的 Agent。

Space 选择，Enter 确认

注意：初始化完成后，需要重启 ide 才能生效。

完成后项目里多出一个 openspec/ 目录：

openspec/
├── specs/
├── changes/
└── config.yaml   # 项目配置

2.3 配置项目上下文（可选，建议配置）

这一步经常被跳过，但它对工件质量影响巨大。在 openspec/config.yaml 里告诉 AI 你的项目是什么样的：

schema: spec-driven

# Project context (项目上下文)
# 此信息将在创建各种 artifacts 时提供给 AI 参考
context: |
  ## 项目概述
  XXX 系统（Engine）是数据平台的核心调度引擎，负责将不同类型的任务(Job)提交到对应类型的执行引擎组件上运行。

  核心功能：
  - 向上：接收平台各应用提交的任务(Job)
  - 内部：负责任务的负载均衡 & 优先级调度
  - 向下：将各种类型的任务真正提交(submit)到具体的执行引擎组件上

  ## 技术栈

  ## 模块结构

  ## 代码规范

  ## 测试规范

  ## Git提交规范

# Per-artifact rules (每个artifact的规则)
rules:
  proposal:
    - 提案应简洁明了，包含背景、目标、方案概述
    - 方案设计需考虑向后兼容性
  tasks:
    - 每个任务应可独立完成和测试
    - 任务粒度适中，避免过大或过细
    - 需要标明任务涉及的模块和文件路径

context 会注入到所有工件的生成过程中——相当于一次配置，以后再也不用在对话开头反复交代技术栈了。rules 则是针对特定工件类型的额外要求。

可以让 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.md
changes/	活跃变更的工作目录	add-dark-mode/、fix-login/
archive/	已归档变更的历史记录	2026-02-27_add-dark-mode/
config.yaml	项目级配置文件	context、rules 等

Specs（主规格） 是系统当前行为的权威描述——「源真相」。它回答的是「系统现在是怎么运作的」。

Changes（变更） 是你正在进行的修改——每个功能、每个 Bug 修复独立一个文件夹，互不干扰。它回答的是「我们​打算怎么改​」。

每个变更（Change）都被组织在独立的文件夹中，包含 4 个工件，它们之间有明确的依赖关系：

proposal.md  →  specs/  →  design.md  →  tasks.md
 为什么做？     做什么？     怎么做？       具体步骤

• ​proposal.md​：描述变更的初衷和范围。
• ​specs/​：具体的逻辑规格，通常包含 “Scenario（场景）” 描述，通过具体的输入输出消除模糊性。这里存放的是 ​Delta Specs（增量规格）​，仅描述本次变更涉及的行为变化。
• ​design.md​：技术设计方案，包括本次变更涉及的数据库变更、接口调整等。
• ​tasks.md​：原子化的任务清单，作为 AI 的执行路径图。

这个依赖关系是​「使能」而不是「门禁」​。意思是：有了 proposal 才能生成 specs，有了 specs 才能生成 design——但这是 AI 生成工件时需要的输入，而不是说你必须按这个顺序来。你完全可以先写 design 再补 specs，或者直接跳到 tasks，流程是灵活的。

​Delta Specs 与 Main Specs 的关系​：

• openspec/specs/：Main Specs，描述系统当前的完整行为，是「源真相」
• openspec/changes/<name>/specs/：Delta Specs，描述本次变更带来的行为变化
• 归档时，Delta Specs 会自动合并到 Main Specs，保持源真相的更新