背景与痛点为什么需要 OpenSpecAICoding 领域模型的逻辑推理能力在短小上下文中表现卓越但在大型工程环境中模型面临两大挑战​上下文中毒​无关信息污染上下文模型误将噪声当作重要信息​注意力漂移​长对话中逐渐偏离原始需求产生幻觉或偏离预期单纯依靠增加大语言模型的参数规模已无法解决复杂业务逻辑中的幻觉与失控问题。OpenSpec 倡导的是一种「规格驱动开发」Spec-Driven Development范式。​其核心理念是在写任何一行代码之前先由人类与 AI 共同协商并锁定一份机器可读、人可评审的规格文档。​需求是什么、技术方案怎么设计、实现步骤有哪些——全部以 Markdown 文件持久化在项目里。AI 每次开工不是从你的口头描述出发而是从这份规格文档出发) 展现出了极高的工程性价比无论是使用 Claude Code、Cursor 还是 Aider都可以无缝接入 OpenSpec 的规格管理层。OpenSpec 对存量代码库的需求场景相当友好相比 Spec Kit 擅长的新项目场景对于很多公司的开发更为适合。维度Spec KitOpenSpec出品方GitHubFission AI设计思路严格门控步步审查依赖图驱动灵活迭代擅长场景新项目从零开始Greenfield已有代码库增量开发Brownfield规范体量较重单阶段可达 800 行较轻文档约 250 行流程自由度线性不能跳步非线性随时可以回改协作友好度直接改主规范多人易冲突变更隔离archive 时合并Token 消耗较高较低变更追踪无内建机制Delta Spec 归档历史二、安装与初始化2.1 安装# 前置条件Node.js 20.19.0 npm install -g fission-ai/openspeclatest2.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.mdchanges/活跃变更的工作目录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保持源真相的更新