一、Spec 的前世今生

1.1 什么是规范驱动开发（SDD）

规范驱动开发（Spec-Driven Development, SDD）是当前 AI 编程领域备受推崇的开发方法论。其核心理念是：先写规范，再写代码，用规范约束 AI 的每一步行为。

传统 AI 辅助编码的模式是：

1
需求 → AI 写代码 → 检查 → 发现问题 → 重来

而 SDD 的模式是：

1
需求 → 生成规范文档 → AI 按规范实现 → 按规范验证

1.2 为什么需要 SDD

AI 编码助手虽然能快速生成代码，但如果没有规范驱动的工作流来约束，容易带来以下问题：

  • 上下文中毒：无关信息污染上下文，导致输出偏离
  • 注意力漂移：长对话中偏离原始需求
  • 质量不可控：AI 随机发挥，缺少统一约束
  • 技术债累积：快速生成但缺乏设计的代码难以维护

SDD 的核心理念是：先想清楚再动手，用文档约束行为，用验证确保正确。

1.3 SDD 的演进

阶段 特点
早期 SRS 需求规格说明书，编码前明确系统行为
形式化方法 Z notation、VDM 等形式化规范语言
敏捷时代 User Story、BDD 中的 Gherkin 语法
API Spec 时代 OpenAPI/Swagger、GraphQL Schema、Protocol Buffers
AI 编程时代 文档/资产中心化的 SDD——Spec-Kit、OpenSpec、Superpowers

当前热门的 Spec-Kit 和 OpenSpec 的核心是**“文档/资产中心化"的 SDD**——规范不再只是指导文档，而是软件工程的"源代码”。

二、Spec-Kit 介绍

2.1 Spec-Kit 的设计哲学

GitHub Spec-Kit 是 GitHub 官方开源的规范驱动开发工具包（107K Stars，MIT 许可证），其核心理念是：

规范变成可执行的——直接生成可工作的实现，而非仅仅指导开发。

关键设计原则：

  • 意图驱动开发：先定义"做什么"再定义"怎么做"
  • 多步骤精炼：通过多阶段流程，逐步将需求转化为可执行代码
  • 规范可执行化：规范写得足够清楚，就能直接驱动代码生成
  • 持续进化：任何改动先改规范，再推导计划和任务

Spec-Kit 还引入了**项目宪法（Constitution）**概念，定义不可协商的架构原则（如库优先、测试优先、反抽象原则等），所有生成的代码必须遵守。

2.2 Spec-Kit 的安装

环境要求：

  • Python ≥ 3.11
  • uv 包管理器
  • Git
  • 支持的 AI 编码代理（30+ 种）

安装步骤：

1
2
3
4
5
6
7
8
9
10
11
12
# 1. 安装 uv（Linux/macOS）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 1. 安装 uv（Windows）
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 2. 安装 Specify CLI
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

# 3. 初始化项目
specify init my-project --integration copilot
cd my-project

支持多种 AI 助手配置：--ai claude、--ai copilot、--ai gemini、--ai cursor 等。

2.3 Spec-Kit 的 Skill 与命令介绍

核心命令（7 阶段门控式工作流）

命令 描述 阶段
/speckit.constitution 创建/更新项目治理原则（项目宪法） 基础设置
/speckit.specify 定义要构建什么（需求和用户故事） 规范阶段
/speckit.clarify 澄清不明确的地方 澄清阶段
/speckit.plan 创建技术实现计划 规划阶段
/speckit.tasks 生成可执行任务列表 任务阶段
/speckit.analyze 跨文档一致性和覆盖率分析 分析阶段
/speckit.implement 执行所有任务来构建功能 实现阶段

可选命令

命令 描述
/speckit.taskstoissues 将任务转为 GitHub Issues
/speckit.checklist 生成质量检查清单

项目结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
your-project/
├── .specify/                          # Spec Kit 配置目录
│   ├── memory/                        # 项目"知识库"
│   │   ├── constitution.md            # 项目宪法（架构原则）
│   │   └── constitution_update_checklist.md
│   ├── scripts/                       # 自动化脚本
│   └── templates/                     # 模板文件
├── specs/                             # 功能规范目录
│   └── 001-feature-name/
│       ├── spec.md                    # 功能规范
│       ├── plan.md                    # 实现计划
│       ├── research.md                # 技术研究
│       ├── data-model.md              # 数据模型
│       ├── contracts/                 # API 契约
│       └── tasks.md                   # 任务列表
└── CLAUDE.md                          # AI 助手配置

