OpenSpec 使用心得

一、引言

如果在 2025 年，你还没有在工作中借助 AI，要么你的水平已经超越 AI，要么你就是被 AI 代替的部分。大多数人都不是前者，也不愿成为后者。如何高效、可靠地利用 AI，是每位开发者的必修课。

我个人的探索大致经历了以下几个阶段，从最初的简单补全，到如今的规范驱动开发——OpenSpec。

二、AI 工具演进阶段

1. 洪荒时代：AI 仅作“补全” • 编辑器里集成 Copilot 插件，或者 ChatGPT 网页窗口复制粘贴，AI 只能做最基础的代码补全，效率提升有限。

2. 集成时代：对话式编辑 • Cursor 等工具将聊天窗口直接搬进 IDE，上下文无缝传递，减少复制粘贴的步骤。

3. 增强时代：MCP 协议崛起 • Model Context Protocol 赋予 AI Agent 文件读写、命令执行、API 调用能力，自动化水平大幅跃升。

4. 智能时代：自主驱动 • AI Agent 能理解复杂任务，分解步骤，自主调用工具链完成工作，不再是简单的问答助手，而是智能协作伙伴。

三、现有困境与解决方案

尽管 AI 功能越来越强，但在团队协作中，仍面临几大痛点：

• 上下文串台：长对话中不同任务相互干扰
• 信息丢失：超出上下文窗口后，需反复重新说明
• 难以复用：项目约定无法在新会话中继承

过去，我常让 AI Agent 先输出思路再动手，但每次改动都像黑盒测试，改错了只能重来。

这也是大家遇到的问题，所以最近出现了一系列工具：spec-kit、OpenSpec 等。

OpenSpec 核心思路

1. “每次改动都是一个提案” • 在动手之前，先形成结构化的 proposal.md，明确 Why / What / How / Impact，我们 Review 通过后再执行。

2. 规范驱动、约定可持久化 • 所有决策、设计、验收标准都以文件形式保存在仓库里，新工具或新同事都能快速“秒懂”项目规范。

通过将项目规范、架构决策、功能需求以结构化文档记录，OpenSpec 保证了上下文一致性、变更可追溯，也让 AI Agent 在任何时刻都能准确执行。

四、角色转变

• 之前：在微观层面指挥 AI Agent “写这段代码”“改那个函数”
• 现在：从宏观角度当“产品经理”或“团队 Leader”
  1. 我来讲需求
  2. AI Agent 起草提案
  3. 我 Review 并反馈
  4. AI Agent 修改提案
  5. 我确认后，AI Agent 执行代码落地

这样一来，我们从指令层的操作者，变成了规范层的把关者，放权给 AI Agent 干更多“脏活累活”。

五、OpenSpec 使用案例

下面以“撰写本篇文章”为例，演示 OpenSpec 的完整流程。

1. 安装 OpenSpec

# 检查 Node.js 版本（需要 >= 20.19.0）
node --version
# v24.11.0

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

2. 初始化 OpenSpec

cd my-project
openspec init

• 选择支持的 AI 工具（如 Claude Code、Cursor 等）
• 自动生成 openspec/project.md、openspec/AGENTS.md、openspec/specs/、openspec/changes/ 等目录结构

验证初始化成功，只需要执行：

openspec list
# No active changes found.

然后让 AI Agent 帮你完善项目背景：

Populate your project context:
"Please read openspec/project.md and help me fill it out with details about my project, tech stack, and conventions"

3. 创建提案

向 AI Agent 提需求：

“在 src/content/blog 下新建《OpenSpec 使用心得》文章，包含：

1. 引言：为何要拥抱 AI
2. AI 演进阶段
3. 现有困境与解决方案
4. OpenSpec 流程
5. 个人实践心得”

AI Agent 自动生成 openspec/changes/complete-openspec-article/proposal.md、tasks.md、相应 specs/。

proposal.md 包含了提案的核心信息：

## Why

现有的 `src/content/blog/2025-11-04-openspec.md` 文章内容不完整，
需要补充完整的内容以完成一篇关于 OpenSpec 使用心得的博客文章。

## What Changes

- 完成博客文章 `src/content/blog/2025-11-04-openspec.md` 的写作
- **保留现有内容**：不删除已有的引言、演进阶段和困境解决方案部分
- **文章要求**：
  - 确保内容准确性
  - AI 工具演进阶段需准确描述
  - 精简整篇文章篇幅...
  - 统一名词使用...

## Impact

- 受影响文件：`src/content/blog/2025-11-04-openspec.md`

tasks.md 列出了详细的实施任务清单：

## 1. 内容创作

- [ ] 1.1 完成第一部分：引言：拥抱 AI 工具
- [ ] 1.2 完成第二部分：AI 工具的演进阶段
  - [ ] 1.2.1 以段落形式描述四个阶段...
- [ ] 1.3 完成第三部分：现有困境与解决方案
- [ ] 1.4 完成第四部分：OpenSpec 的特点与使用流程
  - [ ] 1.4.1 准确介绍 spec-kit 和 OpenSpec 工具...
  - [ ] 1.4.5 使用案例：完成这篇文章提案本身...

specs/blog-content/spec.md 定义了规范要求：

## ADDED Requirements

### Requirement: OpenSpec 使用心得博客文章

博客系统 SHALL 包含一篇完整的关于 OpenSpec 使用心得的文章...

#### Scenario: 文章内容完整性

- **WHEN** 用户访问博客文章页面
- **THEN** 文章应包含所有五个主要部分...

#### Scenario: 文章精炼度

- **WHEN** 文章完成
- **THEN** 应遵循以下原则：
  - 去除所有冗余和重复内容...
  - 使用案例部分需要详细描述...

4. 反复打磨

我在对话中提出细化或优化建议，AI Agent 即刻更新提案，直到内容满足需求，再进入“实施”阶段。

更新提案，介绍完现有的困境，以及 spec-kit 和 openspec 这类工具的优势以后，就要开始一个使用案例，我就以本次我是如何使用 openspec 帮我完成这个提案本身，去写这篇文章。

更新提案，文章里面有几个部分需要调整：

1. AI 工具的演进阶段，是不是足够准确
2. 精简整篇文章，去除冗余和重复内容

5. 实施与归档

跟 AI Agent 说：

实施这个提案

它会自动帮你执行这个指令：openspec apply complete-openspec-article

归档这个提案

对应这个指令：openspec archive complete-openspec-article --yes

提案及规范文件被归档到 openspec/changes/archive/2025-11-04-complete-openspec-article/，形成完整可追溯的记录。

六、个人实践心得

• 我只需记住如何初始化 OpenSpec，具体命令让 AI Agent 自动完成。
• 项目规范文件是最宝贵的资产：新工具、新同事都能无缝衔接，消除了流程断层。