OpenSpec 规范驱动开发实战一项变更走完全流程的完整指南【免费下载链接】OpenSpecSpec-driven development (SDD) for AI coding assistants.项目地址: https://gitcode.com/GitHub_Trending/op/OpenSpec需求改了三轮合并时才发现代码和文档各说各话——不少团队都踩过这个坑。OpenSpec 是面向 AI 编码助手的规范工具核心是规范驱动开发SDD规范作为单一事实来源变更在独立目录里管理AI 按规范写代码完成后归档合并。下面跟着一项变更把整个流程走一遍。为什么团队要先写规范再写代码 多数团队是代码写完再补文档结果文档描述的是上次做的代码实现的是这次想要的两边永远对不上。AI 编码助手进场后问题被放大没有权威基线AI 每次生成的方向都不一致。OpenSpec 把顺序反过来确认过的行为放在openspec/specs/它是单一事实来源想改行为先往openspec/changes/提交变更提案规范评审通过才动手写代码。合并前发现代码和规范对不上一眼就能看出来。跟着一项变更走完全流程proposal → specs → design → tasks 整个流程由 schemas/spec-driven/schema.yaml 里的四个工件定义每个都有明确的生成规则和依赖关系proposal先写提案只说清三件事——为什么改、改什么、影响面多大。它是整个流程的入口后面三个工件都建立在它之上。specs把改什么翻译成行为契约只写可观察行为不写类名、库选型增量操作用 ADDED / MODIFIED / REMOVED 三种头区分删除项必须注明原因和迁移方式。design写怎么做。变更是跨模块的、或涉及安全和迁移复杂度时才需要建普通小改动可以省。tasks把实现拆成可勾选的任务清单每条任务附带验证方式进度靠勾选项跟踪。依赖关系是文件里写死的specs 依赖 proposaltasks 又依赖 specs 和 design谁也跳不过去。多项变更并行靠归档合并每项变更都是openspec/changes/下的一个独立文件夹互不干扰openspec/changes/ ├── add-change-stacking-awareness/ # specs/ proposal.md tasks.md └── add-devin-desktop-support/ # specs/ proposal.md tasks.md两个人各做一项变更独立开发、审查、测试做完后用归档操作把规范增量合入主规范完成一次原子合并。在 macOS / Linux / Windows 上把 OpenSpec 跑起来 ️跨平台最容易踩的坑是路径别假设斜杠方向macOS 文件系统不区分大小写、Linux 区分。OpenSpec 的做法是把约束直接写进工具上下文——路径一律用path.join()/path.resolve()拼接绝不硬编码分隔符测试的期望值同样要用path.join()。这些规则会一并注入给 AI它生成的规范自然包含 Windows 路径场景。config.yaml 关键字段openspec/config.yaml 是行为定制入口不用改核心代码global: validation: strict: false telemetry: enabled: true开发早期用宽松验证项目稳定后把strict切到 true 当质量门禁遥测可独立开关。commands段还能给 init、validate 等命令设默认参数。它替你盯住哪些质量指标 增量验证两阶段语法验证检查格式是否符合 schema语义验证检查变更是否破坏现有规范的完整性只验证改动的部分不做全量扫描。规范索引缓存系统维护一份索引新增或修改规范时自动更新查询和依赖分析的速度不受规范数量影响。仪表盘规范数、需求数、进行中和已完成的变更、任务完成率一屏看全。上面是一个真实视图10 个规范、64 个需求3 个变更进行中、4 个已完成任务完成率 73%。日常运营重点盯四个数规范覆盖率、变更周转时间、验证通过率、任务完成率。团队落地清单 ✅事项做法规范所有权每个规范模块有明确 owner负责维护和更新变更评审所有规范变更必须过同行审查版本控制规范文件与代码一起入库保持同步自动化测试为关键规范建自动化测试采用节奏分四步试点选非关键模块建基线→扩展铺到其他模块→标准化定组织级标准、建质量门禁→优化按反馈持续调流程。常见问题 ❓规范数量多了会不会拖慢验证不会。增量验证只查改动的部分索引缓存兜住查询规范到几十个量级时性能依然稳定。现有项目要不要推倒重来不要。按试点 → 扩展的节奏走先拿非关键模块做出样板存量代码不动。想接 CI/CD 或加 API、数据模型类规范怎么办都是演进路线内的方向把规范验证挂进流水线、扩展规范类型、更丰富的仪表盘再让 AI 辅助生成规范建议和变更分析。一句话如果你有 AI 编码助手参与开发、多人并行改同一个代码库、想让规范不再和代码脱节OpenSpec 值得试如果是单人项目或一锤子买卖的 demo维护这条工件链的成本会大于收益。规范是投入——人越多、改动轮次越多它回本越快。【免费下载链接】OpenSpecSpec-driven development (SDD) for AI coding assistants.项目地址: https://gitcode.com/GitHub_Trending/op/OpenSpec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考