OpenSpec是 2025~2026 年 AI 辅助编程领域最具影响力的**规范驱动开发Spec-Driven Development, SDD**框架之一。本文将从底层原理、定制封装实战到进阶生态方案做一次系统性梳理。一、OpenSpec 是什么OpenSpec是由 Fission-AI 开源的、专为 AI 编程助手设计的轻量级规范驱动开发框架。它通过在代码编写之前建立一套结构化的规范层让开发者和 AI 在要构建什么上达成共识从而大幅减少模糊提示带来的不可预测结果。1.1 四条设计哲学OpenSpec 的全部设计都围绕这四条哲学展开哲学含义落地体现fluid not rigid流动而非僵化反对硬性阶段闸门按最合理的顺序推进Artifact 依赖是 enabler 而非 gate可跳过、可并行iterative not waterfall迭代而非瀑布允许随时回溯修改任何产物design.md、tasks.md 实现中仍可回改easy not complex简单而非复杂秒级初始化最小仪式感渐进严格小改动用 Lite spec高风险才升级 Full specbrownfield-first存量优先真实开发大多是改存量系统Delta Spec 只描述相对现状改了什么1.2 与同类工具的定位差异OpenSpec 在生态中的位置非常清晰工具定位与 OpenSpec 的差异spec-kit(GitHub)重量级规范套件严格阶段门、大量 Markdown、Python 工具链OpenSpec 更轻更自由Kiro(AWS)IDE 内置规范工作流锁定特定 IDE、仅限 Claude 模型OpenSpec 跨工具跨模型Aider非规范驱动对照组diff/编辑优先无正式规格文档OpenSpec 先对齐再动手Red QueenAI 工作流编排引擎多阶段流水线、自动评审与 OpenSpec 互补而非替代二、核心原理三层架构与 Artifact 工作流2.1 第一层规范注入系统Spec Injection SystemOpenSpec 在 AI 助手启动时自动把specs/和changes/的内容注入上下文让助手始终基于最新规范工作。不同工具的注入路径AI 工具注入机制Claude CodeCLAUDE.md.claude/commands/openspec/.claude/skills/Cursor.cursor/commands/openspec/CopilotAGENTS.mdZed.agents/skills/(v1.10.0 新增)Kimi / TraeSkill 指令模板设计意图关注点分离——开发者专注于变更提案AI 专注于按规范实现。2.2 第二层CLI 引擎核心OpenSpec CLI 引擎是整个框架的大脑由以下核心模块组成2.2.1 ArtifactGraph依赖图引擎每个变更提案Change包含多个Artifact工件如proposal.md、specs/、design.md、tasks.md。这些工件之间存在依赖关系引擎通过拓扑排序O(VE)确定生成顺序。proposal ──→ specs ──→ design ──→ tasks ──→ implement ▲ ▲ ▲ │ └───────────┴──────────┴────────────────────┘ 可随时回改任何节点2.2.2 Mustache 模板引擎所有 Artifact 的生成基于Mustache模板。引擎将规范数据注入模板生成结构化的 Markdown 文件。2.2.3 Delta Spec 合并器这是 OpenSpec 适配存量代码库的核心。Delta Spec 描述相对当前规范改了什么而非重写整份规格。分区含义archive 时的动作## ADDED Requirements新增行为追加到主规范## MODIFIED Requirements变更行为替换主规范对应项## REMOVED Requirements废弃行为从主规范删除## RENAMED重命名同步更新引用为什么用 Delta 而非全量Clarity直接显示改了什么冲突规避不同 change 改不同 requirement 可并行Review 效率reviewer 只看变更Brownfield 契合让修改成为一等公民2.2.4 ToolCommand 适配器跨工具兼容通过适配器模式实现interfaceToolCommandAdapter{getFilePath(id):stringformatFile(content):string}新增 AI 工具支持只需添加新的适配器无需改动核心引擎。2.3 第三层规范驱动工作流OpenSpec 的命令体系分为两套 ProfileCore Profile默认命令作用/opsx:explore动手前的思考伙伴读代码、比较方案不产出文件/opsx:propose一步创建 change 并生成全部规划产物/opsx:apply按tasks.md实现逐项勾选/opsx:sync把 delta spec 合并进主规范/opsx:archive完成并归档一个 changeExpanded Profile进阶命令作用/opsx:new只创建 change 骨架/opsx:continue按依赖顺序一次创建一个 artifact/opsx:ffFast-forward一次性创建全部规划 artifact/opsx:verify校验实现与 artifact 是否一致/opsx:bulk-archive批量归档多个 change/opsx:onboard教学向导同一份 intent多种落地形态Claude Code 用/opsx:proposeCursor 用/opsx-proposeKimi 用/skill:openspec-propose。三、完整工作流演示3.1 典型开发周期# 1. 初始化项目npminstall-gfission-ai/openspeclatestcdyour-project openspec init# 2. 创建变更提案/opsx:propose为 iOS 番茄专注 APP 新增自定义时长功能# AI 自动生成# openspec/changes/custom-timer/# ├── proposal.md # 变更原因、影响范围# ├── specs/ # 需求规范Delta Spec# ├── design.md # 技术方案SwiftUI Node.js# └── tasks.md # 实现任务清单# 3. 按规范实现/opsx:apply# AI 逐项完成 tasks.md 中的任务# ✓ 1.1 修改 SwiftUI 界面添加时长输入框# ✓ 1.2 实现 POST /api/timer/custom 接口# ✓ 1.3 验证时长范围 1-60 分钟# 4. 归档并更新主规范/opsx:archive# 移动到 openspec/changes/archive/2025-01-23-custom-timer/# Delta Spec 合并到 openspec/specs/3.2 Token 效率优化在大型项目中直接投喂全部代码会瞬间耗尽 Token。OpenSpec 通过结构化文件实现按需加载策略效果AI 只读project.md获取全局概览AI 只读tasks.md聚焦当前任务AI 只读相关specs/获取具体需求切片Token 消耗从 ~200K 降至 ~5K上下文加载时间↓ 95%AI 响应准确率↑ 40%四、如何封装自己的定制版OpenSpec 提供了完整的扩展机制让你可以根据团队或项目需求封装定制版。4.1 自定义 Schema工作流定义Schema 定义了 Artifact 的序列和依赖关系。你可以从零创建或 Fork 内置 Schema。# 方式一从零创建openspec schema init api-first\--descriptionAPI-first design workflow\--artifactsapi-spec,proposal,design,tasks\--default生成的目录结构openspec/schemas/api-first/ ├── schema.yaml # 工作流定义 └── templates/ ├── api-spec.md # 每个 artifact 的模板 ├── proposal.md ├── design.md └── tasks.mdschema.yaml 示例name:api-firstartifacts:-id:api-specgenerates:api-spec.mdrequires:[]# 无依赖最先生成-id:proposalgenerates:proposal.mdrequires:[api-spec]# 依赖 api-spec-id:designgenerates:design.mdrequires:[proposal]-id:tasksgenerates:tasks.mdrequires:[design]模板示例templates/api-spec.md#APISpecification:{{change.name}}##Endpoints{{#endpoints}}###{{method}}{{path}}-**Auth**:{{auth}}-**Request**:{{requestSchema}}-**Response**:{{responseSchema}}{{/endpoints}}##RateLimits{{#rateLimits}}-{{tier}}:{{limit}}req/min{{/rateLimits}}4.2 方式二Fork 内置 Schema# Fork 内置的 spec-driven schemaopenspec schema fork spec-driven my-workflow# 或从社区 Schema 仓库获取# 复制到 openspec/schemas/ 目录即可Schema 解析优先级Project-levelopenspec/schemas/name/schema.yaml本地版本控制User-level~/.local/share/openspec/schemas/name/全局共享Built-inOpenSpec 包内置如spec-driven4.3 项目配置config.yaml# openspec/config.yamlschema:api-first# 默认使用的 schemacontext:|Project: My SaaS Platform Tech Stack: React Node.js PostgreSQL Architecture: Microservices with API Gateway Coding Standards: ESLint Airbnb, Conventional Commitsrules:-id:require-testsdescription:All changes must include unit testsapplies:[tasks]-id:api-versioningdescription:API changes must follow semverapplies:[api-spec,design]4.4 工具适配器扩展如果需要支持新的 AI 工具实现ToolCommandAdapter接口// src/core/command-generation/adapters/my-tool.tsexportclassMyToolAdapterimplementsToolCommandAdapter{getFilePath(id:string):string{return.my-tool/commands/${id}.md;}formatFile(content:string):string{// 转换为目标工具的命令格式return---\nname:${id}\ndescription: OpenSpec command\n---\n${content};}}4.5 验证自定义 Schema# 查看可用 schemasopenspec schemas# 验证 schema 格式openspec schema validate my-workflow--verbose# 查看 schema 解析路径openspec schemawhichmy-workflow# 设置项目默认 schemaopenspec configsetschema my-workflow4.6 实战封装团队级定制版假设你的团队是互联网支付团队需要强制包含安全评审和合规检查# 1. 创建团队 Schemaopenspec schema init fintech-payment\--artifactsproposal,security-review,compliance-check,design,tasks\--default# 2. 编辑 templates/security-review.md# 加入 CWE 漏洞检查清单、OWASP Top 10 映射# 3. 编辑 templates/compliance-check.md# 加入 PCI-DSS 合规项、数据脱敏要求# 4. 提交到团队内部 npm 仓库# 其他项目通过 openspec schema init 直接使用五、进阶方案从 OpenSpec 到企业级规范驱动OpenSpec 是入门和中小团队的绝佳选择但随着规模扩大你可能需要更进阶的方案。5.1 方案一spec-kitGitHub 官方定位重量级规范驱动套件适合大型开源项目。核心特性严格的阶段门控Phase Gates完整的 PRDProduct Requirements Document模板Python 工具链和 CLI与 GitHub Issues、Projects 深度集成与 OpenSpec 的关系OpenSpec 更轻更自由spec-kit 更完整更严格。两者可以共存——用 OpenSpec 做日常迭代用 spec-kit 做重大版本规划。5.2 方案二cc-sddCCSD / Kiro 风格定位一行命令部署的 Kiro 风格轻量工作流。# 一行部署npx cc-sddlatest--claude--langja# 命令族/kiro-spec-init → /kiro-spec-requirements → /kiro-spec-design → /kiro-spec-tasks → /kiro-impl核心特性极简部署无需维护 schema 文件内置 TDD 循环RED → GREEN → Refactor独立评审和自动调试适合快速启动和个人开发者选择建议如果你嫌 OpenSpec 的 schema 管理太麻烦cc-sdd 是更轻量的替代。5.3 方案三Red QueenAI 工作流编排引擎定位AI 编码的Jenkins多阶段流水线编排。工作流spec-writing → plan-review ↻ spec-feedback (≤3 retries) → spec-review → coding → code-review ↻ coding (≤3 retries) → testing → human-review → merged核心特性动态阶段通过redqueen.yaml定义可增删门控人机协作每个关键节点都设有人类审批门多 Agent 协作不同 AI worker 负责不同阶段与 OpenSpec 互补Red Queen 不管理规范只编排执行适用场景企业级 CI/CD、需要严格审批流程的团队。5.4 方案四Constitutional SDD宪法约束规范驱动定位带安全约束和审计追踪的规范驱动开发。核心特性权威等级系统Authority Levelauthoritysystem核心业务逻辑和安全要求最高优先级authorityplatform基础设施和技术架构决策authorityfeature用户界面和体验要求最低优先级CWE 漏洞映射每个安全需求关联具体 CWE 编号审计追踪完整的规范变更历史满足合规要求对抗性评估器Adversarial Evaluator独立 Agent 评审实现质量适用场景金融、医疗、政务等对安全和合规有严格要求的行业。5.5 方案五AI Development Patterns模式库Paul Duvall 维护的 ai-development-patterns 是目前最完整的 AI 开发模式库将 SDD 扩展为完整的工程体系。关键模式模式成熟度说明Spec-Driven Development中级用可执行规范指导 AI 代码生成Atomic Decomposition中级将复杂工作拆分为独立可实现的 Agent 任务Parallel Agents高级并发运行多个 Agent 处理独立任务Model Routing高级根据任务需求匹配模型能力、成本和延迟Bounded Autonomy高级通过轮次、花费、时间限制 Agent 自主权Adversarial Evaluator中级分离生成器和评估器用对抗压力提升质量核心理念“Keep Quality Left” —— 在早期运行廉价、快速的控制linter、基础评审将昂贵的控制变异测试、深度 AI 评审留到后期。“Steer, don’t automate” —— 当 Agent 重复犯错时改进 harness指南和传感器而非仅仅修改提示词。六、选择决策树你是个人开发者或小团队 ├── 是 → 追求极简 │ ├── 是 → cc-sdd一行命令即刻开始 │ └── 否 → OpenSpec轻量规范30 工具适配 │ └── 否 → 企业级需求 ├── 需要严格审批流程 → Red Queen多阶段流水线 ├── 需要合规审计 → Constitutional SDD宪法约束 ├── 大型开源项目 → spec-kitGitHub 官方套件 └── 已有 OpenSpec → 渐进升级加入 Adversarial Evaluator Model Routing七、总结维度OpenSpec进阶方向核心定位轻量规范驱动框架企业级规范治理学习曲线低秒级初始化高需理解模式库工具适配30 AI 工具与 CI/CD 深度集成规范严格度流动、可跳过阶段门控、强制评审最佳实践Delta Spec Artifact 工作流Constitutional SDD 对抗性评估一句话总结OpenSpec 让 AI 编程从 vibe coding走向规范驱动而真正让 AI 编程结果可预测的不是更强的提示词而是人和 AI 动手前先对齐、动手后可沉淀的这层轻量规格层。参考资源OpenSpec GitHub 仓库OpenSpec NPM 包OpenSpec 官方文档AI Development PatternsRed QueenConstitutional SDD 论文