2.4 Spec-Kit 的通常开发流程

大需求（完整流程）

1
2
3
4
5
6
7
8
9
10
11
12
13
/speckit.constitution   → 建立项目宪法（一次性）
       ↓
/speckit.specify        → 定义功能需求（WHAT & WHY）
       ↓
/speckit.clarify        → 澄清不明确的地方
       ↓
/speckit.plan           → 创建技术实现计划（HOW）
       ↓
/speckit.tasks          → 生成可执行任务列表
       ↓
/speckit.analyze        → 一致性和覆盖率分析
       ↓
/speckit.implement      → 执行实现

每个阶段之间设有门控检查，必须完成当前阶段才能进入下一阶段。

小需求（简化流程）

1
/speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement

效率对比

环节 传统方式 SDD 方式
PRD + 设计文档 + 技术规范 + 测试计划 ~12 小时 ~15 分钟

2.5 Spec-Kit 的优缺点

优点：

  • GitHub 官方出品，社区庞大（107K Stars）
  • 规范可执行化，直接生成代码
  • 严格的阶段门控保证质量
  • 支持扩展和预设系统，定制性高
  • 企业级团队协作功能成熟

缺点：

  • 相对重量级：需要 Python 3.11+ 和 uv，环境配置有门槛
  • 阶段门较严格：7 阶段需要逐步完成，不适合频繁调整方向的项目
  • 学习曲线较陡：七个阶段需要时间理解
  • 灵活性低：更适合从零开始的项目，不够敏捷
  • 不适合 Brownfield：对已有代码库的增量开发支持不如 OpenSpec

三、OpenSpec 介绍

3.1 OpenSpec 的设计哲学

OpenSpec 是由 Fission-AI 团队开发的轻量级规范驱动开发框架（51.3K Stars，MIT 许可证），官方定位：

A lightweight spec-driven framework — universal, open source, and no API keys or MCP required.
（一个轻量级的规范驱动框架——通用、开源，无需 API Key 或 MCP。）

五大设计原则

1
2
3
4
5
→ fluid not rigid          — 流动的，而非僵化的
→ iterative not waterfall  — 迭代的，而非瀑布式的
→ easy not complex         — 简单的，而非复杂的
→ built for brownfield     — 为已有项目设计，而非仅适用于全新项目
→ scalable                 — 从个人项目到企业级均可扩展

OpenSpec 解决的核心问题：AI 编码助手很强大，但当需求仅存在于聊天历史中时，结果是不可预测的。 它在 AI 生成代码之前，让人类和 AI 先就"要构建什么"达成一致。

3.2 OpenSpec 的安装

前置条件： Node.js 20.19.0 或更高版本

1
2
3
4
5
6
# 全局安装
npm install -g @fission-ai/openspec@latest

# 进入项目目录并初始化
cd your-project
openspec init

也支持其他包管理器：pnpm、yarn、bun、nix。

升级更新：

1
2
3
4
5
# 升级包
npm install -g @fission-ai/openspec@latest

# 刷新项目中的 AI 指令
openspec update

初始化后的项目结构：

1
2
3
4
5
openspec/
├── specs/        # 系统当前行为的「源真相」（持久规范）
├── changes/      # 每个变更的独立工作目录（活跃变更）
├── archive/      # 已完成变更的归档
└── config.yaml   # 项目配置

重要：初始化完成后需重启 IDE 才能生效。

3.3 OpenSpec 的 Skill 与 Command 介绍

OpenSpec 通过斜杠命令（slash commands）驱动，使用 /opsx: 前缀：

核心命令

命令 用途 说明
/opsx:explore 自由思考、技术探索 梳理思路，不产生文件，不写代码
/opsx:propose 创建变更提案 一次性生成所有制品（proposal + specs + design + tasks）
/opsx:apply 执行任务，生成代码 AI 按 tasks.md 逐步实现
/opsx:verify 验证实现与规范一致性 对照 artifacts 验证实现
/opsx:archive 归档完成的变更 归档并同步到主 spec

扩展命令

命令 用途
/opsx:new 仅创建变更脚手架（不生成制品内容）
/opsx:continue 逐步生成下一个制品
/opsx:ff 快速通道，一次生成所有 artifacts
/opsx:bulk-archive 批量归档多个已完成变更
/opsx:onboard 项目 onboarding

