

>一个关于混乱、对齐与工程尊严的故事


----

## 📌 全文概览

![image.png](https://developer.qcloudimg.com/http-save/yehe-9261324/249760db014894b0b9614a9d032ee215.png)


----

## 第一章：一个混乱的早晨


小林是一家初创公司的独立开发者，维护着一个 React Todo App。

某天早上，产品经理发来两条消息：

>💬 "用户反馈刷新后 filter 状态会重置，这个 bug 得尽快修。"
💬 "另外，下个版本要加 Due Date 功能，支持过期高亮显示。"


小林打开 CodeBuddy，很熟练地输入：

```
帮我修 filter 刷新重置的 bug，顺便加上 Due Date 功能和过期高亮。
```
AI 开始疯狂输出代码。三十分钟后，功能看起来有了——但小林盯着屏幕，心里开始不安：


- filter 持久化的逻辑改了哪个文件哪一行？

- 过期高亮的日期判断，用的是哪个时区？

- 下个月如果要加"批量完成"，这段代码能不能扩展？


他不知道。CodeBuddy 也不记得了——那段对话已经消失在 token 的汪洋里。

**这，就是 Vibe Coding 的宿命。**


----

## 第二章：转机——OpenSpec 登场


几天后，同事老张发来一条消息：

>"你用过 OpenSpec 吗？不是让你改变写代码的方式，只是在写代码之前，先把要做什么写清楚。"


**OpenSpec** 是一个轻量级规格驱动开发框架（Spec-Driven Development，SDD），专为 AI 编程助手设计，原生支持 CodeBuddy。

核心理念只有一句话：

>**先对齐意图，再生成代码。让规格文档住在仓库里，而不是消失在聊天历史里。**


### Vibe Coding vs Spec-Driven Development

![image.png](https://developer.qcloudimg.com/http-save/yehe-9261324/bef23db77388142cf60133b97ec05fdd.png)

### 痛点与解法对照


|痛点|没有OpenSpec|有了OpenSpec|
|:-:|:-:|:-:|
|AI 跨 session 失忆|每次重新解释需求|spec 文件持久化，随时读取|
|多人实现风格漂移|各做各的，没有契约|行为约束写进 spec|
|改动难以 review|reviewer 只能看代码 diff|先看 proposal + spec delta|
|回归风险高|改一处不知影响哪里|每次变更有明确 scope|
|技术决策失踪|"当时为什么这样？"|design.md 永久留存|


----

## 第三章：装好工具，出发


### 3.1 环境准备


```shell
# 确认 Node.js 版本 >= 20.19.0
node --version

# 全局安装 OpenSpec
npm install -g @fission-ai/openspec@latest

# 验证安装
openspec --version
```
### 3.2 在项目中初始化（CodeBuddy 专项）


```shell
cd your-todo-app

# 针对 CodeBuddy 初始化
openspec init --tools codebuddy
```
>**CodeBuddy 的工作方式**：

OpenSpec 为 CodeBuddy 生成原生 slash commands，
命令格式为 `/openspec:propose`、`/openspec:apply`、`/openspec:archive` 等，

直接在 CodeBuddy 的对话面板中输入即可触发，无需手动调用 CLI。


初始化后，项目里出现：

```
openspec/
├── AGENTS.md          ← 告知 CodeBuddy 如何使用 OpenSpec
├── config.yaml        ← 项目默认配置
└── specs/             ← 长期规格文档（随变更累积）
```
### 3.3 启用扩展工作流（推荐）


默认 core profile 只包含基础命令。需要 `new / continue / ff / verify / sync` 等精细命令时：

```
# 切换到扩展 profile
openspec config profile   # 交互式选择 extended

# 更新 CodeBuddy 的命令绑定
openspec update
```
### 3.4 CodeBuddy Slash Commands 速览


|SlashCommand|等效CLI|作用|
|:-:|:-:|:-:|
|`/openspec:propose <名称>`|`openspec propose`|快速生成所有规划文档|
|`/openspec:new <名称>`|`openspec new`|仅创建脚手架|
|`/openspec:apply [名称]`|`openspec apply`|按 tasks.md 实现|
|`/openspec:archive [名称]`|`openspec archive --yes`|归档并合并 spec|
|`/openspec:verify [名称]`|`openspec verify`|对照 spec 校验实现|


----

## 第四章：两条路，两种任务


任务进来时，第一件事是判断走哪条路——这是 OpenSpec 最关键的决策：

![image.png](https://developer.qcloudimg.com/http-save/yehe-9261324/9f769a515df98049bf81293590481ec1.png)

>**判断原则**：改一个地方、影响范围清晰 → 快速路径。
要新增能力、影响多文件、未来还会扩展 → 完整路径。


----

## 第五章：先杀 Bug（快速路径实战）


### 任务


>🐛 **Bug**：切换 filter tab 后刷新页面，总是回到"All"，不记住用户的选择。


### Step 1：创建变更脚手架


在 CodeBuddy 对话框输入：

```
/openspec:new fix-filter-persistence
```
CodeBuddy 回应：

```
✓ Created openspec/changes/fix-filter-persistence/
  Schema: spec-driven
  Ready to create: proposal
  Use /openspec:ff to generate all artifacts at once.
```
### Step 2：一次性生成全部规划文档


```
/openspec:ff fix-filter-persistence
```
生成目录结构：

```
openspec/changes/fix-filter-persistence/
├── proposal.md
├── specs/
│   └── todo-filters/
│       └── spec.md
├── design.md
└── tasks.md
```
**必须打开阅读这些文件。** 标准 `proposal.md`：

```
## Why
Filter tab state resets to "All" on every page refresh.
Users lose their selected view context, causing repeated navigation friction.

## What Changes
- Persist selected filter to localStorage on every filter change.
- Restore persisted filter on page load before first render.

## Out of Scope
- Server-side session persistence
- URL-based filter routing

## Impact
- Affected files: src/components/FilterTabs.tsx, src/hooks/useTodos.ts
- No new dependencies.
```
标准 `spec.md` 行为契约：

```
## ADDED Requirements

### Requirement: Filter state persistence

Selected filter tab MUST persist across page refreshes.

#### Scenario: Refresh restores filter

- GIVEN user has selected the "Active" filter
- WHEN the page is refreshed
- THEN "Active" tab remains selected
- AND only active todos are displayed
```
>⚠️ **格式陷阱**：`Scenario` 必须使用 `#### Scenario:` 四级标题。
用加粗或 bullet 替代会导致 `/openspec:verify` 时解析失败，这是初学者最常踩的坑。


### Step 3：实现


```
/openspec:apply fix-filter-persistence
```
CodeBuddy 按 tasks.md 逐条执行：

```
✓ 1.1 Add filter key to localStorage in FilterTabs.tsx
✓ 1.2 Read persisted filter on mount in useTodos.ts
✓ 2.1 npm run lint   — passed
✓ 2.2 npm run build  — passed
```
### Step 4：人工验证


1. 浏览器打开 `/todos`

2. 点击 **Active** tab

3. 刷新页面

4. ✅ 确认仍显示 Active，且只显示未完成项


### Step 5：归档


```
/openspec:archive fix-filter-persistence
```
```
✓ Merged specs → openspec/specs/todo-filters/spec.md
✓ Archived → openspec/changes/archive/2025-03-25-fix-filter-persistence/
```
Bug 消灭。仓库里多了一份永久存档——三个月后新同事接手，打开 spec 就能知道这里踩过什么坑。


----

## 第六章：加新功能（完整路径实战）


### 任务


>✨ **新功能**：Todo 支持设置 Due Date，过期 Todo 显示红色高亮。


这次小林不急，他决定走完整路径，逐步生成每个规划文档并仔细审阅。

### Step 1：创建脚手架


```
/openspec:new add-due-date
```
### Step 2：逐步生成规划文档（每步审阅）

![image.png](https://developer.qcloudimg.com/http-save/yehe-9261324/868efb1f5e5ec0611a72efa753c56f7e.png)
### 四个核心文件详解


#### `proposal.md`——为什么做，做什么，不做什么


```
## Why
Users cannot track task deadlines. Overdue tasks look identical to future ones,
causing missed deadlines with no visual distinction.

## What Changes
- Add optional due_date field to todo items (date picker in create/edit form).
- Show due date label on each todo card.
- Highlight overdue items in red when due_date < today.

## Out of Scope
- Reminder / push notifications
- Recurring tasks
- Calendar view integration

## Success Criteria
- User can optionally set a due date when creating a todo.
- Todos past due date display with red background.
- Due date persists in localStorage alongside other fields.

## Impact
- Affected: src/components/TodoItem.tsx, TodoForm.tsx,
  types/todo.ts, src/hooks/useTodos.ts
- No new runtime dependencies (use native date input).
```
#### `spec.md`——行为契约（ADDED / MODIFIED / REMOVED）


```
## ADDED Requirements

### Requirement: Optional due date on todo items

Todo items MAY have an optional due date (ISO 8601 date string or null).

#### Scenario: Create todo with due date

- GIVEN user opens the add todo form
- WHEN user fills in title and selects a due date
- THEN the todo is saved with the due_date value

#### Scenario: Create todo without due date

- GIVEN user opens the add todo form
- WHEN user fills in title only
- THEN the todo is saved with due_date as null

### Requirement: Overdue highlighting

Todos with due_date earlier than today MUST render with a red background.

#### Scenario: Overdue item displays red

- GIVEN a todo has due_date set to yesterday
- WHEN the todo list renders
- THEN that todo card has a red/danger background color

#### Scenario: Future due date renders normally

- GIVEN a todo has due_date set to tomorrow
- WHEN the todo list renders
- THEN that todo card renders without red highlighting
```
#### `design.md`——技术决策与风险


```
## Decisions

- Store due_date as ISO date string ("2025-03-25") or null in localStorage.
- Compare date strings directly (YYYY-MM-DD) instead of full Date objects
  to avoid local timezone offset issues.
- Use native <input type="date"> — no new UI library needed.

## Risks

- [Risk] Timezone edge case: item may appear overdue 1 day early.
  → Mitigation: strip time component, compare YYYY-MM-DD strings only.
```
#### `tasks.md`——可勾选的执行清单


```
## 1. Data Layer

- [ ] 1.1 Add `due_date?: string | null` to Todo type in types/todo.ts
- [ ] 1.2 Update useTodos.ts: persist/restore due_date in localStorage
- [ ] 1.3 Update addTodo() and editTodo() to accept due_date param

## 2. UI Components

- [ ] 2.1 Add date picker to TodoForm.tsx (optional field)
- [ ] 2.2 Display due_date label in TodoItem.tsx
- [ ] 2.3 Apply red highlight class when due_date < today in TodoItem.tsx

## 3. Validation

- [ ] 3.1 Run npm run lint
- [ ] 3.2 Run npm run build
- [ ] 3.3 Manual: create todo with date, verify persistence on refresh
- [ ] 3.4 Manual: set past date, verify red highlight appears
- [ ] 3.5 Manual: set future date, verify no highlight
```
### Step 3：实现


```
/openspec:apply add-due-date
```
CodeBuddy 按 tasks.md 的 checklist 逐项实现，完成一项打一个勾。

### Step 4：校验


```
/openspec:verify add-due-date
```
```
Checking against specs/todo-due-date/spec.md...
✓ Scenario: Create todo with due date
✓ Scenario: Create todo without due date
✓ Scenario: Overdue item displays red
✓ Scenario: Future due date renders normally
All 4 scenarios pass.
```
### Step 5：归档


```
/openspec:archive add-due-date
```
```
✓ Merged specs → openspec/specs/todo-due-date/spec.md
✓ Archived → openspec/changes/archive/2025-03-25-add-due-date/
```


----

## 第七章：两个变更结束后，仓库长这样

![image.png](https://developer.qcloudimg.com/http-save/yehe-9261324/fae0e8c9f8ec111855862e017c66f665.png)

`specs/` 目录是这个项目的**活的需求文档**——不是一次性的 PRD，而是随每次变更自动生长的行为契约。三个月后新同事问"为什么过期判断用字符串而不是 Date 对象"，`design.md` 里有答案。


----

## 第八章：命令全景速查


### 完整命令对照表


|CodeBuddySlash|等效CLI命令|用途|路径|
|:-:|:-:|:-:|:-:|
|`/openspec:new <n>`|`openspec new <n>`|创建变更脚手架|两条路径通用起点|
|`/openspec:ff <n>`|—|一次生成全部规划文档|快速路径|
|`/openspec:continue <n>`|—|逐步生成下一个规划文档|完整路径|
|`/openspec:propose <n>`|`openspec propose <n>`|new + ff 合并简写|最简单快速路径|
|`/openspec:apply [n]`|`openspec apply [n]`|按 tasks.md 实现代码|两条路径通用|
|`/openspec:verify [n]`|`openspec verify [n]`|对照 spec 逐条校验|完整路径|
|`/openspec:sync [n]`|`openspec sync [n]`|合并 delta 但不关闭变更|多 MR 大功能|
|`/openspec:archive [n]`|`openspec archive [n] --yes`|归档并合并 spec|收尾|
|`/openspec:bulk-archive`|`openspec bulk-archive`|批量归档多个变更|清理工作区|

### 实用 CLI 命令


```
# 查看某个变更当前状态
npx openspec status --change add-due-date

# 严格模式校验 spec 格式
npx openspec validate add-due-date --strict

# 查看所有活跃变更
npx openspec list

# 切换工具或版本后刷新指令
openspec update
```


----

## 第九章：常见陷阱与修正

![image.png](https://developer.qcloudimg.com/http-save/yehe-9261324/dffd5f788150a85d1d71fec6fabdcd19.png)


----

## 尾声：小林三周后


产品经理又发来消息：

>💬 "能加批量完成功能吗？把所有 Active 的一键标为完成。"


小林打开 `openspec/specs/`，三分钟内理清楚影响范围——`todo-filters/spec.md` 定义了 filter 行为，`todo-due-date/spec.md` 记录了数据结构。他在 CodeBuddy 输入：

```
/openspec:new add-bulk-complete
```
这一次，他不慌了。


----

## 🚀 行动指南


>按这个顺序，今天就能跑起来。


### 第一步：安装（5 分钟）


```shell
# 1. 确认 Node.js >= 20.19.0
node --version

# 2. 全局安装
npm install -g @fission-ai/openspec@latest

# 3. 进入你的项目
cd your-project

# 4. 初始化（针对 CodeBuddy）
openspec init --tools codebuddy

# 5. 启用扩展命令（推荐）
openspec config profile    # 选择 extended
openspec update
```
### 第二步：用 Bug 修复练手（15 分钟）


找项目里一个小 bug，完整走一遍快速路径：

```
# 在 CodeBuddy 对话框依次输入：

/openspec:new fix-your-bug
/openspec:ff fix-your-bug
```
>👁️ **停下来**，打开 `proposal.md` 和 `spec.md` 认真读一遍。


```
/openspec:apply fix-your-bug
# 🧪 打开浏览器手动验证
/openspec:archive fix-your-bug
```
### 第三步：用新功能深入练手（30 分钟）


找一个即将要做的小功能，走完整路径：

```
/openspec:new add-your-feature
/openspec:continue add-your-feature   # proposal → 审阅
/openspec:continue add-your-feature   # spec     → 审阅
/openspec:continue add-your-feature   # design   → 审阅
/openspec:continue add-your-feature   # tasks    → 审阅
/openspec:apply add-your-feature
/openspec:verify add-your-feature
/openspec:archive add-your-feature
```
### 第四步：把 OpenSpec 文件提交进 Git


```
git add openspec/
git commit -m "chore: add OpenSpec workflow and initial specs"
```
规划文档和代码一起进仓库，在 code review 里也能看到 proposal——这才是 spec 发挥长期价值的方式。

### 第五步：团队推广节奏


|阶段|时间|做法|
|:-:|:-:|:-:|
|熟悉工具|第 1 周|个人项目试跑两条路径，建立肌肉记忆|
|真实功能|第 2 周|一个真实需求走完整流程，积累第一批 spec|
|引入评审|第 3 周|Code review 时加入 proposal.md 审阅环节|
|团队规范|稳定后|`openspec/specs/` 作为新人 onboarding 必读材料|


----

>**最后一句话**：OpenSpec 不是为了增加流程而生的，
是为了让你在按下 `/openspec:apply` 之前，真正知道自己在做什么。
工具的价值，取决于你愿不愿意认真读自己写的 spec。



💬 "用户反馈刷新后 filter 状态会重置，这个 bug 得尽快修。"💬 "另外，下个版本要加 Due Date 功能，支持过期高亮显示。"

SDD-openspec实战

先对齐意图，再生成代码。让规格文档住在仓库里，而不是消失在聊天历史里。这就是SDD.

架构师

前端

架构设计

开发工具

OpenSpec是轻量级规格驱动开发框架，帮助开发者先对齐意图再生成代码。通过持久化规格文档解决AI编程失忆问题，支持快速路径和完整路径两种开发模式，实现代码可追溯、可扩展。适用于React等前端项目，提升工程尊严与协作效率。

数据结构

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

SDD-openspec实战-腾讯云开发者社区-腾讯云

SDD-openspec实战

SDD-openspec实战

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