前言

最近在使用 Claude Code、Cursor 等 AI 编程工具时，遇到了一个共性问题：上下文丢失。

每次开新会话，AI 就像失忆了一样——之前讨论过的架构决策、设计约束、业务规则，统统忘干净。更头疼的是，当项目变大之后，AI 经常”自作主张”地改坏已有功能，因为它根本不理解系统的全貌。

直到我发现了 OpenSpec，一个轻量级的 Spec 驱动规划框架。它用一种非常优雅的方式解决了这个问题：把规划成果持久化为版本控制的规范文件，让 AI 和人类都能随时回顾系统的设计意图。

这篇文章记录了我在自己的 Hexo 博客项目中，从零开始学习和使用 OpenSpec 的完整过程——包括安装、配置、编写 Spec、生成 Proposal、实施功能、归档变更的每一步。

什么是 OpenSpec？

OpenSpec 是由 Fission AI 开源的一个规范驱动的开发规划框架。它的核心理念很简单：

在写代码之前，先用结构化的 Spec 文件描述”系统应该做什么”；在改代码时，用 Spec Delta 展示”需求发生了什么变化”。

它不是又一个文档工具，而是一个活在代码仓库里的规划层。

与其他方案的对比

安装与配置

安装非常简单，一行命令：

1

npm install -g @fission-ai/openspec@latest

不需要 API Key，不需要 MCP 协议，不绑定任何特定的 AI 工具。装完就能用。

然后在项目根目录初始化：

1

openspec init

这会在项目中创建 openspec/ 目录结构，并自动配置你使用的 AI 工具（比如 Claude Code 的 slash commands）。

支持的 AI 工具

OpenSpec 提供了原生集成，支持的工具非常广泛：

• Claude Code — 我主要使用的工具
• Cursor / GitHub Copilot / Windsurf
• Gemini CLI / Cline / RooCode
• Amazon Q / Qwen Code 等等

每个工具都有对应的 slash command 集成，使用体验一致。

核心概念

OpenSpec 的工作流围绕三个核心概念展开：

1. Specs（规范）

Spec 是对系统某个能力的结构化描述，存放在 openspec/specs/ 目录下：

1
2
3
4
5
6
7
8
9

openspec/specs/
├── auth-login/
│   └── spec.md
├── auth-session/
│   └── spec.md
├── checkout-cart/
│   └── spec.md
└── checkout-payment/
    └── spec.md

每个 Spec 用 SHALL 风格描述需求，用 GIVEN/WHEN/THEN 格式描述场景：

1
2
3
4
5
6
7
8
9
10

## 需求

- 系统 SHALL 支持用户名密码登录
- 登录失败超过 5 次 SHALL 触发账户锁定

## 场景：正常登录

GIVEN 用户已注册且账户未锁定
WHEN 用户提交正确的用户名和密码
THEN 系统返回有效的会话 Token

2. Proposals（提案）

当你需要做改动时，通过 slash command 或 CLI 创建变更：

1

openspec new change add-fulltext-search

然后按模板编写 4 个制品（proposal / specs / design / tasks）。OpenSpec 提供了 openspec instructions 命令来指导你完成每个制品的编写。

3. Spec Deltas（规范差异）

这是 OpenSpec 最精妙的设计。与传统的代码 Diff 不同，Spec Delta 展示的是需求层面的变化：

1
2
3
4
5
6
7

- 会话有效期 SHALL 为 24 小时
+ 会话有效期 SHALL 可配置，默认 24 小时

+ ## 场景：记住我登录
+ GIVEN 用户勾选了"记住我"选项
+ WHEN 用户登录成功
+ THEN 会话有效期 SHALL 延长至 30 天

这让 Code Review 从”看代码改了什么”升级为”看需求变了什么”。

实际使用体验：为博客添加全文搜索

接下来，我用一个真实的例子来演示完整的工作流。目标是给我的 Hexo 博客添加全文搜索功能，支持中文搜索。

第一步：初始化 OpenSpec

1
2
3
4
5

$ openspec init

✔ Setup complete for Claude Code
Created: Claude Code
4 skills and 4 commands in .claude/

初始化后，项目中多了 openspec/specs/、openspec/changes/ 目录，以及 .claude/ 下的 AI 工具集成。

第二步：为现有功能补 Spec

在规划新功能之前，先为博客的现有能力编写 Spec。我创建了两个：

文章管理 Spec (openspec/specs/blog-post/spec.md)：

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

# 文章管理

## 需求

- 系统 SHALL 支持 Markdown 格式的文章编写与发布
- 文章 SHALL 存放在 source/_posts/ 目录下
- 文章 SHALL 包含 YAML Front Matter 元数据
- 系统 SHALL 按日期倒序在首页展示文章列表

## 场景：发布新文章

GIVEN 管理员在 source/_posts/ 目录下创建了新的 .md 文件
AND 文件包含有效的 YAML Front Matter
WHEN 执行 pnpm build 构建
THEN 新文章 SHALL 出现在首页文章列表中

