AI 编程三剑客：Spec-Kit、OpenSpec、Superpowers 深度对比与实战指南

AI 编程三剑客：Spec-Kit、OpenSpec、Superpowers 深度对比与实战指南

本文将深入介绍 GitHub 官方的 Spec-Kit、社区热门的 OpenSpec 以及跨平台方法论工具 Superpowers 三个 AI 编程辅助工具，从安装配置到实战使用，再到三者协同的最佳实践，带你全面掌握 AI 驱动的规格化开发新范式。

前言：为什么需要这些工具？

2024-2026 年，AI 编程工具经历了爆发式增长。从最初的代码补全，到如今的 AI Agent 自主编程，开发者面临一个核心问题：如何让 AI 真正理解我们的意图，并按照预期的方式工作？

三个工具应运而生，它们从不同角度解决这个问题：

工具	核心问题	类比
Spec-Kit	"按什么规矩干"	建筑规范手册
OpenSpec	"改了什么"	施工变更单
Superpowers	"怎么干"	施工队工作手册

接下来，让我们逐一深入了解。

---

一、Spec-Kit：GitHub 官方的规格驱动开发框架

1.1 简介

Spec-Kit 是 GitHub 官方在 2025 年初推出的开源工具包，专为"规格驱动开发"（Spec-Driven Development）设计。它的核心理念是：先写规格，再写代码。

• GitHub 仓库 ：github.com/github/spec...
• Stars：69.1k ⭐
• 技术栈：Python (uv 包管理器)
• 适用 AI：Claude Code、Copilot Agent 等

1.2 核心概念

Spec-Kit 引入了三个关键文档类型：

┌─────────────────────────────────────────────────────────┐
│                    CONSTITUTION.md                       │
│         (项目宪法：全局约束、技术栈、代码规范)            │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│                       SPEC.md                            │
│           (功能规格：具体功能的详细设计)                  │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│                      REVIEW.md                           │
│              (审查清单：验收标准和检查项)                 │
└─────────────────────────────────────────────────────────┘

CONSTITUTION.md（宪法）：定义项目级别的"不可违反"规则

• 技术栈选择（如必须使用 TypeScript）
• 代码风格（如禁止使用 any 类型）
• 架构约束（如必须遵循 Clean Architecture）

SPEC.md（规格）：描述具体功能的实现细节

• 功能目标
• 接口设计
• 数据结构
• 边界条件

REVIEW.md（审查清单）：AI 完成后的自检列表

• 代码是否符合宪法
• 功能是否满足规格
• 测试覆盖率是否达标

1.3 安装教程

前置条件

• Python 3.10+
• uv 包管理器（推荐）

安装步骤

# 1. 安装 uv（如果还没有）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 克隆 Spec-Kit 仓库
git clone https://github.com/github/spec-kit.git
cd spec-kit

# 3. 安装依赖
uv sync

# 4. 验证安装
uv run spec-kit --version

快速初始化项目

# 在你的项目根目录运行
uv run spec-kit init

# 这会创建以下文件结构：
# your-project/
# ├── .spec/
# │   ├── CONSTITUTION.md    # 项目宪法
# │   ├── specs/             # 功能规格目录
# │   │   └── example.md
# │   └── reviews/           # 审查清单目录
# │       └── example.md

1.4 使用教程

步骤一：编写 CONSTITUTION.md

# Project Constitution

## Technology Stack
- Language: TypeScript 5.x
- Runtime: Node.js 20 LTS
- Framework: Next.js 14 (App Router)
- Database: PostgreSQL 15
- ORM: Prisma

## Code Standards
- MUST use strict TypeScript (no `any`)
- MUST follow ESLint + Prettier config
- MUST write tests before implementation (TDD)
- MUST NOT use console.log in production code

## Architecture
- Follow Clean Architecture principles
- Use repository pattern for data access
- All business logic in /src/domain
- All API handlers in /src/api

步骤二：为新功能编写 SPEC.md

# Feature Spec: User Authentication

## Goal
Implement JWT-based authentication with refresh token rotation.

## Interfaces

### POST /api/auth/login

interface LoginRequest {
  email: string;
  password: string;
}

interface LoginResponse {
  accessToken: string;
  refreshToken: string;
  expiresIn: number;
}

### POST /api/auth/refresh

interface RefreshRequest {
  refreshToken: string;
}

interface RefreshResponse {
  accessToken: string;
  refreshToken: string; // rotated
  expiresIn: number;
}

## Security Requirements
- Access token expires in 15 minutes
- Refresh token expires in 7 days
- Refresh token rotation on every use
- Bcrypt for password hashing (cost factor 12)