核心概念：Artifact 链

每个变更包含 4 个工件，有明确依赖关系：

1
2
proposal.md → specs/*.md → design.md → tasks.md
  为什么做？      做什么？       怎么做？      具体步骤
Artifact 职责
proposal.md 变更提案：为什么做、目标/非目标、影响范围
specs/*.md Requirements + Scenarios（WHEN/THEN 测试场景）
design.md 技术方案选择、替代方案对比、风险评估
tasks.md 可执行的 checkbox 任务列表

独特设计：主 Spec + Delta Spec

  • 每次变更产生 Delta Spec（用 ADDED/MODIFIED/REMOVED 标记影响面）
  • 归档时同步到主 Spec（openspec/specs/ 目录）
  • 形成项目级规格知识库，支持长期追溯

3.4 OpenSpec 的日常开发流程

OpenSpec 的工作流遵循：探索 → 提案 → 开发 → 归档 四阶段闭环。

两种工作流模式

模式 适用场景 核心命令
快速模式 需求明确的简单开发 /opsx:propose → /opsx:apply → /opsx:archive
扩展模式 复杂开发/团队协作 /opsx:explore → /opsx:new → /opsx:continue//opsx:ff → /opsx:apply → /opsx:verify → /opsx:archive

多场景实践

场景 推荐流程
需求明确，快速落地 /opsx:propose 具体需求 → 审查 → /opsx:apply → /opsx:archive
需求模糊，需要探索 /opsx:explore → 多轮对话 → /opsx:propose
技术预研 /opsx:explore 多轮对话 → 方向确定后再 /opsx:propose
已有项目接入 openspec init → /opsx:explore 分析现有代码 → 逐步写规格
开发中断后恢复 /opsx:apply <change-name>，AI 从 tasks.md 断点继续
多任务并行 openspec list 查看进度 → /opsx:apply <name> 切换 → /opsx:bulk-archive 批量归档

配置项目上下文（建议必做）

在 openspec/config.yaml 中填写项目信息，注入到所有工件生成过程：

1
2
3
4
5
6
7
8
9
10
11
12
13
schema: spec-driven
context: |
  ## 项目概述
  ...
  ## 技术栈
  ...
  ## 代码规范
  ...
rules:
  proposal:
    - 提案应简洁明了，包含背景、目标、方案概述
  tasks:
    - 每个任务应可独立完成和测试

3.5 OpenSpec 与 Spec-Kit 对比

维度 Spec-Kit OpenSpec
出品方 GitHub 官方 Fission-AI 团队
Star 数 107K 51.3K
技术栈 Python（uv 包管理器） TypeScript（npm）
核心理念 规范可执行化，直接生成代码 规范轻量化，灵活迭代
工作流范式 阶段门控式（7 阶段） 流畅迭代式（3-4 步骤）
AI 代理支持 11+ 20+（更广）
是否需要 API Key 取决于代理 ❌ 不需要
是否需要 MCP 取决于代理 ❌ 不需要
Brownfield 支持 ✅ 支持 ✅ 优先设计
学习曲线 中等（7 阶段需要理解） 平缓
定制性 高（扩展/预设） 中等
规范能否生成代码 ✅ 可以 ❌ 只能指导
变更追踪 Git 分支隔离 changes/ 目录 + 主/delta spec
团队协作 ✅ 企业级 🚧 开发中
环境配置 Python 3.11+ + uv（有门槛） Node.js 20.19+（简单）

选型建议

场景 推荐 原因
大型企业项目、多人协作 Spec-Kit 质量可控、流程可追溯、企业级功能成熟
快速迭代/个人项目 OpenSpec 灵活性高、学习曲线低、无需额外配置
现有代码库改造（Brownfield） OpenSpec 明确为 brownfield 设计，渐进式改造
跨工具开发（频繁切换 AI 工具） OpenSpec 支持 20+ 工具，切换无需重新配置
需要规范自动生成代码 Spec-Kit 规范可执行化是核心定位
严格流程管控 Spec-Kit 阶段门控确保每步质量

一句话总结

  • 选 Spec-Kit：你需要规范直接变成代码，项目大、流程严、团队多
  • 选 OpenSpec：你需要轻量灵活、快速迭代、跨工具使用、改造遗留系统

3.6 OpenSpec 最佳实践

  1. 项目上下文先行配置 — 投入十分钟，收益贯穿整个项目
  2. 善用 explore — 探索阶段发现问题修正成本几乎为零
  3. 变更职责保持单一 — 一个变更只解决一个问题
  4. 规划阶段用高推理模型（如 Claude Opus），执行阶段可用快速模型
  5. 执行前清空对话历史 — 避免探索阶段噪音干扰代码生成
  6. 归档前先 verify — 抓住实现与规格的不一致
  7. 定期 openspec list — 保持对多任务状态的清晰把控
  8. 归档是知识沉淀 — Main Specs 逐渐成为项目的「活文档」

四、OpenSpec 实战：敏感用户过滤需求开发

下面通过一个真实需求，展示 OpenSpec 的完整工作流程。

4.1 需求介绍

需求：在 AIZoneServer 中，对 OA 登录的敏感用户进行过滤，当用户 username 是敏感用户时，无法使用 OA 登录。原来的代码敏感用户是通过七彩石配置文件维护的，现在敏感用户列表需要定时去 OA 那边的接口实时同步。

4.2 OpenSpec 初始化

安装 OpenSpec 之后，需要对项目进行初始化，进入项目根目录执行如下命令：

1
openSpec init

执行完成之后，会让用户挑选对应的工具，这里选择 CodeBuddy Code (CLI)：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
(base) [root@VM-53-193-tencentos AIZoneServer]# openspec init
Detected tool directories: CodeBuddy Code (CLI) (pre-selected for first-time setup)
? Select tools to set up (28 available)
  Selected:  CodeBuddy Code (CLI) 
  Search: [type to filter]
  ↑↓ navigate • Space toggle • Backspace remove • Enter confirm
  › ◉ CodeBuddy Code (CLI) (selected)
    ○ Amazon Q Developer
    ○ Antigravity
    ○ Auggie (Augment CLI)
    ○ Bob Shell
    ○ Claude Code
    ○ Cline
    ○ Codex
    ○ ForgeCode
    ○ Continue
    ○ CoStrict
    ○ Crush
    ○ Cursor
    ○ Factory Droid
    ○ Gemini CLI

执行完成之后，会在项目的 .codebuddy/ 目录下生成 OpenSpec 所需的技能和命令：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
.codebuddy/
├── commands                            # 斜杠命令目录
│   └── opsx
│       ├── apply.md                    # /opsx:apply 命令定义（执行任务生成代码）
│       ├── archive.md                  # /opsx:archive 命令定义（归档已完成变更）
│       ├── explore.md                  # /opsx:explore 命令定义（自由探索不写代码）
│       └── propose.md                  # /opsx:propose 命令定义（生成变更提案）
└── skills                              # 技能目录
    ├── openspec-apply-change           
    │   └── SKILL.md                    # apply 技能：指导 AI 按 tasks.md 逐步实现代码
    ├── openspec-archive-change
    │   └── SKILL.md                    # archive 技能：指导 AI 归档变更并同步主 Spec
    ├── openspec-explore
    │   └── SKILL.md                    # explore 技能：指导 AI 进行需求探索和技术分析
    └── openspec-propose
        └── SKILL.md                    # propose 技能：指导 AI 生成完整的变更提案

4.3 Explore 阶段：需求探索

在开始生成提案之前，需要先执行 explore 阶段，这个阶段主要是为了通过多轮对话让 AI 对需求有一个全面的了解（类似与 Superpowers 中的 brainstorming 头脑风暴流程，但 OpenSpec 的 explore 不允许生成任何文件）。

1
2
3
4
/opsx:explore 在aiwxlogin服务中，需要修改OA登录的敏感用户判断逻辑，当用户username是敏感用户时，无法使用OA登录。原来的代码敏感用户是通过七彩石配置文件维护的，现在敏感用户列表需要定时去OA那边的接口实时同步。
api_impl_OA.go:328-353
敏感用户接口可以参考官方demo：
OA_sensitive_demo.py

探索阶段模型输出：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
问题探索：OA 敏感用户从静态配置改为动态同步
我已经梳理了现有代码。让我画一个当前架构和目标架构的对比：

现状（As-Is）
...
目标（To-Be）
...
几个值得思考的问题
1. 数据同步策略

Demo 中可以看到，SOC 接口使用 游标分页（last_id + page_size，has_more 判断）一次拉全量。几个选择：

全量替换：每次定时任务拉全量列表 → 原子替换内存缓存（简单、一致性强）
增量更新：记住上次 last_id，只拉新增？ — 但 demo 没有体现"增量"语义，last_id 看起来只是分页游标而非时间戳
你觉得敏感用户列表大概有多大规模？如果几百到几千人，全量替换是最简洁可靠的方案。

2. 同步频率

定时多久拉一次？这涉及：

新增敏感用户后，最长多久生效？
接口调用频率限制（SOC 那边是否有 QPS 限制）
常见选择：5 分钟 / 10 分钟 / 30 分钟

3. ...

4. ...
你怎么看这几个问题？特别是：

同步频率你期望多少？
列表规模大概多大？
是否需要保留配置文件静态列表做兜底/补充？
冷启动时的策略偏好？

继续对话，回答模型的追问：

1
/opsx:explore 数据很少，直接全量替换即可，同步频率配置化，默认10分钟。静态配置列表还需要保留，没有冷启动，服务启动的时候开启协程全量拉取即可，参考现有的api.go里面的NewApi()

模型输出：

1
2
3
4
5
6
7
8
9
10
好的，决策点已经清晰了。让我基于你的输入，勾勒出完整的技术方案轮廓：
...

一个细节问题
Demo 返回的人员列表，字段名是什么？我看到 demo 没有具体展示 list 里每个对象的字段结构。你知道返回的 JSON 里哪个字段对应 username 吗？是 login_name？english_name？staff_name？

这决定了我们在 Go 里解析 SensitiveUser 结构体时要映射哪个字段来跟 sessionData.Username 做匹配。

还有一个值得确认的点
当前 isOASensitiveUser 的用途是在 HandleOAPoll 的 done 分支里返回 is_sensitive: true/false，但不阻止登录。你说的"无法使用 OA 登录"是要新增拦截逻辑吗？

模型仍然一直追问不清楚的逻辑，持续多轮对话之后，模型终于思路清晰了：

1
思路已经很清晰了。你想让我创建一个 change proposal 来正式化这个方案，还是现在就退出探索模式直接开始实现？

这一步探索阶段openspec体验上没有使用superpower的brainstorming好，可以使用superpower的brainstorming来代替

4.4 Propose 阶段：生成提案

模型确认好需求之后，开始生成提案：

1
/opsx:propose [需求描述 可选]

这一步会生成一个 change proposal，里面会包含需求的描述、实现方案、可能存在的风险、测试计划等。模型输出如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
## 总结

**Change**: `OA-sensitive-user-remote-sync`
**位置**: `openspec/changes/OA-sensitive-user-remote-sync/`

| Artifact | 描述 |
|----------|------|
| `proposal.md` | 阐述改造动机：从静态配置改为定时远程同步 SOC 敏感人员列表 |
| `design.md` | 技术决策：RWMutex+map 缓存、repo 层封装、双层签名兼容、静态配置兜底 |
| `specs/sensitive-user-sync/spec.md` | 5 个需求规格：定时同步、失败容错、合并判断、repo 封装、配置扩展 |
| `tasks.md` | 5 组 14 个实现任务，从配置扩展 → repo → logic → 判断改造 → 可观测性 |

**All artifacts created! Ready for implementation.**

运行 `/opsx:apply` 开始实现。

这一步会在 openspec 目录下创建如下文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
(base) [root@VM-53-193-tencentos AIZoneServer]# tree openspec/
openspec/
├── changes                                # 活跃变更目录
│   ├── archive                            # 归档目录（已完成的变更会移入此处）
│   └── OA-sensitive-user-remote-sync     # 当前正在进行的变更
│       ├── design.md                      # 技术设计方案（怎么做）
│       ├── proposal.md                    # 变更提案（为什么做、目标、影响范围）
│       ├── specs                          # 本次变更的需求规格
│       │   └── sensitive-user-sync
│       │       └── spec.md                # Delta Spec（本次变更的规格说明）
│       └── tasks.md                       # 任务清单（具体实施步骤）
├── config.yaml                            # OpenSpec 项目配置
└── specs                                  # 主 Spec 目录（系统当前行为的"源真相"）

OpenSpec 的设计哲学："文档/资产中心化"就体现在这里，通过文档变更来管理需求变更，在 changes 目录下保存当前的需求变更。

如果我们发现生成的提案和我们所想要的有出入，可以继续对话，直到模型生成的提案符合我们的预期：

1
/opsx:propose [审核文档，继续对话让模型生成的提案符合预期]

4.5 Apply 阶段：执行实现

模型生成的提案符合预期之后，开始执行 apply 阶段，这个阶段主要是根据 proposal.md 中的描述，生成对应的代码文件：

1
/opsx:apply

代码在开发过程中，会一直更新 tasks.md 中的任务，将其标记为已完成，直到所有任务都完成：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
## Implementation Complete

**Change:** OA-sensitive-user-remote-sync
**Schema:** spec-driven
**Progress:** 16/16 tasks complete ✓

### Completed This Session

- [x] 1.1 `OAConfig` 新增 7 个远程同步配置字段
- [x] 1.2 `GetSensitiveSyncInterval()` 方法（默认 600 秒）
- [x] 2.1 新建 `repo/sensitive_user_repo.go`，定义接口和实现
- [x] 2.2 SOC 内层 SHA256 签名计算
- [x] 2.3 太湖外层 RIO 签名计算（可选）
- [x] 2.4 全量翻页拉取 + 提取 `list[].rtx`
- [x] 3.1 `apiImpl` 新增缓存字段（`sync.RWMutex + map`）
- [x] 3.2 `newApiImpl()` 初始化 `sensitiveUserRepo`
- [x] 3.3 `StartSensitiveUserSync()` 方法
- [x] 3.4 `refreshSensitiveUsers()` 方法
- [x] 3.5 `NewApi()` 中调用启动同步
- [x] 4.1 `isOASensitiveUser` 改为方法，合并远程+静态判断
- [x] 4.2 `HandleOAPoll` 调用方式更新
- [x] 5.1 goroutine defer+recover 防护
- [x] 5.2 同步成功/失败日志
- [x] 5.3 metrics 上报函数

### 修改的文件

| 文件 | 变更类型 |
|------|---------|
| `appconfig/config.go` | 修改：新增配置字段和方法 |
| `repo/sensitive_user_repo.go` | **新建**：SOC openapi 调用封装 |
| `logic/api.go` | 修改：新增字段、初始化、启动同步 |
| `logic/api_impl_OA.go` | 修改：改造 `isOASensitiveUser` |
| `metrics/metrics.go` | 修改：新增同步 metrics |

All tasks complete! You can archive this change with `/opsx:archive`.

4.6 Archive 阶段：归档变更

模型生成的代码文件符合预期之后，开始执行 archive 归档阶段，这个阶段主要是将当前的需求变更归档存储：

1
/opsx:archive

至此，本次需求的全部变更都沉淀成了文档，并且进行了存档 archive，每次变更都有迹可循，形成项目级规格知识库，支持长期追溯。

归档后的目录结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
openspec/
├── changes
│   └── archive                              # 归档目录：存放已完成的变更
│       └── 2026-05-28-OA-sensitive-user-remote-sync  # 归档的变更（带日期前缀）
│           ├── design.md                    # 技术设计方案
│           ├── proposal.md                  # 变更提案（为什么做、目标、影响范围）
│           ├── specs                        # 该变更的需求规格
│           │   └── sensitive-user-sync
│           │       └── spec.md              # Delta Spec（本次变更的规格说明）
│           └── tasks.md                     # 任务清单（实施步骤）
├── config.yaml                              # OpenSpec 项目配置
└── specs                                    # 主 Spec 目录：系统当前行为的"源真相"
    └── sensitive-user-sync
        └── spec.md                          # 主 Spec（由归档时 delta spec 同步而来）

关键点：

  1. changes/archive/ — 归档后，变更从 changes/ 根目录移入 archive/ 子目录，并自动加上日期前缀（2026-05-28-），方便按时间追溯历史变更。

  2. 归档保留完整制品 — proposal.md、design.md、specs/、tasks.md 四件套完整保留，任何时候都能回溯"为什么做、做什么、怎么做、分几步做"。

  3. specs/（根级） — 这是主 Spec，代表系统的当前状态。归档时 /opsx:archive 命令会将变更中的 Delta Spec 同步合并到此处，使其始终反映最新的系统规格。

简单说：changes/archive/ 是历史记录，specs/ 是当前真相。随着项目迭代，archive/ 不断积累历史变更，而 specs/ 持续演进为项目的"活文档"知识库。

五、Superpowers 介绍

5.1 Superpowers 的设计哲学

Superpowers 是由 Jesse Vincent 开发的完整软件开发方法论（210K Stars，MIT 许可证），专为编程 AI 代理设计。

其核心理念是让 AI 代理像有纪律的开发团队一样工作：

  1. 先退一步，询问你真正想做什么
  2. 通过对话梳理出规格说明，分段展示给你确认
  3. 设计通过后，制定清晰的实施计划（详细到"热情但缺乏经验的初级工程师"也能执行）
  4. 强调 TDD（测试驱动开发）、YAGNI（你不会需要它）、DRY（不要重复自己）
  5. 启动子代理驱动开发流程

设计哲学总结：

  • 测试驱动开发 — 永远先写测试
  • 系统化优于即兴 — 流程优于猜测
  • 降低复杂性 — 简洁是首要目标
  • 证据优于声明 — 宣告成功前先验证

5.2 Superpowers 的安装

支持多种编码代理工具：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Claude Code
/plugin install superpowers@claude-plugins-official

# Codex CLI
/plugins  # 搜索 "superpowers" 并安装

# Gemini CLI
gemini extensions install https://github.com/obra/superpowers

# Cursor
/add-plugin superpowers

# Factory Droid
droid plugin marketplace add https://github.com/obra/superpowers
droid plugin install superpowers@superpowers

5.3 Superpowers 的 Skill 介绍

Superpowers 提供一套可组合的技能（Skills）体系：

类别 技能
测试 TDD 循环（含反模式参考）、RED-GREEN-REFACTOR
调试 4 阶段系统化根因分析、完成前验证
协作 头脑风暴、编写计划、执行计划、并行代理调度、代码审查、Git Worktree、子代理驱动开发
元技能 编写新技能、使用 Superpowers 简介

核心特色：

  • 子代理驱动开发：Controller 编排，Implementer 实现，Spec Reviewer + Code Quality Reviewer 分别审查
  • 强制 TDD：RED-GREEN-REFACTOR 循环，不先写测试就会被拒绝
  • 两阶段审查：先审"做对了吗"（Spec 合规），再审"做好了吗"（代码质量）
  • Git Worktree 隔离：每个任务有独立工作空间

5.4 Superpowers 的日常开发流程

Superpowers 的 7 步强制流程：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1. Brainstorming（头脑风暴）
   └─ 苏格拉底式提问，探索替代方案，分段展示设计

2. Git Worktree
   └─ 设计通过后，在新分支创建隔离工作区，验证测试基线

3. Writing Plans（编写计划）
   └─ 拆分为每个 2-5 分钟的小任务，包含具体文件路径和验证步骤

4. Subagent-Driven Development（子代理驱动开发）
   └─ 每个任务分派给新的子代理执行

5. TDD（测试驱动开发）
   └─ RED → GREEN → REFACTOR：先写失败测试 → 写最少代码通过 → 重构

6. Code Review（代码审查）
   └─ 任务间审查，按严重程度报告，关键问题阻止进度

7. Finishing Branch（完成分支）
   └─ 验证所有测试，提供合并/PR/保留/丢弃选项，清理 worktree

六、三者综合对比与协同

6.1 定位对比

维度 Spec-Kit OpenSpec Superpowers
定位 规范可执行化工具包 轻量规格驱动框架 多代理协作开发方法论
核心优势 规范生成代码 + 企业级 Spec 驱动 + 变更追溯 + 知识积累 子代理隔离 + TDD 强制 + 自动化审查
TDD 不强制 不强制 强制
代理模式 单代理 单代理 多子代理（上下文隔离）
Spec 管理 ✅ 完善 ✅ 完善（主/delta/归档） ❌ 无独立 spec
平台依赖 中等 低（任何 AI 助手） 高（需支持子代理派遣）

6.2 协同使用建议

OpenSpec 和 Superpowers 可以互补使用：

  • OpenSpec 管需求层：用于需求规约、设计文档、变更追溯
  • Superpowers 管执行层：将 OpenSpec 的 tasks.md 输入 Superpowers 启动 7 步工作流

协同工作流：

1
2
3
4
5
OpenSpec /opsx:explore → /opsx:propose → 生成 tasks.md
                                              ↓
                          Superpowers 接管 → TDD + 子代理执行 + 代码审查
                                              ↓
                          OpenSpec /opsx:verify → /opsx:archive（归档知识）

花在设计上的时间，会在实现阶段成倍地省回来。