主题部署 Spec (openspec/specs/site-theme/spec.md)：

1
2
3
4
5
6

# 站点主题与部署

## 需求

- 站点 SHALL 使用暗色主题（背景 #0a0e17，强调色 #00f0ff）
- 站点 SHALL 通过 GitHub Actions 自动构建和部署

第三步：创建变更和 Proposal

1
2
3

$ openspec new change add-fulltext-search

✔ Created change 'add-fulltext-search' at openspec/changes/add-fulltext-search/

然后用 openspec instructions 获取每个制品的编写指导：

1
2
3
4

$ openspec instructions proposal --change add-fulltext-search
$ openspec instructions specs --change add-fulltext-search
$ openspec instructions design --change add-fulltext-search
$ openspec instructions tasks --change add-fulltext-search

每个命令都会输出详细的模板和要求。按照指导，我依次编写了 4 个制品：

proposal.md — 为什么要做这个变更

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

## Why

博客目前没有搜索功能，读者只能通过浏览首页或按标签/分类筛选来查找文章。
随着文章数量增长，找到特定内容会越来越困难。

## What Changes

- 新增基于 hexo-generator-searchdb 的本地全文搜索功能
- 在导航栏集成搜索入口，替换现有的 Google 搜索跳转
- 支持中文分词，确保中文文章可被正确搜索

## Capabilities

### New Capabilities
- `site-search`: 博客站内全文搜索功能

specs/site-search/spec.md — 搜索功能的详细需求

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

## ADDED Requirements

### Requirement: 全文搜索索引生成
系统 SHALL 在构建时自动生成全文搜索索引文件。

#### Scenario: 构建时生成搜索索引
- WHEN 执行 pnpm build 构建站点
- THEN 系统 SHALL 在输出目录中生成 JSON 格式的搜索索引文件

#### Scenario: 中文内容索引
- WHEN 文章包含中文内容
- THEN 搜索"AI" SHALL 匹配包含"AI探索"的文章

### Requirement: 搜索 UI 组件
站点 SHALL 提供一个内嵌的搜索 UI 组件。

#### Scenario: 实时搜索
- WHEN 用户在搜索框中输入关键词
- THEN 系统 SHALL 实时展示匹配的文章列表

design.md — 技术方案

1
2
3
4
5
6
7
8
9
10

## Decisions

### 1. 搜索索引方案：hexo-generator-searchdb
选择理由：Hexo 生态中最成熟的搜索索引生成插件，支持 JSON 格式输出。

### 2. 搜索 UI：自定义实现
选择理由：复用导航栏搜索图标，自定义 UI 适配暗色主题。

### 3. 中文搜索策略：子串匹配
选择理由：中文不需要严格分词，indexOf 子串匹配已能覆盖大部分场景。

tasks.md — 实施任务清单

1
2
3
4
5
6
7
8
9
10
11
12

## 1. 依赖安装与配置
- [ ] 1.1 安装 hexo-generator-searchdb 依赖
- [ ] 1.2 在 _config.yml 中添加搜索索引配置

## 2. 搜索 UI 组件
- [ ] 2.1 创建搜索 UI 的 CSS 样式
- [ ] 2.2 创建搜索 UI 的 JavaScript 逻辑
- [ ] 2.3 将搜索 CSS 和 JS 注入到 inject 脚本中

## 3. 验证与测试
- [ ] 4.1 执行 pnpm build 验证搜索索引文件生成
- [ ] 4.2 本地预览验证搜索功能

第四步：验证 Proposal

1
2
3

$ openspec validate add-fulltext-search

Change 'add-fulltext-search' is valid

1
2
3
4
5
6
7
8
9
10
11
12

$ openspec status --change add-fulltext-search

Change: add-fulltext-search
Schema: spec-driven
Progress: 4/4 artifacts complete

[x] proposal
[x] design
[x] specs
[x] tasks

All artifacts complete!

第五步：按任务实施

有了清晰的任务清单，实施过程变得非常顺畅。每个任务都有明确的验收标准（来自 Spec），AI 在执行时不会偏离方向。

实际实施过程：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 1. 安装依赖
pnpm add hexo-generator-searchdb

# 2. 在 _config.yml 中添加搜索配置
# search:
#   path: search.json
#   field: post
#   content: true
#   format: striptags

# 3. 在 inject-custom.js 中添加搜索 UI 的 CSS 和 JS

# 4. 构建验证
$ pnpm build

INFO  Generated: search.json
INFO  20 files generated in 312 ms
[inject] Custom styles, animations and search UI injected.

构建成功，search.json 索引文件自动生成，包含了所有文章的标题、内容、标签和分类。

第六步：归档变更

功能实施完成、所有任务勾选后，用 openspec archive 归档：

1
2
3
4
5
6
7
8
9
10
11

$ openspec archive add-fulltext-search -y

Task status: ✓ Complete

Specs to update:
  site-search: create
Applying changes to openspec/specs/site-search/spec.md:
  + 3 added