## Edge Cases
- Invalid credentials: return 401
- Expired refresh token: return 401, require re-login
- Concurrent refresh attempts: only first succeeds

步骤三：让 AI 执行

在 Claude Code 或其他 AI 工具中：

请根据 .spec/CONSTITUTION.md 和 .spec/specs/auth.md 实现用户认证功能。
实现完成后，根据 .spec/reviews/auth.md 进行自检。

步骤四：审查与迭代

Spec-Kit 会生成审查报告，标记哪些检查项通过/失败：

# Review: User Authentication

## Constitution Compliance
- [x] TypeScript strict mode enabled
- [x] No `any` types used
- [x] Tests written before implementation
- [ ] ❌ Found console.log on line 45 of auth.service.ts

## Spec Compliance
- [x] Login endpoint implemented
- [x] Refresh endpoint implemented
- [x] Token rotation working
- [ ] ❌ Missing: concurrent refresh protection

---

二、OpenSpec：轻量级规格驱动开发工具

2.1 简介

OpenSpec 是由 Fission-AI 团队开发的规格驱动开发（SDD）工具，专注于灵活的、可自定义的工作流 。最新版本使用 OPSX 工作流，支持 20+ AI 编码助手。

• GitHub 仓库 ：github.com/Fission-AI/...
• Stars：23.7k ⭐
• 技术栈：TypeScript (npm)
• 适用 AI：Claude Code、Cursor、Windsurf、OpenCode、Codex、Copilot 等 20+ 工具

2.2 核心概念

OpenSpec 最新版本使用 OPSX 工作流，提供灵活的动作式工作方式，而非固定的阶段流程：

