OpenSpec 完全上手指南：AI 时代如何用规范驱动开发

Spec-Driven Development —— 先写规范，再写代码

---

一、什么是 OpenSpec？

OpenSpec 是一个专为 AI 编程场景设计的规范驱动开发框架。核心理念是：先想清楚要做什么（Spec），再让 AI 去实现（Code）。

大模型每次对话都是从零开始的，缺少对项目上下文和需求的持续理解。OpenSpec 通过一套结构化的规范文件，把需求、设计、验收条件明确记录下来，让 AI 每次执行都有据可依，避免反复试错。

---

二、四个核心 Skill

OpenSpec 提供四个 Skill，覆盖完整的开发周期：

Skill	别名	用途
openspec-propose	/opsx:propose	提出新变更，生成 proposal / design / specs / tasks
openspec-explore	/opsx:explore	探索模式，理清需求和设计思路
openspec-apply-change	/opsx:apply	按 tasks.md 逐步实现
openspec-archive-change	/opsx:archive	完成后归档，合并规范

---

三、完整工作流

以下通过一个天气查询 CLI 工具的案例，展示 OpenSpec 的完整流程。

第一步：提出变更

/opsx:propose "创建一个简单的天气查询命令行工具"

OpenSpec 会生成四个文件：

proposal.md —— 回答 Why / What / Impact

## Why
在终端快速查看天气，不需要打开浏览器或手机。


## What Changes
- 新增 weather-cli 命令行工具
- 支持 weather <城市名> 和 weather --help

## Impact
- 新增文件：weather.py
- 无外部依赖（仅用 Python 标准库）

specs/city-weather-query/spec.md —— 逐条描述功能需求

## Requirement: 城市天气查询
系统应接受城市名并返回当前天气。

Scenario: 有效城市名
- WHEN 运行 weather London
- THEN 显示伦敦的天气

Scenario: 含空格的城市名
- WHEN 运行 weather "New York"
- THEN 正确显示纽约天气

Scenario: 无效城市名
- WHEN 运行 weather xyzxyzxyz
- THEN 显示友好错误信息

每条需求附带验收场景（Scenario），AI 严格按照这些场景来编码和测试。

design.md —— 记录架构决策

## Context
零依赖的命令行天气查询工具。

## Goals / Non-Goals
- Goals: 城市名查询、--help、错误处理、零依赖
- Non-Goals: 自动定位、GUI、持久化

## Decisions
- 使用 wttr.in API（免费、无需 API Key）
- 只用 Python 标准库
- 纯文本输出

## Risks / Trade-offs
- [API 可能被限流] → 添加超时处理
- [城市名含空格] → 支持引号包裹

tasks.md —— 可执行的检查清单

## 1. Core Implementation
- [ ] 1.1 实现天气查询函数
- [ ] 1.2 添加 CLI 参数解析
- [ ] 1.3 添加错误处理

## 2. Testing
- [ ] 2.1 测试有效城市名
- [ ] 2.2 测试多词城市名
- [ ] 2.3 测试错误处理

第二步：审阅

生成完成后，人工审阅这些文件：

• 需求是否完整、准确？
• 设计决策是否合理？
• 边界情况是否覆盖？

在这个阶段修改成本最低——改几行 markdown 比改代码快得多。

第三步：执行变更

/opsx:apply weather-cli

OpenSpec 按 tasks.md 逐项推进：

Working on task 1/6: 实现天气查询函数   ✓
Working on task 2/6: 添加 CLI 参数解析   ✓
Working on task 3/6: 添加错误处理       ✓
Working on task 4/6: 测试有效城市名     ✓
...

最终产出：

# weather.py
def fetch_weather(city: str) -> str:
    url = f"https://wttr.in/{quote(city)}?format=%C+%t&lang=zh"
    ...

def main():
    parser = argparse.ArgumentParser(description="命令行天气查询工具")
    parser.add_argument("city", nargs="?", help="城市名称")
    ...

# test_weather.py
class TestFetchWeather(unittest.TestCase):
    def test_fetch_valid_city(self): ...
    def test_fetch_multi_word_city(self): ...
    def test_network_error(self): ...

第四步：归档

/opsx:archive weather-cli

归档后，specs 合并到主规范目录，变更标记为已完成。

---

四、高级技巧

1. 拆解复杂需求

大型功能不要一次 propose 全部。拆分成多个独立变更，每个变更独立审阅、独立实现：

/opsx:propose "用户认证模块"
/opsx:propose "数据模型层"
/opsx:propose "API 路由层"

2. 需求不清晰时先用 Explore

不确定要做什么时，进入 explore 模式，让 AI 帮你理清思路：

/opsx:explore
→ "我在做一个笔记应用，但不确定选本地存储还是云端同步..."
→ （AI 引导你梳理关键决策点）
→ 思路清晰后退出
/opsx:propose "本地 Markdown 笔记应用"

3. 迭代中修正

实现过程中发现设计问题，改 spec 而不是硬编码绕过去：

执行到一半发现 API 设计不合理
→ 修改 spec 文件
→ 继续 apply，AI 按新 spec 调整代码

4. 多变更并行管理

openspec list
→ weather-cli (in-progress) 6/6
→ add-todo-api (in-progress) 3/8
→ md-notes (draft)

openspec status --change "add-todo-api"  # 查看具体进度

---

总结

OpenSpec 把 AI 编程从"猜需求"转变为"按规范执行"。

阶段	工具	产出
理清需求	/opsx:explore	明确的设计方向
定义功能	/opsx:propose	proposal + specs + design + tasks
确认设计	人工审阅	确认过的规范文件
逐步实现	/opsx:apply	通过测试的代码
完成归档	/opsx:archive	已合并的规范

最后一条建议：无论是否使用 OpenSpec，"先写规范再写代码"这个习惯本身就值得养成。在 AI 编程时代，想清楚再动手的效率远高于边做边改。