AI 编程铁三角：02 OpenSpec 入门

在第一行代码编写之前，先与 AI 对齐需求

一个真实的故事

上周，我的朋友小王兴冲冲地告诉我：

“我用 Claude Code 花 2 小时实现了一个用户权限系统，太强了！”

第二天，他沮丧地来找我：

“产品经理说这不是他要的…他要的是角色权限，我做成了用户权限。
现在要重构，相当于白干了。”

问题出在哪？

AI 理解错了需求，小王也没有及时纠正，结果一路狂奔。

这就是 AI 编程最常见的问题：理解偏差。

---

理解偏差的三种形态

形态一：范围偏差

你：加个登录功能
AI 理解成：OAuth + 本地登录 + 手机验证码 + 找回密码 + 记住我
实际需要：简单的用户名密码登录

形态二：技术路线偏差

你：存储用户数据
AI 选择：MongoDB + Mongoose
项目规范：PostgreSQL + Prisma

形态三：优先级偏差

你：优化性能
AI 开始：重构整个数据层
你期望：先优化一个慢查询

问题的本质：需求只存在于"对话"中，没有固化成"规范"。

OpenSpec 就是为了解决这个问题。

---

OpenSpec 是什么

一句话定义：

OpenSpec = AI 原生的规范驱动开发系统

核心理念

传统开发：需求文档 → 人工阅读 → 写代码
AI 开发（无规范）：对话 → AI 理解（可能错） → 写代码
AI 开发（有OpenSpec）：对话 → 规范文档 → AI 按规范 → 写代码

三个关键特性

1. 轻量级 —— 不增加负担

OpenSpec 不是传统的那种"先写100页需求文档再开发"的瀑布模式。

它的核心理念是：

→ fluid not rigid      # 流动而非僵化
→ iterative not waterfall   # 迭代而非瀑布
→ easy not complex     # 简单而非复杂

2. 结构化 —— 信息有处安放

每个需求变更都有一个独立的文件夹：

openspec/
└── changes/
    └── add-user-permissions/
        ├── proposal.md   # 为什么要做，做什么
        ├── specs/        # 详细需求规范
        ├── design.md     # 技术方案
        └── tasks.md      # 实施清单

3. 工具无关 —— 支持主流AI助手

OpenSpec 支持 25+ AI 编码工具：

• Claude Code
• Cursor
• Windsurf
• GitHub Copilot
• Codex
• OpenCode
• …

---

三步核心工作流

OpenSpec 的核心就三个命令：

/opsx:propose → /opsx:apply → /opsx:archive

第一步：propose（创建规范）

你：/opsx:propose add-login-feature

AI：创建 openspec/changes/add-login-feature/
    ✓ proposal.md — 为什么要做，改什么
    ✓ specs/      — 需求细节
    ✓ design.md   — 技术方案
    ✓ tasks.md    — 实施清单
    
    请确认设计无误后，输入 /opsx:apply 开始实施

关键点：AI 先生成规范，你确认后再执行。

第二步：apply（执行实施）

你：/opsx:apply

AI：开始执行任务清单...
    ✓ 1.1 创建 User 模型
    ✓ 1.2 实现登录接口
    ✓ 2.1 添加密码加密
    ✓ 2.2 实现会话管理
    ✓ 3.1 编写单元测试
    ✓ 3.2 添加API文档
    
    所有任务完成！

关键点：按规范执行，不是按"对话理解"执行。

第三步：archive（归档变更）

你：/opsx:archive

AI：归档到 openspec/changes/archive/2026-05-02-add-login/
    更新主规范文档
    准备下一个变更

关键点：变更完成，规范更新，形成历史记录。

---

快速上手：10 分钟安装

安装 CLI

# 需要Node.js 20.19.0+
npm install -g @fission-ai/openspec@latest

验证安装

openspec --version
# 应该显示版本号

openspec status
# 显示当前项目的 OpenSpec 状态

---

实战演示：第一个 OpenSpec 变更

场景：为 hot-trends 添加知乎热榜数据源

让我们用 AI 编程铁三角：01 Superpowers 入门 的案例，继续添加一个变更需求，体验完整流程。

初始化项目

