Spec-Kit、OpenSpec、Superpowers 深度对比与最佳实践

AI 编程三剑客：Spec-Kit、OpenSpec、Superpowers 深度对比与最佳实践

本文将深入介绍 GitHub 官方的 Spec-Kit、社区热门的 OpenSpec 以及 Claude Code 神器 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 引入了三个关键文档类型：

scss 复制代码

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

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

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

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

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

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

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

1.3 安装教程

前置条件

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

安装步骤

bash 复制代码

# 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

快速初始化项目

bash 复制代码

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

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

1.4 使用教程

步骤一：编写 CONSTITUTION.md

markdown 复制代码

# 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

markdown 复制代码

# 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
```typescript
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 工具中：

bash 复制代码

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

步骤四：审查与迭代

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

markdown 复制代码

# 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 团队开发的轻量级规格管理工具，专注于"规格增量"（Spec Deltas）的管理。与 Spec-Kit 的"重文档"理念不同，OpenSpec 更强调流动性和迭代性。

GitHub 仓库 ：github.com/Fission-AI/...
Stars：23.7k ⭐
技术栈：TypeScript (npm)
适用 AI：Claude Code、Cursor、Windsurf 等

2.2 核心概念

OpenSpec 的核心是 Spec Delta（规格增量）：

scss 复制代码

┌─────────────────────────────────────────────────────────┐
│                    Active Specs                          │
│              (当前生效的规格变更)                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐                  │
│  │ Delta 1 │  │ Delta 2 │  │ Delta 3 │                  │
│  └─────────┘  └─────────┘  └─────────┘                  │
└─────────────────────────────────────────────────────────┘
                            │
                            │ archive（归档）
                            ▼
┌─────────────────────────────────────────────────────────┐
│                    Archive (Knowledge Base)              │
│                    (历史规格，形成知识库)                 │
└─────────────────────────────────────────────────────────┘

工作流程：

创建 Spec Delta（描述要实现的功能变更）
AI 根据 Delta 进行实现
实现完成后，将 Delta 归档到知识库
知识库成为项目的"记忆"，供后续参考

2.3 安装教程

前置条件

Node.js 18+
npm 或 pnpm

安装步骤

bash 复制代码

# 方式一：全局安装
npm install -g openspec

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

# 方式三：使用 npx 直接运行
npx openspec init

初始化项目

bash 复制代码

# 在项目根目录运行
openspec init

# 这会创建以下结构：
# your-project/
# ├── .openspec/
# │   ├── config.json         # 配置文件
# │   ├── active/             # 当前活跃的规格
# │   └── archive/            # 归档的规格（知识库）

2.4 使用教程

步骤一：创建配置文件

json 复制代码

// .openspec/config.json
{
  "projectName": "my-awesome-app",
  "ai": {
    "provider": "claude",
    "model": "claude-sonnet-4-20250514"
  },
  "templates": {
    "feature": ".openspec/templates/feature.md",
    "bugfix": ".openspec/templates/bugfix.md"
  },
  "archive": {
    "autoArchive": true,
    "archiveOnMerge": true
  }
}

步骤二：创建 Spec Delta

bash 复制代码

# 创建新的功能规格
openspec new feature "Add user profile page"

# 这会生成 .openspec/active/feature-add-user-profile-page.md

生成的模板：

markdown 复制代码

# Spec Delta: Add User Profile Page

## Status: ACTIVE
## Created: 2025-02-12
## Author: developer

---

## Summary
Add a user profile page that displays user information and allows editing.

## Context
Currently users cannot view or edit their profile information after registration.

## Requirements

### Functional
- [ ] Display user avatar, name, email
- [ ] Allow editing name and avatar
- [ ] Show account creation date
- [ ] Show last login time

### Non-Functional
- [ ] Page load time < 2s
- [ ] Mobile responsive
- [ ] WCAG 2.1 AA compliant

## Technical Approach
<!-- AI will fill this based on codebase analysis -->

## Files to Modify
<!-- AI will fill this -->

## Tests Required
<!-- AI will fill this -->

---

## Implementation Notes
<!-- AI fills this during implementation -->

## Review Comments
<!-- Human reviewer adds comments here -->

步骤三：让 AI 执行

在 Claude Code 中：

bash 复制代码

请查看 .openspec/active/ 目录下的活跃规格，实现 "Add User Profile Page" 功能。
实现时参考 .openspec/archive/ 中的历史规格了解项目惯例。

步骤四：归档完成的规格

bash 复制代码

# 实现完成后，归档规格
openspec archive feature-add-user-profile-page

# 这会将文件移动到 .openspec/archive/2025/02/
# 并添加完成时间戳和实现摘要

步骤五：查询知识库

bash 复制代码

# 搜索历史规格
openspec search "authentication"

# 查看某个归档规格的详情
openspec show archive/2025/01/feature-user-auth.md

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

3.1 简介

Superpowers 是由 Jesse Vincent（obra）开发的 Claude Code 增强工具包，专注于执行方法论。它不是文档管理工具，而是一套让 AI 更高效、更可靠地执行编码任务的最佳实践集合。

GitHub 仓库 ：github.com/obra/superp...
Stars：50k ⭐
技术栈：Shell + JavaScript
适用 AI：Claude Code（专属）

3.2 核心概念

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

css 复制代码

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

3.3 安装教程

前置条件

Claude Code CLI 已安装（claude 命令可用）
Bash 或 Zsh shell

安装步骤

bash 复制代码

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

# 2. 运行安装脚本
cd ~/.claude/superpowers
./install.sh

# 3. 验证安装
claude /superpowers-help

安装脚本会自动：

将自定义斜杠命令复制到 ~/.claude/commands/
将配置规则复制到 ~/.claude/rules/
设置必要的环境变量

手动安装（可选）

如果你想更精细地控制安装内容：

bash 复制代码

# 只安装斜杠命令
cp -r ~/.claude/superpowers/commands/* ~/.claude/commands/

# 只安装规则
cp -r ~/.claude/superpowers/rules/* ~/.claude/rules/

# 只安装特定功能
cp ~/.claude/superpowers/commands/tdd.md ~/.claude/commands/

3.4 使用教程

核心斜杠命令

安装后，你可以在 Claude Code 中使用以下命令：

命令	用途
`/tdd`	启动 TDD 工作流
`/implement`	实现功能（自动包含探索、TDD、审查）
`/review`	对当前代码进行审查
`/explore`	探索代码库结构
`/plan`	创建实现计划
`/verify`	验证当前实现状态

使用示例：TDD 工作流

bash 复制代码

# 在 Claude Code 中
claude

# 启动 TDD 流程
> /tdd Add a rate limiter middleware

# Claude 会自动：
# 1. 探索现有中间件结构
# 2. 编写失败的测试用例
# 3. 运行测试确认失败
# 4. 实现最小代码使测试通过
# 5. 重构优化
# 6. 运行代码审查

使用示例：完整实现流程

bash 复制代码

> /implement Add user notification system

# Superpowers 会引导 Claude 执行：
#
# 📍 Phase 1: Exploration
# - 扫描现有通知相关代码
# - 理解数据库模型
# - 查看 API 模式
#
# 📍 Phase 2: Planning
# - 生成实现计划
# - 识别需要修改的文件
# - 评估影响范围
#
# 📍 Phase 3: TDD Implementation
# - 编写测试用例
# - 逐步实现功能
# - 持续验证
#
# 📍 Phase 4: Review
# - 代码质量检查
# - 安全性审查
# - 性能评估

使用示例：子代理委托

对于复杂任务，Superpowers 支持子代理模式：

bash 复制代码

> /implement Add full-text search with Elasticsearch

# Claude 会拆分任务：
#
# 🤖 Sub-Agent 1: Schema Design
#    - 设计 Elasticsearch 索引映射
#    - 定义搜索字段权重
#
# 🤖 Sub-Agent 2: Integration Layer
#    - 实现 ES 客户端封装
#    - 编写数据同步逻辑
#
# 🤖 Sub-Agent 3: API Implementation
#    - 实现搜索 API 端点
#    - 添加分页和过滤
#
# 🤖 Sub-Agent 4: Testing
#    - 编写集成测试
#    - 性能基准测试

3.5 自定义配置

你可以在 ~/.claude/rules/ 中添加自定义规则：

markdown 复制代码

<!-- ~/.claude/rules/my-project.md -->

# Project-Specific Rules

## 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

四、三者对比分析

4.1 核心对比表

维度	Spec-Kit	OpenSpec	Superpowers
维护方	GitHub 官方	Fission-AI	obra (社区)
Stars	69.1k	23.7k	50k
技术栈	Python (uv)	TypeScript (npm)	Shell/JS
核心理念	规格即法律	增量流动	方法论驱动
文档量	重（宪法+规格+审查）	中（Delta 即用即归档）	轻（规则文件）
学习曲线	较陡	平缓	中等
适用项目	大型/合规要求高	中小型/快速迭代	所有规模
AI 绑定	通用	通用	Claude Code 专属

4.2 工作流对比

rust 复制代码

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

OpenSpec 工作流（增量式）：
┌─────────┐    ┌─────────┐    ┌─────────┐
│ Delta 1 │ -> │  实现   │ -> │  归档   │ ─┐
└─────────┘    └─────────┘    └─────────┘  │
                                           │
┌─────────┐    ┌─────────┐    ┌─────────┐  │
│ Delta 2 │ -> │  实现   │ -> │  归档   │ ─┼─> 知识库
└─────────┘    └─────────┘    └─────────┘  │
                                           │
                     ...                   │
                                           ▼
                                    ┌─────────────┐
                                    │ 历史参考    │
                                    └─────────────┘

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

4.3 适用场景对比

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

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

5.1 协同架构

yaml 复制代码

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

5.2 实战工作流

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

Phase 1：立法（Spec-Kit）

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

markdown 复制代码

<!-- .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）

创建功能规格 Delta：

bash 复制代码

openspec new feature "Implement coupon system"

编写详细规格：

markdown 复制代码

# Spec Delta: 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）

在 Claude Code 中执行：

bash 复制代码

claude

> 请先阅读 .spec/CONSTITUTION.md 了解项目约束，
> 然后查看 .openspec/active/feature-implement-coupon-system.md 了解功能需求。

> /implement Coupon system based on the active spec

Superpowers 会自动：

探索阶段
- 分析现有订单系统结构
- 查看 Redis 配置
- 理解审计日志模式

TDD 阶段

typescript 复制代码

// 先写测试
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');
  });

  // ... 更多测试
});

实现阶段
- 实现 CouponService
- 实现 API 端点
- 集成 Redis 缓存
- 添加审计日志
审查阶段
- 检查是否符合 CONSTITUTION 约束
- 验证所有测试通过
- 评估代码质量

Phase 4：归档与验收

实现完成后：

bash 复制代码

# 归档 OpenSpec
openspec archive feature-implement-coupon-system

# 更新 Spec-Kit 审查清单
# Claude 会自动填写 .spec/reviews/coupon-system.md

5.3 配置集成

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

markdown 复制代码

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

# Spec Integration Rules

## Before Implementation
1. ALWAYS read .spec/CONSTITUTION.md first
2. Check .openspec/active/ for current spec
3. Reference .openspec/archive/ for historical context

## During Implementation
1. Follow Superpowers TDD workflow
2. Ensure all CONSTITUTION constraints are met
3. Update spec delta with implementation notes

## After Implementation
1. Run Superpowers code review
2. Verify against spec acceptance criteria
3. Archive completed spec to OpenSpec

六、总结与建议

6.1 工具选择指南

erlang 复制代码

你的项目是...

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

6.2 学习路径建议

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

6.3 未来展望

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

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

参考资源

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

Happy Coding！