记录日常编程的开发规范。

OpenSpec + Superpowers 的协同工作流

1.安装与使用

OpenSpec 安装

直接通过 npm 安装：

npm install -g @fission-ai/openspec@latest

然后在项目根目录进行初始化：

openspec init

初始化之后就可以在 codex终端里使用了。

环境要求与配置：

• Node.js：确保已安装 Node.js 16 或更高版本。
• CodeX 终端：OpenSpec 设计为在 CodeX 环境中运行，请确保已安装并配置好 CodeX 终端插件。
• 项目权限：初始化命令需要在具有写入权限的项目根目录下执行，以便创建 openspec/ 配置目录。

常见安装问题：

• 如果遇到权限错误，可以尝试使用 sudo（Linux/macOS）或以管理员身份运行终端（Windows）。
• 若网络环境导致 npm 安装缓慢或失败，可配置国内镜像源，例如：npm config set registry https://registry.npmmirror.com
• 安装完成后，可通过 openspec --version 验证安装是否成功。

OpenSpec 使用整体流程：

1. 创建 proposal：根据需求生成完整的 spec。命令示例：/opsx:propose "创建一个 Todo 应用"。执行后会在 openspec/changes/ 下生成以任务命名的目录，包含提案文档、设计模板、任务清单等结构化文件。
2. 应用 proposal：定义好 spec 之后开始实现。使用 /opsx:apply 命令，OpenSpec 会根据生成的 spec 和任务清单，指导后续开发步骤。
3. 归档 proposal：实现完成后对 proposal 进行归档。使用 /opsx:archive 命令，所有相关变更文件将被移动到 openspec/changes/archive/ 目录，便于版本追溯与团队知识共享。

高级用法与集成：

• 自定义模板：可以在 openspec/templates/ 目录下放置自定义的 Markdown 模板，以适配团队或项目的特定规范。
• CI/CD 集成：OpenSpec 生成的 spec 和任务清单可以作为 CI/CD 流水线的输入，实现自动化测试和部署门禁。
• 与 Superpowers 联动：如上文所述，OpenSpec 生成的详细 spec 是 Superpowers 进行深度技术设计和实现的基础，两者形成了“设计-实现”的闭环。

Superpowers 安装

在 CodeX应用 插件中搜索Superpowers 安装：

安装后会在 CodeX 中注册多个技能：

• brainstorming：头脑风暴，澄清需求和技术细节

• write-plan：基于 brainstorming 结果生成实现计划

• subagent-driven-development：按计划启动子代理逐任务实现，强制 TDD + 两阶段代码审查

2.开发流程

第一步：OpenSpec 生成 Spec

使用 OpenSpec 生成初步 Spec：

/opsx:propose "创建一个单页网页版Todo应用。它必须包含以下核心功能：
1. 一个输入框和一个'添加'按钮，用于创建新任务。
2. 每个任务项显示为一行，包含任务文本。
3. 每个任务项前有一个复选框，点击可将任务标记为'已完成'。
4. 每个任务项旁有一个'删除'按钮，点击可移除该任务。
5. 所有任务数据必须在浏览器刷新后依然保留（使用localStorage）。"

生成产物包括：

• proposal.md — 变更动机

• design.md — 技术方案

• specs/ — 3 个能力规范（task-management、task-persistence、task-ui）

• tasks.md — 8 组共 21 个实现任务

第二步：Superpowers 细化 Spec

使用 Superpowers 继续细化上一步的 Spec，进行头脑风暴和深度技术设计。

产出包括：

• Design Doc：7 个章节，涵盖实现方案、技术风险矩阵、测试策略、边界条件表、扩展性分析

• Delta Spec 补充：回写到 OpenSpec 三个 spec 文件，新增 5 个缺失场景

关键技术决策摘要：

决策项	方案	原因
渲染	DOM API (createElement + textContent)	从根本上防止 XSS
事件	事件委托（dataset.action 派发）	配合 full re-render，避免监听器泄漏
ID	Date.now().toString(36) + 随机后缀	比纯时间戳更抗碰撞
持久化失败	try/catch + 非阻塞告警横幅	应用在内存中保持正常运行

第三步：Superpowers Write Plan

使用 Superpowers writing-plans，基于 Design Doc 创建实现计划。

计划创建后会自动：

1. 创建新分支

2. 使用 subagent-driven-development 执行实现，逐任务完成并提交

第四步：Superpowers 实现

使用 Superpowers 的 subagent-driven-development 执行实现。

最终交付：

• 分支：web-todo-app（11 次提交）

• 实现计划、设计文档、增量规范

• 应用文件：index.html + style.css + app.js

第五步：验证

使用 openspec-verify-change 做完整验证，然后 superpowers 的 finishing-a-development-branch 处理分支。

第六步：OpenSpec 归档

bash

/opsx:archive

所有变更将被保存至 openspec/changes/archive/，支持版本追溯与团队共享。

3.Comet 工具：自动化整个流程

如果觉得手动切换两个工具比较繁琐，可以尝试 Comet 将整个流程自动化。

Comet 将 OpenSpec、Superpowers 串联为五阶段自动化流水线：

阶段	命令	内容
Open	/comet-open	openspec-explore + openspec-propose
Design	/comet-design	superpowers:brainstorm + writing-plans
Build	/comet-build	superpowers:subagent-driven-development
Verify	/comet-verify	openspec-verify-change + finishing-a-development-branch
Archive	/comet-archive	openspec-archive-change

同时 Comet 还提供了快捷路径：

• /comet-hotfix：快速 bug 修复，跳过头脑风暴

• /comet-tweak：小改动，如文案调整、配置调整

安装 Comet

bash

npm install -g @rpamis/comet

使用

cd your-project
comet init
/comet "帮我实现一个 TODO 应用"

Comet 会自动按照 Open → Design → Build → Verify → Archive 五阶段工作流执行。

值得一提的是，每个阶段完成后都会运行阶段守卫（检测脚本），确保当前阶段真的完成了。例如 Open 阶段会判断 OpenSpec 的 proposal、specs、design、tasks 是否正常生成，如果检测发现没有则不会进入下一阶段。

小结

OpenSpec + Superpowers 组合的核心思想是：用 OpenSpec 生成和管理 Spec，然后用 Superpowers 这个"资深工程师"来执行 Spec。

• OpenSpec (SDD)：对齐设计需求，在编码前生成结构化变更提案、需求规范、技术设计和任务拆解

• Superpowers (TDD)：保证代码质量，强制 AI 遵循 TDD、YAGNI、DRY 等工程原则

如果觉得手动切换两个工具比较繁琐，可以尝试 Comet 将整个流程自动化。

参考文档
OpenSpec + Superpowers: SDD+TDD 双驱动 AI 编程工作流 - 探索云原生