Totals: + 3, ~ 0, - 0, → 0
Specs updated successfully.
Change 'add-fulltext-search' archived as '2026-05-11-add-fulltext-search'.

归档后，site-search 的 Spec 被合并到了主 Spec 目录 openspec/specs/site-search/spec.md，变更记录移到了 openspec/changes/archive/ 下。

最终的项目结构：

1
2
3
4
5
6
7
8
9
10
11
12

openspec/
├── specs/
│   ├── blog-post/spec.md       ← 文章管理 Spec
│   ├── site-search/spec.md     ← 搜索功能 Spec（归档后生成）
│   └── site-theme/spec.md      ← 主题部署 Spec
└── changes/
    └── archive/
        └── 2026-05-11-add-fulltext-search/
            ├── proposal.md
            ├── design.md
            ├── tasks.md
            └── specs/site-search/spec.md

为什么 Spec 比 Prompt 更重要？

用了 OpenSpec 之后，我最大的感受是：好的规划比好的 Prompt 更重要。

Prompt 的局限

1
2
3

❌ "帮我加个搜索功能"
❌ "优化一下性能"
❌ "重构认证模块"

这些 Prompt 缺乏上下文，AI 只能猜测你的意图。

Spec 的优势

有了 Spec，AI 能看到：

• 系统当前的行为是什么（现有 Spec）
• 你想改成什么（Spec Delta）
• 需要满足什么约束（需求和场景）

这比任何精心设计的 Prompt 都有效。

OpenSpec CLI 速查

在实际使用中，这些命令最常用：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# 初始化
openspec init

# 创建变更
openspec new change <name>

# 获取制品编写指导
openspec instructions proposal --change <name>
openspec instructions specs --change <name>
openspec instructions design --change <name>
openspec instructions tasks --change <name>

# 验证和查看状态
openspec validate <name>
openspec status --change <name>

# 归档完成的变更
openspec archive <name> -y

# 查看所有 Spec 和变更
openspec list --specs
openspec list

适用场景

OpenSpec 特别适合以下场景：

1. 已有项目的功能迭代

“Brownfield development” — 这是 OpenSpec 的设计重心。对于成熟项目，理解现有系统比从零开始更难。

2. 多人协作

Spec 存在 Git 里，团队成员通过 PR 审查 Spec 变更，确保大家对需求的理解一致。

3. 跨会话的长期规划

大型功能往往需要多次会话才能完成。Spec 让每次会话都能接续上次的进度。

4. AI 编程的质量控制

Spec 为 AI 提供了明确的约束，减少”自作主张”的风险。

注意事项

使用 OpenSpec 也有一些需要注意的地方：

1. 不要过度设计 — OpenSpec 强调”够用就好”，不要把 Spec 写成瀑布式的需求文档
2. Spec 需要维护 — 代码改了但 Spec 没更新，比没有 Spec 更糟糕
3. 增量采用 — 不需要一次性为整个项目补 Spec，按需创建即可
4. AI 不是万能的 — “Specs only work if you actually read them, think through them, and engage with them”

总结

OpenSpec 给我的 AI 编程工作流带来了质的提升：

• 上下文持久化 — 不再依赖会话记忆
• 意图可追溯 — Spec Delta 让变更意图清晰可见
• AI 协作更精准 — 有了 Spec 约束，AI 的输出质量显著提高
• 团队对齐 — Spec 成为活的文档，而不是写完就扔的 PRD

如果你也在用 AI 工具做开发，强烈推荐试试 OpenSpec。它不是银弹，但确实解决了一个真实的痛点：让 AI 理解你的系统，而不只是你的 Prompt。

参考资料

• OpenSpec 官网
• OpenSpec GitHub 仓库
• OpenSpec Discord 社区

开篇

你好，欢迎来到我的博客！这是一个记录 AI 使用与学习过程的个人空间。

最近人工智能技术飞速发展，从 ChatGPT 到 Claude，从 Midjourney 到 Stable Diffusion，各种 AI 工具正在深刻改变我们的工作和生活方式。作为一个 AI 爱好者，我决定建立这个博客，记录我在探索 AI 世界中的所见所闻、所思所想。

为什么写这个博客？

1. 记录学习过程 — 将零散的知识系统化，写作是最好的学习方式
2. 分享实践经验 — 希望我的使用心得能帮助到同样在探索 AI 的朋友
3. 建立知识库 — 方便日后回顾和查阅

这个博客会写什么？

• AI 工具的使用教程和技巧
• Prompt Engineering 的学习笔记
• AI 在实际项目中的应用案例
• 技术思考和个人见解

关于建站

这个博客使用 Hexo 搭建，部署在 GitHub Pages 上。选择 Hexo 的原因是它简单、快速，而且有丰富的主题和插件支持。

1
2
3
4
5
6
7
8

# 安装 Hexo
npm install -g hexo-cli

# 创建新博客
hexo init my-blog

# 本地预览
hexo server

结语

技术的世界永远充满惊喜，让我们一起在 AI 的浪潮中学习、成长。

感谢你的阅读，我们下篇文章再见！