cd hot-trends
openspec init

这会在项目中创建：

openspec/
├── .openspec/      # 配置文件
├── changes/        # 变更目录
└── specs/          # 主规范文档

第一步：创建变更提案

输入：

/opsx:propose add-zhihu-fetcher

AI 生成 proposal.md：

# Proposal: add-zhihu-fetcher

## Why（为什么做）

用户需要聚合多个平台的热门文章，目前 hot-trends 只支持掘金，缺少知乎热榜。

## What（做什么）

1. 新增知乎热榜数据抓取器
2. 支持按标签过滤（前端/后端/AI等）
3. 统一输出格式，与掘金数据源保持一致

## Scope（范围边界）

### In Scope
- 知乎热榜 Top 20 抓取
- 按领域过滤（前端/后端/AI/全栈）
- 统一的数据模型（与掘金数据源一致）

### Out of Scope
- 知乎搜索功能（后续迭代）
- 知乎评论抓取（本次不做）
- 多数据源聚合展示（后续迭代）

AI 生成 specs/：

specs/
├── zhihu-api.md      # 知乎 API 规范
├── filter-rules.md   # 过滤规则
└── data-model.md     # 统一数据模型

spec示例：

# Zhihu API Specification

## API Endpoint
- URL: https://www.zhihu.com/api/v3/feed/topstory/hot-lists/total
- Method: GET
- Headers: User-Agent required

## Response Fields
- target.id: string（内容 ID）
- target.title: string（标题）
- target.vote_count: number（点赞数）
- target.topic.name: string（领域标签）

## Error Handling
- 超时：5 秒
- 重试：最多 3 次
- 限流：指数退避

AI 生成 design.md：

# Technical Design

## Data Flow

知乎 API → ZhihuFetcher → Filter → Output（复用已有）

## Components

| Component | File | Responsibility |
|-----------|------|---------------|
| Fetcher | src/fetchers/zhihu.ts | API 调用 |
| Filter | src/filters/article-filter.ts | 复用已有 |
| Output | src/output/table.ts | 复用已有 |

## Data Model

```typescript
interface ArticleItem {
  id: string
  title: string
  diggCount: number
  tags: string[]
  url: string
  source: 'juejin' | 'zhihu'
}

API Design

Source	Endpoint	Method
知乎热榜	https://www.zhihu.com/api/v3/feed/topstory/hot-lists/total	GET

**AI 生成 tasks.md**：

```markdown
# Implementation Tasks

## 1. 数据模型
- [ ] 1.1 扩展 ArticleItem 接口（添加 source 字段）

## 2. 数据层
- [ ] 2.1 实现 src/fetchers/zhihu.ts（fetchZhihuHot）
- [ ] 2.2 编写 tests/fetchers/zhihu.test.ts

## 3. 过滤层
- [ ] 3.1 扩展 filterByTag 支持多数据源
- [ ] 3.2 编写过滤测试

## 4. CLI 入口
- [ ] 4.1 添加 --source 参数支持选择数据源
- [ ] 4.2 添加 --zhihu 快捷参数

## 5. 测试
- [ ] 5.1 集成测试：多数据源抓取

---

第二步：确认规范

你的任务：仔细阅读生成的规范，确认无误。

如果发现问题：

你：zhihu-api.md 里缺少 User-Agent 的具体格式说明

AI：已更新 specs/zhihu-api.md：
    添加说明：
    - User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36

关键点：这步很重要！规范错了，后面代码全错。

---

第三步：执行实施

确认规范后：

你：/opsx:apply

AI：开始执行任务清单...

    [1/5] 扩展 ArticleItem 接口...
          ✓ Updated: src/types/article.ts
    
    [2/5] 实现 fetchZhihuHot()...
          ✓ Created: src/fetchers/zhihu.ts
    
    [3/5] 编写 zhihu fetcher 测试...
          ✓ Created: tests/fetchers/zhihu.test.ts
    
    [4/5] 扩展过滤逻辑...
          ✓ Updated: src/filters/article-filter.ts
    
    [5/5] 集成测试...
          ✓ All tests passed
    
    所有任务完成！查看报告？

