文章总结： 本文介绍规范驱动开发(SDD)实践，通过OpenSpecCLI、OpenCode引擎与Superpowers框架构建原生AI编码工作流。核心思想是人类定规范、规则转契约、AI引擎读契约做编码。文章以新增优惠券核销API为例，详细演示了从提案、隔离沙盒、TDD严格编码到归档的全生命周期流程，并给出使用连字符命令和耐心回答AI提问的避坑建议。该方法旨在解决AI编程中代码跑偏和逻辑破坏问题，提升编码质量与可靠性。 综合评分： 88 文章分类： 安全开发,AI安全,解决方案,技术标准

规范驱动开发：基于 OpenCode + OpenSpec 原生流转的 AI 编码工程化实践

原创

adra1n adra1n

YY的黑板报

2026年7月9日 11:44 天津

在小说阅读器读本章

去阅读

在 AI 编程工具（如 Cursor、Claude Code、OpenCode 等）全面普及的今天，许多开发者在享受高效生成的同时候，也饱受其苦：AI 频繁写出“僵尸代码”、对复杂需求理解跑偏、甚至在改动新功能时悄悄破坏了原有的系统逻辑。

为了解决这一痛点，规范驱动开发（Spec-Driven Development, SDD）应运而生。本文将为您拆解如何利用 OpenSpec官方的原生脚手架，配合开源 AI 编码执行引擎 OpenCode与 Agent 技能框架 Superpowers（超级能力），搭建一套让 AI 绝对无法“脱轨”的高质量自动化编码工作流。

🎯 核心架构：化繁为简的原生三剑客

过去，整合 AI 编码工具往往需要配置复杂的第三方 JSON 插件。如今，OpenSpec 已经原生支持了 OpenCode，开发者只需通过官方 CLI 即可一键完成环境绑定。这套工作流的核心思想是：人类定规范 ➔ 规则转契约 ➔ AI 引擎读契约做编码。

1. OpenSpec CLI：大堂经理。负责在初始化时自动为 OpenCode 生成指令集，并建立规范（Spec）目录以锁死业务边界。
2. OpenCode 引擎：核心执行者。读取 OpenSpec 生成的契约并转化为代码，通过加载 superpowers插件来获得顶级的工程约束力。
3. Superpowers 框架：严厉的包工头。强制 AI 在编码时执行分支隔离（Git Worktrees）、微型任务拆解（Plans）和严格的测试驱动开发（TDD）。

⚙️ 第一步：一键初始化（开箱即用）

你不再需要手动去改动繁琐的 plugin配置。只需在你的项目根目录下执行以下两步：

\# 1. 全局安装最新的 OpenSpec CLI
npm install -g @fission-ai/openspec@latest

\# 2. 在项目根目录执行初始化
openspec init

💡 关键步骤：执行 openspec init后，终端会弹出一个交互式菜单，询问你使用的是哪款 AI 工具（如 Cursor、Claude Code 等）。请直接勾选OpenCode并在接下来的提示中关联安装superpowers插件。

初始化后生成的原生目录结构：

• openspec/：存放系统业务和架构的唯一事实来源（主干规范）。
• AGENTS.md：自动生成在项目根目录，用来对 OpenCode 的行为边界进行硬性提示词约束。
• .opencode/command/：OpenSpec 会自动在此目录下生成原生的斜杠指令文件（如 /opsx-explore、/opsx-apply等），让 OpenCode 完美识别。

🔄 第二步：全生命周期实战演练

我们以在现有存量项目中**“新增优惠券核销（Verify Coupon）API”**为例，演示这套原生组合拳在实际开发中的阶段。

阶段一：提出提案与行为对齐（/opsx-propose 或 /opsx-explore）

重启你的 OpenCode 客户端，在 Chat 中直接输入原生斜杠指令：

/opsx-propose 新增优惠券核销接口，用户下单时输入券码，如果优惠券有效且未过期，则返回折扣金额并更新券状态。

或者，如果你想先进入深度思考对齐设计，可以使用：

/opsx-explore 深入推演优惠券核销的各种边界异常情况

OpenCode 会瞬间触发拦截。它绝对不会允许自己直接去动你的核心业务代码，而是在本地创建了一个隔离的规范变更脚手架：

openspec/changes/verify-coupon-api/
├── proposal.md       \# 明确 Why 和 What
├── design.md         \# 明确接口入参和出参 JSON 格式
└── specs/coupon.md   \# 精确描述行为场景的断言文件

