OpenSpec完整指南：如何给AI编码助手写好"规则书"
【免费下载链接】OpenSpecSpec-driven development (SDD) for AI coding assistants.项目地址: https://gitcode.com/GitHub_Trending/op/OpenSpec
AI编码助手直接写代码，出来的东西时好时坏、风格漂移。规范驱动开发（SDD，就是先写"规则书"，再让AI照规则写代码）解决的就是这个问题。OpenSpec是面向AI编码助手的规范驱动开发工具：它替你管理规则书，从提变更到验证通过。
📘 AI编码助手为什么需要一本规则书
你遇到过这种情况吗：同一个功能让AI写三遍，三遍风格都不一样，还经常违背之前约定好的行为？AI编码助手直接动手写代码，问题会越积越多——它写的"对"，但不是你项目想要的"对"。
漂移的根源，是缺少一本写在纸面上的规则书。脑子里的需求留不下痕迹，AI只能凭感觉发挥。规范驱动开发给出的答案是：先把"系统应该怎么表现"写成人人（包括AI）都能读懂的规范，再让AI动手。那么如何用OpenSpec管理AI代码？答案就在下一张图。
🗺️ 一张图看懂OpenSpec
OpenSpec把活分成三层，各干各的：
- 规范存储：装下所有已确认的行为规范，也就是规则书的"定稿"
- 变更管理：改规则的提案和增量修改都发生在这里，不动主规范
- 验证执行：每个变更落地前先过一道检查，保证不破坏既有规则
仪表盘让你一眼看清项目状态。打开它会看到：10个规范、64个需求、3个进行中的变更、4个已完成的变更，任务完成率73%——做到哪一步、缺什么，一张图讲完。
🧩 核心四件套：提案→规范→设计→任务
OpenSpec里的每个变更，都是一串四个工件，按顺序生成，后者依赖前者：
- 提案（proposal.md）：说清"为什么改"，是整条链的起点
- 规范（specs/*.md）：基于提案写"系统应该有什么行为"
- 设计（design.md）：在规范之上敲定"怎么做"的细节
- 任务（tasks.md）：把设计拆成可执行的任务清单
以 openspec/changes/ 目录为例，每个变更都是一个独立文件夹。比如add-change-stacking-awareness/里面有proposal.md、tasks.md，还有一个specs/子目录，里面按 change-creation、change-stacking-workflow、cli-change 等能力再拆。独立文件夹意味着多个变更可以并行推进，做完后归档合回主规范。
🚀 快速上手：3步跑起来
- 第1步，初始化：在项目里运行
openspec init，自动生成 openspec/ 目录和模板文件 - 第2步，写规范：照着提示从四件套写起，先提案，再规范、设计、任务
- 第3步，验证：运行
openspec validate 变更名，缺什么、哪里不合规，一条条报给你
不需要额外配置就能跑起来，规则想改，后面随时能改。
⚙️ 自定义规则：一份配置看懂
自定义规则只需要看两个文件。
第一个是 openspec/config.yaml，管全局行为：验证严格度、遥测开关、命令的默认参数都在这——
global: validation: strict: false # 开发初期放宽验证 telemetry: enabled: true commands: validate: outputFormat: detailed开发期放宽验证、上线前收紧，都不用改代码。
第二个是 schemas/spec-driven/schema.yaml，它定义"四件套"怎么生成：每个工件声明自己产出什么文件、依赖哪些前置工件——
description: Default workflow - proposal → specs → design → tasks artifacts: - id: proposal generates: proposal.md - id: specs generates: "specs/**/*.md" requires: [proposal]改模板、改依赖，就能长出属于自己的规范流程。
⚡ 跨平台与性能：两个细节
- 跨平台：OpenSpec在macOS、Linux、Windows上行为一致。代码里一律用Node.js的
path.join()和path.resolve()拼路径，从不硬编码斜杠，同一套规范文件在任何系统打开都正常。 - 性能：验证只查"你改的部分"，不重查全库。系统还维护一份规范索引，查规范、查依赖的速度不随规范数量变慢。
👥 团队怎么用
采用节奏建议一步一迈：
| 阶段 | 做法 |
|---|---|
| 试点 | 挑一个非关键模块，先写出规范基线 |
| 扩展 | 把经验复制到更多模块，形成团队约定 |
| 标准化 | 制定组织级规范标准，设质量门禁 |
| 优化 | 根据使用反馈持续调整流程 |
日常盯住四个指标：
- 规范覆盖率：关键功能是否都有对应规范
- 变更周转时间：从提案到归档花多久
- 验证通过率：变更一次通过的比例
- 任务完成率：规范变更是否真的落地了
❓ 常见问题
问：已有项目，需要重写文档吗？不需要。openspec/ 目录和代码放在同一个仓库里，按模块逐个补写规范即可，存量代码不用动。
问：AI没照规范写怎么办？先跑openspec validate检查规范本身，再把验证通过的规范交给AI对照执行。规范就是契约，AI的产出必须以它为准。
问：Windows上能正常用吗？能。macOS、Linux、Windows三端命令和目录结构完全一致，路径分隔符这类跨平台问题已由工具内部处理。
总结
- 先写规则书，再让AI动手
- 变更隔离管理，验证后落地
- 两份配置，定制所有行为
【免费下载链接】OpenSpecSpec-driven development (SDD) for AI coding assistants.项目地址: https://gitcode.com/GitHub_Trending/op/OpenSpec
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