关键点：AI 按 tasks.md 执行，每步都有验证。

---

第四步：归档变更

你：/opsx:archive

AI：归档变更...
    ✓ 移动到 openspec/changes/archive/2026-05-03-add-zhihu/
    ✓ 更新 openspec/specs/main.md

    变更已归档，项目规范已更新。

---

OpenSpec vs 传统方式对比

对比场景：实现一个新功能

维度	传统方式	对话式AI	OpenSpec
需求记录	需求文档（可能过时）	对话历史（难追溯）	规范文档（始终最新）
需求确认	人工评审	边写边改	先确认再执行
变更追溯	依赖Git commit	难以追溯	每个变更有完整记录
团队协作	文档共享	对话不共享	规范文档是共享的
范围控制	靠人工把控	容易跑偏	规范即边界

---

核心概念详解

1. Change（变更）

每个功能需求都是一个 Change。

openspec/changes/
├── add-zhihu-fetcher/     # 添加知乎数据源
├── add-juejin-fetcher/   # 掘金数据源（已有）
└── optimize-filter/       # 优化过滤逻辑

特点：

• 独立的工作空间
• 完整的生命周期
• 可并行开发

2. Artifacts（产物）

每个 Change 包含四个产物：

产物	作用	更新时机
proposal.md	阐述意图和范围	变更开始时
specs/	详细需求规范	需求明确时
design.md	技术方案	设计确认时
tasks.md	实施清单	执行前

3. Delta Specs（增量规范）

OpenSpec 支持增量更新：

# 第一次变更（add-juejin-fetcher）
specs/
└── data-model.md    # 新增

# 第二次变更（add-zhihu-fetcher）
specs/
├── data-model.md    # 已有（扩展 source 字段）
└── zhihu-api.md    # 新增（Delta）

Delta 标记：

# data-model.spec.md

## ADDED
- source 字段标识数据来源

## MODIFIED
- ArticleItem 接口新增可选字段

---

高级用法

多人协作

# 开发者A创建变更
/opsx:propose add-feature-a

# 开发者B创建另一个变更（不冲突）
/opsx:propose add-feature-b

# 两人并行开发
/opsx:apply  # 各自执行各自的变更

存量项目迁移

/opsx:onboard

AI：分析现有项目结构...
    创建初始规范...
    生成项目概览...
    
    已创建 openspec/specs/overview.md
    项目已接入 OpenSpec！

自定义模板

# 使用自定义模板
openspec config template ./my-templates/

---

常见问题

Q1：规范写太细，会不会太慢？

答案：不会。

OpenSpec 的理念是 “刚好够用”：

太粗：只有标题 → AI 还是自己猜
太细：每个字段都定义 → 文档负担重
刚好：核心需求 + 关键约束 → AI 能理解，人也不用写太多

建议粒度：

• proposal.md：200-500字
• specs/：每个文件 100-300字
• design.md：200-400字
• tasks.md：每个任务一行描述

Q2：执行中发现规范错了怎么办？

答案：随时可以修改。

你：发现知乎 API 需要添加 cookie 处理

AI：更新规范...
    ✓ 更新 design.md：添加 cookie 处理方案
    ✓ 更新 tasks.md：添加 cookie 获取任务

    是否继续执行？

Q3：和 Superpowers 的关系？

Superpowers = 流程约束（怎么开发）
OpenSpec = 需求约束（开发什么）

两者结合：

OpenSpec 创建规范 → Superpowers 按流程执行

我们会在后面的"铁三角"篇章详细讲解这两者的协同。

---

下一步

现在的你已经学会了 OpenSpec 的基本使用，知道它如何让 AI 在写代码前先对齐需求。

但 OpenSpec 只是"铁三角"的第二角。完整的 AI 编程工程化体系还需要：

• 标准化的执行流程 → Superpowers ✅ 已学
• 规范化的需求定义 → OpenSpec ✅ 已学
• 系统化的行为约束 → Harness Engineering（下一篇）

下一篇，我们来讲 Harness Engineering：给 AI 套上缰绳。

---

扩展阅读

• OpenSpec 官网
• OpenSpecGitHub
• OpenSpec 文档
• OpenSpec Discord