proposal/spec/design/tasks 四件套解剖：OpenSpec 是怎么给 AI 编程“立规矩“的

proposal/spec/design/tasks 四件套解剖OpenSpec 是怎么给 AI 编程立规矩的【免费下载链接】OpenSpecSpec-driven development (SDD) for AI coding assistants.项目地址: https://gitcode.com/GitHub_Trending/op/OpenSpec2025 到 2026 年AI 编程工具迎来爆发式增长但一个尴尬的现实摆在开发者面前Claude Code、Cursor 这类助手写代码越来越熟练想清楚再写却越来越难。需求口头说一遍AI 凭上下文自由发挥几轮对话之后模型甚至忘了最初要什么多个变更并行推进时谁先落地、谁依赖谁全靠人脑记忆。社区里涌现出一批规范驱动开发SDD框架试图解决这个问题而 OpenSpec 是其中增长最猛的一个——GitHub 上已有数万星标社区文章称其每两秒就有一条新规范被创建得物、洞窝等企业也公开分享了用它治理 AI 编码的实践。OpenSpec 给出的答案朴素得有点反直觉既然 AI 最擅长照着做那就先给它一份结构化的规矩——每个变更必须沉淀成 proposal、spec、design、tasks 四份产物让 AI 从猜需求变成按契约执行。本文就从源码层面拆解这四件套每一份文件承担什么职责、它们之间如何流转、最终又是靠什么机制保证变更不失控。一、为什么立规矩能解决 AI 编程失控先看一个典型痛点人类说给用户加个导出功能AI 助手可能直接写一个exportToCSV()函数却没人定义导出成功长什么样数据量太大怎么办要不要走异步任务。问题不在模型能力而在需求没有形成可验证的契约。OpenSpec 的核心设计是把软件开发拆成两个物理世界openspec/specs/当前系统的事实真相和openspec/changes/待实施的变更提案docs/concepts.md 用一张图说得很清楚——specs 描述系统现在怎么工作changes 描述我们打算怎么改两者通过归档archive时的合并动作完成同步。而每一次变更都强制落成一组文档openspec/changes/add-dark-mode/ ├── proposal.md # Why and what ├── design.md # How (technical approach) ├── tasks.md # Implementation checklist ├── .openspec.yaml # Change metadata └── specs/ # Delta specs └── ui/ └── spec.md # Whats changing这套结构不是文档模板的简单堆叠而是被 schemas/spec-driven/schema.yaml 用机器可读的依赖关系焊死的。下面逐一解剖。二、四件套的职责边界why / what / how / steps 的四层分层proposal.md回答Why——变更的理由与边界proposal.md 模板 定义了四个固定章节Why一两句话讲清问题与时机、What Changes新增/修改/移除的具体清单破坏性变更要标注BREAKING、Capabilities本次变更触及哪些能力、Impact影响的代码、API、依赖与系统。模板里最关键的指令藏在 schema 的 instruction 字段里Capabilities 章节是 proposal 与 spec 两阶段的契约。schema 要求作者先运行openspec list --specs摸清项目能力清单再决定是新增能力还是修改既有能力——新增能力要按kebab-case命名如user-auth而不是add-login-endpoint因为能力名要对应可持续演化的系统行为而不是这一次要做的事。看仓库里一个真实的例子add-version-command 的 proposal## Capabilities ### New Capabilities - cli-version: Report the installed OpenSpec version and install context, with an optional privacy-aware update check and stable JSON output. ### Modified Capabilities None.它只声明了一个新能力cli-version后续的 spec、tasks 全部围绕这个能力展开。注意 schema 里有一条硬约束每个变更要么至少声明一个能力新增或修改要么在.openspec.yaml里显式设置skip_specs: true否则openspec validate直接拒绝零 delta 的变更。这把需求必须落成规范变成了不可绕过的关卡。specDelta Specs回答What——系统行为的可测试契约spec 不是设计文档而是行为契约。schema.yaml 的 specs instruction 给出了一条极其实用的判别标准Quick test: if the implementation can change without changing externally visible behavior, it likely does not belong in the spec.也就是说spec 只收用户或下游系统可观测的行为内部类名、框架选型、实现步骤一概排除——那些属于 design 和 tasks。spec 文件用结构化的 Delta 格式书写支持四种操作ADDED Requirements新增能力的行为MODIFIED Requirements改动的行为必须包含完整更新内容避免归档时信息丢失REMOVED Requirements废弃的特性必须给出 Reason 和 MigrationRENAMED Requirements仅改名FROM:/TO: 格式每条需求用 RFC 2119 的 SHALL/MUST 措辞且必须配至少一个#### Scenario:场景注意是四个井号三个会静默失效场景用 WHEN/THEN 描述可验证的输入输出。add-version-command 的 spec 是教科书级示范——报告已安装版本这条需求下挂了四个场景人类可读输出、机器可读 JSON、源码检出场景、旧版旗标兼容。每个场景都是一个可以直接变成测试用例的验收点。design.md回答How——技术方案与取舍记录design 是按需创建的schema 明确列出四种才需要写跨模块/新架构模式、新外部依赖或数据模型变更、安全/性能/迁移复杂度、值得先做技术决策的歧义。模板定义了Context、Goals / Non-Goals、Decisions、Risks / Trade-offs、Migration Plan、Open Questions等章节。看 add-version-command 的 design它把为什么新增独立命令而不是扩展--version本地检查与网络检查分离JSON 信封用 schemaVersion 版本化等七个决策逐条给出 rationale 和备选方案还在风险表里坦承了install.location可能泄露用户名的权衡。仓库里大量轻量变更如add-amp-support根本没有 design.md——这正是 OpenSpec 强调的渐进式严谨风险等级决定文档深度。tasks.md回答Steps——可勾选、可追踪的实施清单tasks 模板 要求分组编号## 1. Setup/- [ ] 1.1 ...。它的特殊性在于apply 阶段会解析复选框格式来追踪进度——只有纯x大小写、间距不限算完成[~]、[-]、空[]一律视为未完成没有复选框的行根本不计入追踪。每个任务还必须写明如何验证完成测试、命令或可观测结果。更严格的是两条组织纪律测试与文档必须跟随各自任务组落地不许攒到最后统一补否则晚组改动会连带早组返工需要归档后执行的工作要作为纯文本放入可选的## Workflow follow-up章节不参与进度追踪。add-version-command 的 tasks 把工作切成模型层、结构化结果层、命令层、兼容性验证层、文档发布层五个组每组都标注了验证方式。三、从提案到归档信息如何逐层升级四件套不是平级文件而是被 schema 的requires字段钉死的有向依赖图proposal (root node) │ ┌───────────┴───────────┐ │ │ ▼ ▼ specs design (requires: (requires: proposal) proposal) │ │ └───────────┬───────────┘ │ ▼ tasks (requires: specs, design)这里有个容易误读的细节依赖是创建顺序的使能条件不是阶段闸门。specs 和 design 都只依赖 proposal可以并行产出tasks 依赖 specs design。Schema 的注释特别强调Dependencies are enablers, not gates——你完全可以在不需要 design 时跳过它add-amp-support就是证明也可以先写 specs 再写 design。所谓规范驱动不是瀑布流而是保证任何一份产物都有上游依据。依赖被真正执行的地方在 src/commands/workflow 的工作流实现里。而 schema 里每个 artifact 的instruction字段是 AI 生成该产物时的行为准则——比如 specs 阶段要求写一个文件就落盘一个让用户看到进度tasks 阶段要求写任务前先检查 design 的 Open Questions。信息的流转终点是归档archive。docs/concepts.md 描绘了完整循环specs 描述当前行为changes 以 delta 形式提出修改实施让修改变成现实tasks 逐项勾选归档把 delta 合并进 specsspecs 描述新行为成为下一轮变更的基线。归档时变更目录会带上日期前缀移入changes/archive/四份产物原样保留——你随时能回溯当时为什么这么改、怎么设计、做了哪些任务这正是社区文章反复强调的可追溯性。四、产物一致性delta 机制如何让变更不失控四件套最容易翻车的地方是文档与代码脱节。OpenSpec 用三道防线把失控概率压到最低。第一道proposal 与 spec 的能力契约前面说过proposal 的 Capabilities 章节是硬约束——它直接决定 spec 文件要落在specs/capability-path/spec.md。schema 甚至要求生成 spec 前先比对 proposal 列出的能力与已存在的 spec 文件从第一个缺失文件开始写不要重写已有文件。这保证提案里承诺的每一个能力都有一份对应的行为规范。第二道delta 合并时的语义校验归档不是简单地把文件拼起来。src/core/specs-apply.ts 的buildUpdatedSpec是合并引擎它先把 delta 解析成操作计划然后做一系列近乎偏执的预校验同一需求出现在多个 delta 区段如 MODIFIED 又 REMOVED直接报错RENAMED 必须 FROM:/TO: 成对出现不成对就拒绝目标 spec 不存在时只允许 ADDEDMODIFIED/RENAMED 一律中止大小写或空白折叠后撞名的需求会被识别为近似错拼并硬性拦截——因为归档是作者最后能发现问题的时机。合并按 RENAMED → REMOVED → MODIFIED → ADDED 的顺序执行每种操作都有近匹配守卫比如 REMOVED 的目标需求已在基线中消失会被当作早已同步的幂等操作no-op而非失败——但若存在仅大小写/空白不同的近似需求则判定为拼写错误并中止。这套逻辑在 src/core/archive.ts 里还有更狠的兜底若合并后的 spec 一个需求都不剩isRetirableSpec会调用校验器确认这条 spec 根本不可能被合法写出从而触发能力退役retire而不是留下一个残破文件。第三道validate 与 skip_specs 的豁免机制src/core/validation/constants.ts 里的错误消息暴露了校验的边界设计找不到 delta 时提示要么补上specs/capability/spec.md并确保每个需求至少带一个#### Scenario:要么在变更的.openspec.yaml设置skip_specs: true显式声明本次无规范级行为变化纯重构、工具链、文档。注意豁免必须显式声明——skip_specs的语义是我确认过没有行为变化而不是我懒得写。这正是给 AI 立规矩的微妙之处规则给了明确的例外出口但出口本身也是一条规则。规矩的注入config.yaml 的上下文约束除了文件结构OpenSpec 还把项目级约束写进 openspec/config.yamlcontext字段注入技术栈、跨平台要求等环境事实rules字段按产物类型给出纪律——specs 必须写跨平台路径场景、tasks 涉及文件路径时要有 Windows CI 验证、design 优先用 Node.js path 模块而非字符串拼接。这些约束会随openspec instructions注入 AI 的工作上下文让规矩不只是事后校验而是事前约束。五、结语四件套的本质是契约的可执行化回到标题的问题OpenSpec 是怎么给 AI 编程立规矩的答案藏在四件套的分工里——proposal 立下为什么做的动机契约spec 立下系统该有什么行为的可测试契约design 记录怎么做的技术取舍tasks 把契约翻译成可勾选、可追踪、可验证的执行步骤。schema 用requires依赖图保证产物之间有据可依delta 机制与归档引擎用语义校验保证合并不丢信息validate 与skip_specs保证例外也有规则可循。这种设计的价值在于它不试图替代人的判断而是把人机对齐这件事从对话时的运气问题变成了文件系统里的结构问题。当每个变更都自带一份可审查、可回滚、可追溯的契约时AI 写代码从自由发挥回归按图施工——这或许就是规范驱动开发在 AI 时代重新流行的根本原因。【免费下载链接】OpenSpecSpec-driven development (SDD) for AI coding assistants.项目地址: https://gitcode.com/GitHub_Trending/op/OpenSpec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考