此时，Superpowers 的 brainstorming技能被激活，OpenCode 开始扮演架构师向你进行苏格拉底式提问：“如果优惠券已被核销，返回什么错误码？”。在你与 AI 确认完细节后，规则会被沉淀进 coupon.md锁死契约：

\#\# ADDED Requirements
\#\#\# Scenario: 优惠券过期，核销失败
  GIVEN 数据库中存在一张已过期的优惠券 "EXPIRED99"
  WHEN 请求 POST \`/api/v1/coupons/verify\`
  THEN 系统应返回状态码 400 且消息为 "Coupon expired"

最后，运行 openspec validate verify-coupon-api，确保施工蓝图通过自动化结构校验。

阶段二：隔离沙盒与任务拆解（/opsx-apply）

当你确认蓝图无误，在 OpenCode 中下达编码命令 /opsx-apply时，Superpowers 框架开始重拳出击：

1. 自动隔离环境（using-git-worktrees）：它会强制在本地利用 Git Worktrees 开辟一个完全独立的沙盒目录和新分支，确保 AI 即使写错代码，也绝对不会污染你当前正在工作的目录。
2. 拆解微型任务单（writing-plans）：它将刚刚锁死的契约拆解为一个个工作量仅 2-5 分钟的极致微型任务清单（tasks.md），包含具体的文件路径和验证步骤。

阶段三：测试驱动严格编码（TDD 防御门禁）

进入编码阶段，OpenCode 派出的子 Agent 开始严格执行微型任务，并触发 test-driven-development技能（红绿测试循环）：

1. 红灯阶段：AI 必须先在测试文件（如 coupon.test.ts）中写下测试用例，由于没有业务逻辑，测试运行挂掉（显示红灯）。
2. 绿灯阶段：AI 观察到红灯错误后，去写实现代码，直到测试跑通（显示绿灯）。

🛑 硬性门禁拦截：如果 AI 试图偷懒，在没有写测试的前提下，洋洋洒洒把业务代码直接全写完了。Superpowers 的 TDD 门禁会判定这属于“未经测试的代码破坏行为”，会自动执行git checkout把 AI 刚才写的业务代码全部删掉，逼着 AI 重新走先写测试的流程！

阶段四：增量增量同步与最终归档（/opsx-sync 与 /opsx-archive）

在开发过程中，如果你在本地手动微调了变更文件，可以随时让 AI 同步：

/opsx-sync 同步最新的增量 Spec

当所有微型任务单被自动勾选完毕、测试全部通过后，在 Chat 中输入：

/opsx-archive

OpenSpec 重新接管收尾工作：

1. 它把临时变更里的增量优惠券规则，自动合并到你项目长期维护的主干规范文件 openspec/specs/coupon/core_spec.md中。
2. 自动把临时的 verify-coupon-api文件夹丢进历史归档区作为审计线索。
3. 自动清理 Git 临时工作区，安全合入主分支。

💡 实战总结与建议

通过 OpenCode 与 OpenSpec 的原生绑定，我们把原本“在复杂的聊天历史中和 AI 碰运气拼凑代码”的盲盒过程，升级成了“用 Git 管理 MD 规范，由测试门禁严格驱动 AI 编程”的工业级流水线。

给开发者的两条避坑建议：

1. 指令拼写注意：请务必记住命令是连字符（如 /opsx-apply），使用冒号（如 /opsx:apply）引擎将无法识别。
2. 不要嫌 AI 提问烦：在初期阶段 AI 频繁向你确认细节时，千万不要回复“按你觉得对的来”。在规范阶段多花 5 分钟，能帮你省去后期代码跑偏后调试 2 小时的时间。

免责声明：

本文所载程序、技术方法仅面向合法合规的安全研究与教学场景，旨在提升网络安全防护能力，具有明确的技术研究属性。

任何单位或个人未经授权，将本文内容用于攻击、破坏等非法用途的，由此引发的全部法律责任、民事赔偿及连带责任，均由行为人独立承担，本站不承担任何连带责任。

本站内容均为技术交流与知识分享目的发布，若存在版权侵权或其他异议，请通过邮件联系处理，具体联系方式可点击页面上方的联系我。

本文转载自：YY的黑板报 adra1n adra1n《规范驱动开发：基于 OpenCode + OpenSpec 原生流转的 AI 编码工程化实践》