┌─────────────────────────────────────────────────────────┐
│                   OPSX Workflow                      │
│               (灵活动作，迭代流动）                   │
├─────────────────────────────────────────────────────────┤
│  /opsx:new ───► /opsx:continue ───► /opsx:apply ───► /opsx:archive │
│      │               │               │              │              │
│      └───────────────┴───────────────┴──────────────┘              │
│       创建工件           逐步实施                归档            │
└─────────────────────────────────────────────────────────┘

工作流程：

1. /opsx:new - 开始新的变更（创建 proposal）
2. /opsx:continue - 逐步创建工件（specs、design、tasks）
3. /opsx:apply - 实施工阶段，执行任务并更新工件
4. /opsx:archive - 归档完成的功能到知识库
5. /opsx:explore - 探索想法，思考问题（可选）
6. /opsx:ff - 快速前进，一次性创建所有规划工件
7. /opsx:sync - 同步到主分支（可选）

2.3 安装教程

前置条件

• Node.js 20.19.0 或更高版本
• npm 或 pnpm（也支持 bun、yarn）

安装步骤

# 方式一：全局安装（推荐）
npm install -g @fission-ai/openspec@latest

# 方式二：项目级安装
npm install --save-dev @fission-ai/openspec

# 方式三：使用 npx 直接运行
npx @fission-ai/openspec init

初始化项目

# 在项目根目录运行
openspec init

# 这会创建以下结构：
# your-project/
# ├── .openspec/
# │   ├── changes/            # 活跃变更（OPSX workflow）
# │   ├── changes/archive/     # 归档的变更（知识库）
# │   ├── config.yaml         # 项目配置（可选）
# │   └── schemas/           # 自定义工作流模式（可选）
# └── .claude/skills/openspec-*  # 自动生成的技能

提示 ：初始化时会提示创建 openspec/config.yaml 项目配置文件，这是可选但推荐的。

2.4 使用教程

步骤一：创建配置文件（可选）

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js
  API conventions: RESTful, JSON responses
  Testing: Vitest for unit tests, Playwright for e2e
  Style: ESLint with Prettier, strict TypeScript

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format for scenarios
  design:
    - Include sequence diagrams for complex flows

配置说明：

• schema：默认工作流模式（当前为 spec-driven）
• context：项目上下文，会注入到所有工件
• rules：每个工件的具体规则

步骤二：创建新变更

# 开始新的变更
/opsx:new Add user profile page

AI 会询问：

1. 你想构建什么？
2. 使用哪个工作流模式？

生成的工件结构：

openspec/changes/add-user-profile-page/
├── proposal.md           # 变更提案（为什么、范围、方法）
├── specs/                # 功能规格
│   └── spec.md
├── design.md             # 技术设计
└── tasks.md              # 实施任务清单

步骤三：逐步创建工件

# 继续创建下一个工件（基于依赖关系）
/opsx:continue

每次调用会：

1. 检查哪些工件已准备好
2. 创建一个工件
3. 显示解锁的下一个工件

步骤四：快速前进

# 一次性创建所有规划工件
/opsx:ff add-user-profile-page

使用场景：当你已经清楚要构建什么，想要快速启动时。

步骤五：实施

# 执行任务，并更新工件
/opsx:apply

AI 会：

1. 遍历 tasks.md 中的任务
2. 逐一实现
3. 实时更新任务状态
4. 如有问题，更新 specs/ 或 design/

步骤六：归档

# 完成后归档
/opsx:archive add-user-profile-page

将变更移动到知识库：

openspec/changes/archive/2025-02-12-add-user-profile-page/

步骤七：探索想法

# 不确定要构建什么时，先探索
/opsx:explore

这是一个思考伙伴，帮助澄清想法、比较选项、明确需求。

查看状态

# 查看当前变更状态
openspec status --change add-user-profile-page --json

返回：

{
  "artifacts": [
    {"id": "proposal", "status": "done"},
    {"id": "specs", "status": "ready"},
    {"id": "design", "status": "ready"},
    {"id": "tasks", "status": "in_progress"}
  ]
}

---

三、Superpowers：Claude Code 的"施工队工作手册"

3.1 简介

Superpowers 是由 Jesse Vincent（obra）开发的 AI 编程方法论工具包，专注于执行方法论。它不是文档管理工具，而是一套让 AI 更高效、更可靠地执行编码任务的最佳实践集合，通过"技能"（Skills）系统引导 AI 像高级工程师一样工作。

• GitHub 仓库 ：github.com/obra/superp...
• Stars：50k ⭐
• 技术栈：Markdown + JavaScript Plugin
• 适用 AI：Claude Code、OpenCode、Codex

3.2 核心概念

Superpowers 的核心是 "让 AI 像高级工程师一样工作"：

┌─────────────────────────────────────────────────────────┐
│                    Superpowers 方法论                    │
├─────────────────────────────────────────────────────────┤
│  🧪 TDD-First      │ 强制 AI 先写测试，再写实现          │
├─────────────────────────────────────────────────────────┤
│  🤖 Sub-Agents     │ 拆分复杂任务给专门的子代理          │
├─────────────────────────────────────────────────────────┤
│  📝 Code Review    │ 实现后自动触发代码审查              │
├─────────────────────────────────────────────────────────┤
│  🔍 Exploration    │ 实现前先充分探索代码库              │
├─────────────────────────────────────────────────────────┤
│  ✅ Verification   │ 每步都要验证，不盲目前进            │
└─────────────────────────────────────────────────────────┘

3.3 安装教程

前置条件

• Bash 或 Zsh shell (macOS/Linux)
• PowerShell 或 Command Prompt (Windows)

Claude Code 用户（推荐方式）

Claude Code 有插件市场，安装最简单：

# 在 Claude Code 中执行
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

# 验证安装
/help

看到 brainstorm、write-plan、execute-plan 这 3 个命令就说明安装成功。

OpenCode 用户

# 1. 克隆 Superpowers 仓库
git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers

# 2. 创建目录
mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills

# 3. 创建符号链接（插件）
ln -s ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js ~/.config/opencode/plugins/superpowers.js

# 4. 创建符号链接（技能）
ln -s ~/.config/opencode/superpowers/skills ~/.config/opencode/skills/superpowers

# 5. 重启 OpenCode

Windows 用户（PowerShell）

# 1. 克隆仓库
git clone https://github.com/obra/superpowers.git "$env:USERPROFILE\.config\opencode\superpowers"

# 2. 创建目录
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode\plugins"
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode\skills"

# 3. 创建符号链接（插件，需要开发者模式或管理员权限）
New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.config\opencode\plugins\superpowers.js" -Target "$env:USERPROFILE\.config\opencode\superpowers\.opencode\plugins\superpowers.js"

# 4. 创建符号链接（技能，无需特殊权限）
New-Item -ItemType Junction -Path "$env:USERPROFILE\.config\opencode\skills\superpowers" -Target "$env:USERPROFILE\.config\opencode\superpowers\skills"

Git Bash 用户

# Git Bash 的 ln 命令会复制文件，需使用 cmd //c
mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills

cmd //c "mklink \"$(cygpath -w ~/.config/opencode/plugins/superpowers.js)\" \"$(cygpath -w ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js)\""

cmd //c "mklink /J \"$(cygpath -w ~/.config/opencode/skills/superpowers)\" \"$(cygpath -w ~/.config/opencode/superpowers/skills)\""

更新 Superpowers

# OpenCode 用户
cd ~/.config/opencode/superpowers
git pull

# Claude Code 用户（如果有安装）
cd ~/.claude/superpowers
git pull

卸载

# OpenCode 用户
rm ~/.config/opencode/plugins/superpowers.js
rm -rf ~/.config/opencode/skills/superpowers

# 可选：删除源码
rm -rf ~/.config/opencode/superpowers

看到 brainstorm、write-plan、execute-plan 这 3 个命令就说明安装成功。

OpenCode 用户

OpenCode 需要手动配置：

# 1. 克隆 Superpowers 仓库
git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers

# 2. 创建目录
mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills

# 3. 创建符号链接（插件）
ln -s ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js ~/.config/opencode/plugins/superpowers.js

# 4. 创建符号链接（技能）
ln -s ~/.config/opencode/superpowers/skills ~/.config/opencode/skills/superpowers

# 5. 重启 OpenCode

# 6. 验证安装
# 在 OpenCode 中问："Do you have superpowers?"

Windows 用户（PowerShell）：

# 1. 克隆仓库
git clone https://github.com/obra/superpowers.git "$env:USERPROFILE\.config\opencode\superpowers"

# 2. 创建目录
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode\plugins"
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode\skills"

# 3. 创建插件符号链接（需要开发者模式或管理员权限）
New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.config\opencode\plugins\superpowers.js" -Target "$env:USERPROFILE\.config\opencode\superpowers\.opencode\plugins\superpowers.js"

# 4. 创建技能目录链接（无需特殊权限）
New-Item -ItemType Junction -Path "$env:USERPROFILE\.config\opencode\skills\superpowers" -Target "$env:USERPROFILE\.config\opencode\superpowers\skills"

# 5. 重启 OpenCode

Codex 用户

# 1. 克隆仓库
git clone https://github.com/obra/superpowers.git ~/.codex/superpowers

# 2. 创建符号链接
mkdir -p ~/.agents/skills
ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers

# 3. 重启 Codex

Windows 用户（PowerShell）：

# 1. 克隆仓库
git clone https://github.com/obra/superpowers.git "$env:USERPROFILE\.codex\superpowers"

# 2. 创建符号链接
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
New-Item -ItemType Junction -Path "$env:USERPROFILE\.agents\skills\superpowers" -Target "$env:USERPROFILE\.codex\superpowers\skills"

# 3. 重启 Codex

更新 Superpowers

# OpenCode 用户
cd ~/.config/opencode/superpowers && git pull

# Codex 用户
cd ~/.codex/superpowers && git pull

卸载

# OpenCode 用户
rm ~/.config/opencode/plugins/superpowers.js
rm -rf ~/.config/opencode/skills/superpowers
# 可选：删除源码
rm -rf ~/.config/opencode/superpowers

# Codex 用户
rm ~/.agents/skills/superpowers
# 可选：删除源码
rm -rf ~/.codex/superpowers

3.4 使用教程

Superpowers 工作原理

Superpowers 提供两种工作方式：

1. Commands（快捷命令）：3 个可用命令

   • brainstorm - 头脑风暴
   • write-plan - 编写计划
   • execute-plan - 执行计划

2. Skills（技能系统）：AI 根据上下文自动加载合适的技能，无需记忆命令名称

推荐使用：自然语言描述需求，让 Superpowers 自动选择最合适的方式。

核心技能列表

技能名称	用途
brainstorming	在任何创造性工作前先头脑风暴，理解需求后再动手
subagent-driven-development	子代理驱动开发：为每个任务派发独立子代理 + 两阶段审查
executing-plans	执行已制定的实施计划
finishing-a-development-branch	完成开发分支：合并、创建 PR 或保留
requesting-code-review	请求代码审查
receiving-code-review	接收并处理代码审查反馈
systematic-debugging	系统化调试：解决 bug 时使用
test-driven-development	TDD 工作流：测试驱动开发
using-git-worktrees	使用 Git Worktree 创建隔离的工作空间
verification-before-completion	完成前验证：每步都要验证
writing-plans	编写实施计划
writing-skills	编写自定义技能

技能触发机制

┌─────────────────────────────────────────────────┐
│              说出你的需求                              │
└─────────────────────────────────────────────────┘
                        │
                        ▼
            ┌────────────────────────┐
            │  分析请求类型          │
            └────────────────────────┘
                        │
         ┌───────────────┼───────────────┐
         ▼               ▼               ▼
    ┌─────────┐    ┌─────────┐    ┌─────────┐
    │ 新想法   │    │有计划    │    │要审查    │
    │头脑风暴  │    │实施任务  │    │代码质量  │
    └─────────┘    └─────────┘    └─────────┘
         │               │               │
         ▼               ▼               ▼
    brainstorming  subagent-driven  requesting

你不需要记住所有技能名称，只需说出你的需求，Superpowers 会自动选择合适的技能。

使用示例：完整工作流

假设你要给电商网站添加一个优惠券功能。

1. 开始头脑风暴

"我想添加用户优惠券功能"

Superpowers 的 brainstorming 技能会自动启动：

• Step 1: 理解项目上下文

  • 读取 CONSTITUTION.md
  • 扫描现有代码库
  • 查看相关文档

• Step 2: 逐个问题澄清

  • "优惠券类型有哪些？百分比折扣还是固定金额？"
  • "优惠券可以叠加使用吗？"
  • "有使用次数限制吗？"

• Step 3: 提出方案

  • "我建议采用以下方案..."
  • "或者另一种方案是..."
  • "我的推荐是...，因为..."

• Step 4: 逐步确认设计

  • 分节展示设计（每节 200-300 字）
  • 每节确认是否正确
  • 不对则回溯修改

• Step 5: 生成设计文档

  • 保存到 docs/plans/YYYY-MM-DD-coupon-design.md
  • 提交到 git

2. 子代理驱动开发

当有明确的实现计划后：

"帮我实施优惠券功能，按照上面的设计文档"

Superpowers 的 subagent-driven-development 技能会启动：

• 提取所有任务到 TodoWrite
• 为每个独立任务派发子代理

🤖 Sub-Agent 1: 实现优惠券模型
   - 编写测试（TDD）
   - 实现代码
   - 提交并自审查

🤖 Sub-Agent 2: 实现认证服务
   - 编写测试（TDD）
   - 实现代码
   - 提交并自审查

🤖 Sub-Agent 3: 实现 API 端点
   - 编写测试（TDD）
   - 实现代码
   - 提交并自审查

🤖 Spec Reviewer: 验证是否符合规格
   - 检查代码是否匹配设计文档

🤖 Code Quality Reviewer: 代码质量审查
   - 检查代码质量、安全性、性能

📋 标记任务完成

3. 请求代码审查

"请帮我审查一下这段代码"

Superpowers 的 requesting-code-review 技能会：

• 分析代码变更
• 从多个角度审查：
  • 代码质量
  • 安全性
  • 性能
  • 测试覆盖率
  • 文档完整性
• 提供具体建议
• 使用友好的、建设性的语气

4. 系统化调试

"用户登录时出现 500 错误"

Superpowers 的 systematic-debugging 技能会：

• 复现问题
• 分析相关代码
• 定位根本原因
• 提出修复方案
• 验证修复

示例 2：子代理驱动开发

当有明确的实现计划后：

# 说出：
"帮我实施优惠券功能，按照上面的设计文档"

# Superpowers 的 subagent-driven-development 技能会启动：
#
# 📋 Step 1: 读取计划，提取任务
# - 读取设计文档
# - 提取所有任务
# - 创建 TodoWrite 任务列表
#
# 🤖 Step 2: 对每个任务执行以下循环：
#
#    a) 派发实现者子代理
#       "实现优惠券模型"
#       子代理独立工作：实现 + 测试 + 提交 + 自审查
#
#    b) 派发规格审查子代理
#       "检查代码是否符合设计文档"
#       如果不符合 -> 返回 a) 修复
#
#    c) 派发代码质量审查子代理
#       "检查代码质量、安全性、性能"
#       如果有问题 -> 返回 a) 修复
#
#    d) 标记任务完成
#
# 🔍 Step 3: 重复直到所有任务完成
#
# ✅ Step 4: 最终整体审查
# 派发最终代码审查子代理
#
# 🌳 Step 5: 完成分支
# 使用 finishing-a-development-branch 技能

示例 3：请求代码审查

# 在提交代码前：
"请帮我审查一下这段代码"

# Superpowers 的 requesting-code-review 技能会：
#
# 1. 分析代码变更
# 2. 从多个角度审查：
#    - 代码质量
#    - 安全性
#    - 性能
#    - 测试覆盖率
#    - 文档完整性
# 3. 提供具体建议
# 4. 使用友好的、建设性的语气

示例 4：使用 Git Worktree 隔离开发

# 在开始新功能开发前：
"我要开发优惠券功能，帮我创建一个隔离的工作空间"

# Superpowers 的 using-git-worktrees 技能会：
#
# 1. 检查当前 git 状态
# 2. 创建新分支：feature/coupon-system
# 3. 创建 Git Worktree: .worktrees/feature-coupon-system/
# 4. 更新项目配置（如果需要）
# 5. 切换到新工作空间
#
# 这样可以：
# - 保持主分支干净
# - 多个功能并行开发互不干扰
# - 快速切换上下文

技能触发机制

Superpowers 的技能会根据上下文自动触发：

┌─────────────────────────────────────────────────────────┐
│              说出你的需求                              │
└─────────────────────────────────────────────────────────┘
                        │
                        ▼
           ┌────────────────────────┐
           │  分析请求类型          │
           └────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        ▼               ▼               ▼
   ┌─────────┐    ┌─────────┐    ┌─────────┐
   │ 新想法   │    │有计划    │    │要审查    │
   │头脑风暴  │    │实施任务  │    │代码质量  │
   └─────────┘    └─────────┘    └─────────┘
        │               │               │
        ▼               ▼               ▼
   brainstorming  subagent-driven  requesting
                  development      code-review

你不需要记住所有技能名称，只需说出你的需求，Superpowers 会自动选择合适的技能。

3.5 自定义技能

你可以创建自己的技能来扩展 Superpowers 的能力。

项目级技能

在项目的 .opencode/skills/ 目录下创建自定义技能：

# 创建技能目录
mkdir -p .opencode/skills/my-custom-skill

# 创建技能文件
cat > .opencode/skills/my-custom-skill/SKILL.md << 'EOF'
---
name: my-custom-skill
description: "Use when [condition] - [what it does]"
---

# My Custom Skill

## When to Use

Use this skill when...

## The Process

1. First step...
2. Second step...
3. Third step...

## Key Principles

- Principle 1
- Principle 2
EOF

个人级技能（OpenCode）

在 ~/.config/opencode/skills/ 目录下创建：

mkdir -p ~/.config/opencode/skills/my-personal-skill

# 创建技能文件
cat > ~/.config/opencode/skills/my-personal-skill/SKILL.md << 'EOF'
---
name: my-personal-skill
description: "My personal coding preferences"
---

# My Personal Coding Preferences

## Code Style
- Use functional components only (no class components)
- Prefer `const` over `let`
- Use named exports, not default exports

## Testing
- Minimum 80% coverage for new code
- Use React Testing Library, not Enzyme
- Mock external APIs in tests

## Git
- Use conventional commits
- Squash before merge
- No force push to main
EOF

技能优先级

Superpowers 会按以下优先级加载技能：

1. 项目级技能 （.opencode/skills/）- 最高优先级
2. 个人级技能 （~/.config/opencode/skills/）- 中优先级
3. Superpowers 技能 （~/.config/opencode/skills/superpowers/）- 默认技能

这意味着你可以：

• 在项目中覆盖默认行为
• 为不同项目定制不同的规则
• 保持个人编码偏好的一致性

实战示例：创建团队技能

假设你的团队有特定的数据库规范：

---
name: team-database-rules
description: "Must use for all database operations"
---

# Team Database Rules

## When to Use

Use this skill when:
- Creating new database models
- Writing SQL queries
- Designing database schemas
- Writing migrations

## The Process

### 1. Schema Design
- Always use snake_case for column names
- Include `created_at` and `updated_at` timestamps
- Add appropriate indexes for foreign keys

### 2. Query Writing
- Use parameterized queries only
- Never concatenate strings for SQL
- Add `EXPLAIN` analysis for complex queries

### 3. Migrations
- Always write rollback migration
- Test migration on staging first
- Back up production schema before deploying

## Key Principles

- Performance first: optimize for query speed
- Safety second: prevent SQL injection
- Maintainability third: clear naming and documentation

将此技能放在 .opencode/skills/team-database-rules/SKILL.md，整个团队都会自动遵守这些规则。

---

四、三者对比分析

4.1 核心对比表

维度	Spec-Kit	OpenSpec	Superpowers
维护方	GitHub 官方	Fission-AI	obra (社区)
Stars	69.1k	23.7k	50k
技术栈	Python (uv)	TypeScript (npm)	Markdown + JavaScript Plugin
核心理念	规格即法律	OPSX 灵活工作流（动作而非阶段）	方法论驱动（技能系统）
文档量	重（宪法+规格+审查）	轻（工件式、可自定义）	轻（技能文件）
学习曲线	较陡	平缓	中等
适用项目	大型/合规要求高	中小型/快速迭代	所有规模
AI 绑定	通用	通用	Claude Code / OpenCode / Codex

4.2 工作流对比

Spec-Kit 工作流（瀑布式）：
┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
│  宪法   │ -> │  规格   │ -> │  实现   │ -> │  审查   │
└─────────┘    └─────────┘    └─────────┘    └─────────┘
   立法          立项          施工          验收

OpenSpec OPSX 工作流（动作式）：
┌──────────────────────────────────────────────────────────────────┐
│              OPSX Flexible Workflow（灵活、可自定义）       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   ┌────────────┐    ┌────────────┐    ┌────────────┐     │
│   │ /opsx:new │ -> │/opsx:continue│ -> │ /opsx:apply │      │
│   └────────────┘    └────────────┘    └────────────┘      │
│         │                │               │              │           │
│         ▼                ▼               ▼              ▼           │
│   /opsx:archive ──────────────────────────────────────────────────> 知识库  │
│                                                              │
└───────────────────────────────────────────────────────────────────────┘

Superpowers 工作流（TDD 螺旋）：
           ┌─────────────────────────────────┐
           │                                 │
           ▼                                 │
    ┌─────────┐    ┌─────────┐    ┌─────────┐
    │  探索   │ -> │写测试   │ -> │  实现   │
    └─────────┘    └─────────┘    └─────────┘
                        │              │
                        ▼              │
                   ┌─────────┐         │
                   │运行测试 │ ────────┘
                   └─────────┘   失败则迭代
                        │
                        ▼ 通过
                   ┌─────────┐
                   │代码审查 │
                   └─────────┘

4.3 适用场景对比

场景	推荐工具	原因
金融/医疗/合规项目	Spec-Kit	需要完整文档链和审计轨迹
初创公司快速迭代	OpenSpec	轻量级，不拖慢开发节奏
日常 Claude Code 使用	Superpowers	即插即用，提升 AI 执行质量
开源项目	Spec-Kit + OpenSpec	需要清晰的贡献规范和变更追踪
个人 Side Project	Superpowers	零配置，立即提升效率
大型团队协作	三者组合	分层治理，各司其职

---

五、三工具协同：最佳实践方案

5.1 协同架构

┌───────────────────────────────────────────────────────────────┐
│                      项目治理层                                │
│                                                               │
│    ┌─────────────────────────────────────────────────────┐   │
│    │              Spec-Kit: CONSTITUTION.md              │   │
│    │                  (项目宪法/全局约束)                  │   │
│    └─────────────────────────────────────────────────────┘   │
│                              │                                │
└──────────────────────────────│────────────────────────────────┘
                               │
                               ▼
┌───────────────────────────────────────────────────────────────┐
│                      规格管理层                                │
│                                                               │
│    ┌─────────────────────────────────────────────────────┐   │
│    │              OpenSpec: OPSX Workflow                │   │
│    │                 (功能规格/变更管理)                   │   │
│    └─────────────────────────────────────────────────────┘   │
│                              │                                │
└──────────────────────────────│────────────────────────────────┘
                               │
                               ▼
┌───────────────────────────────────────────────────────────────┐
│                      执行方法层                                │
│                                                               │
│    ┌─────────────────────────────────────────────────────┐   │
│    │              Superpowers: TDD + Review              │   │
│    │                  (AI 执行方法论)                      │   │
│    └─────────────────────────────────────────────────────┘   │
│                                                               │
└───────────────────────────────────────────────────────────────┘

5.2 实战工作流

假设我们要为一个电商项目添加"优惠券系统"：

Phase 1：立法（Spec-Kit）

确保 CONSTITUTION.md 包含相关约束：

<!-- .spec/CONSTITUTION.md 追加内容 -->

## Coupon System Constraints

### Business Rules
- Coupon codes must be unique and case-insensitive
- Maximum discount cannot exceed order total
- Coupons cannot be combined unless explicitly allowed

### Technical Requirements
- Use Redis for coupon validation caching
- Implement idempotent coupon application
- Log all coupon usage for audit trail

Phase 2：立项（OpenSpec）

创建功能规格：

/opsx:new Implement coupon system

或快速启动：

/opsx:ff Implement coupon system

编写详细规格：

# Proposal: Implement Coupon System

## Summary
Add a complete coupon system with creation, validation, and application.

## Requirements

### API Endpoints
- POST /api/coupons - Create coupon (admin)
- GET /api/coupons/:code - Validate coupon
- POST /api/orders/:id/apply-coupon - Apply to order

### Data Model

interface Coupon {
  id: string;
  code: string;
  type: 'percentage' | 'fixed';
  value: number;
  minOrderAmount?: number;
  maxDiscountAmount?: number;
  usageLimit?: number;
  usedCount: number;
  validFrom: Date;
  validUntil: Date;
  isActive: boolean;
}

### Business Logic
- Validate coupon existence and status
- Check usage limits
- Calculate discount based on type
- Apply to order with audit logging

## Acceptance Criteria
- [ ] Admin can create coupons
- [ ] Users can validate coupon codes
- [ ] Discount calculated correctly
- [ ] Usage limits enforced
- [ ] Audit trail complete

Phase 3：施工（Superpowers）

在 OpenCode / Codex / Claude Code 中执行：

# 告诉 AI：
"请先阅读 .spec/CONSTITUTION.md 了解项目约束，
然后查看 .openspec/active/feature-implement-coupon-system.md 了解功能需求，
最后基于这些文档实施优惠券系统。"

Superpowers 的技能会自动启动：

1. 头脑风暴阶段（brainstorming 技能）

   • 澄清需求细节
   • 确认技术方案
   • 生成实施计划

2. 子代理驱动开发阶段（subagent-driven-development 技能）

   • 为每个任务派发独立子代理
   • 两阶段审查：规格合规性 + 代码质量
   • 持续迭代直到所有任务完成

3. TDD 阶段（每个子代理内部）

   // 先写测试
   describe('CouponService', () => {
     it('should validate active coupon', async () => {
       const coupon = await createTestCoupon({ code: 'TEST20' });
       const result = await couponService.validate('TEST20');
       expect(result.valid).toBe(true);
     });
   
     it('should reject expired coupon', async () => {
       const coupon = await createTestCoupon({ 
         code: 'EXPIRED',
         validUntil: new Date('2020-01-01')
       });
       const result = await couponService.validate('EXPIRED');
       expect(result.valid).toBe(false);
       expect(result.reason).toBe('COUPON_EXPIRED');
     });
   
     // ... 更多测试
   });

4. 实现阶段

   • 实现 CouponService
   • 实现 API 端点
   • 集成 Redis 缓存
   • 添加审计日志

5. 审查阶段

   • 检查是否符合 CONSTITUTION 约束
   • 验证所有测试通过
   • 评估代码质量

Phase 4：归档与验收

实现完成后：

# 归档 OpenSpec
/opsx:archive implement-coupon-system

工件会被移动到知识库供后续参考。

5.3 配置集成

为了让三个工具无缝协作，推荐以下配置：

<!-- ~/.claude/rules/spec-integration.md -->

# Spec Integration Rules

## Before Any Implementation Work

1. ALWAYS read .spec/CONSTITUTION.md first
2. Check openspec/changes/ for current change
3. Reference openspec/changes/archive/ for historical context

## During Implementation

1. Follow Superpowers TDD workflow
2. Ensure all CONSTITUTION constraints are met
3. Update spec artifacts with implementation notes using /opsx:continue

## After Implementation

1. Run Superpowers code review
2. Verify against spec acceptance criteria
3. Archive completed change to OpenSpec using /opsx:archive

---

六、总结与建议

6.1 工具选择指南

你的项目是...

├─ 大型企业项目/合规要求高
│  └─ 推荐：Spec-Kit（主） + Superpowers（执行）
│
├─ 初创公司/快速迭代
│  └─ 推荐：OpenSpec（主） + Superpowers（执行）
│
├─ 个人项目/Side Project
│  └─ 推荐：Superpowers（单独使用即可）
│
├─ 开源项目/社区协作
│  └─ 推荐：Spec-Kit（贡献规范） + OpenSpec（变更追踪）
│
└─ 追求极致/不差钱
   └─ 推荐：三者组合使用

6.2 学习路径建议

1. 入门：先从 Superpowers 开始，立即体验 AI 效率提升
2. 进阶：引入 OpenSpec 管理功能迭代
3. 精通：使用 Spec-Kit 建立完整的规格治理体系

6.3 未来展望

AI 编程工具正在从"代码补全"向"自主工程"演进。Spec-Kit、OpenSpec、Superpowers 代表了三种不同的思路，但最终目标一致：让 AI 成为可靠的工程伙伴，而非需要时刻看管的实习生。

随着这些工具的成熟，我们有理由相信，"规格驱动 + AI 执行"将成为软件开发的新范式。现在开始学习和实践，就是在为未来的开发方式做准备。

参考资源

• Spec-Kit GitHub
• OpenSpec GitHub
• Superpowers GitHub
• GitHub Blog: Spec-Driven Development
• OpenSpec vs Spec Kit 对比
• Superpowers 入门指南
• OpenSpec OPSX 工作流文档
• OpenSpec CLI 文档
• OpenSpec Supported Tools 文档
• Superpowers OpenCode 安装文档

如果这篇文章对你有帮助，欢迎点赞、收藏、关注！有问题欢迎在评论区讨论 🚀