用规格驱动 AI 编码 —— 让 AI 真正理解你要什么

如果你正在用 AI 写代码，却总觉得"沟通成本"比"写代码"还高——OpenSpec 可能是你一直缺的那块拼图。

---

一、为什么需要 OpenSpec

AI 编码的真正瓶颈不是代码，是对齐

用 AI 结对编程一段时间后，你大概率会遇到几个反复出现的问题：

痛点	描述
📉理解偏差	花了两段话描述功能，AI 写出来的代码却跑偏了
🔄重复解释	纠偏、重来，几轮下来上下文窗口消耗大半
💨记忆蒸发	对话关闭后，所有讨论、决策、设计全部消失
⏸️中断丢失	被打断后回来，AI 完全不知道你之前做到哪了

这些痛点的根源都一样：AI 的"记忆"只存在于当前对话中。对话关了，一切归零。

OpenSpec 的解决思路

既然对话会消失，那就把重要的东西写成文件：

• 需求是什么

• 技术方案怎么设计

• 实现步骤有哪些

全部以 Markdown 文件 持久化在项目里。AI 每次开工，不是从你的口头描述出发，而是从这份"共识文档"出发。

---

二、安装与初始化

前置要求

• Node.js 20.19.0

安装

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

初始化项目

cd your-project
openspec init

CLI 会问你使用哪些 AI 工具（Claude Code、Cursor、Copilot 等），然后自动往对应目录写入 Skill 和斜杠命令文件。

完成后项目里多出一个 openspec/ 目录：

openspec/
├── specs/        # 系统当前行为的"源真相"（Source of Truth）
├── changes/      # 每个变更的独立工作目录
└── config.yaml   # 项目配置

配置项目上下文（强烈推荐）

在 openspec/config.yaml 里告诉 AI 你的项目是什么样的：

schema: spec-driven

context: |
  技术栈：TypeScript、React 18、Node.js、PostgreSQL
  API 风格：RESTful，文档在 docs/api.md
  测试框架：Vitest + React Testing Library
  代码规范：参考 .eslintrc.js

rules:
  proposal:
    - 必须包含回滚方案
    - 标注影响的模块范围
  specs:
    - 使用 Given/When/Then 格式描述测试场景

context 会注入到所有工件的生成过程中——相当于一次配置，以后再也不用在对话开头反复交代"我们用的是 React + TypeScript"了。

💡 可以让 AI 帮你生成初稿：

Please read openspec/config.yaml and help me fill it out
with details about my project, tech stack, and conventions

启用扩展命令

默认只安装了 4 个核心命令。解锁完整命令集：

openspec config profile
openspec update

选择 Expanded Profile 后，new、continue、ff、verify、sync、bulk-archive、onboard 等高级命令就可以用了。

---

三、核心理念

为什么要先写"规格"再写代码？

规格是给 AI 看的行为契约 —— 它告诉 AI 系统应该表现出什么行为。你基于这份契约去验收。

四个设计原则

原则	说明
🧘灵活，而非死板	没有"规划阶段不许写代码"这种锁定。写到一半发现 specs 不对？回去改就是了
🔄迭代，而非瀑布	不要求一次把所有事情想清楚。先写个大概，边做边完善
📄简单，而非复杂	就是几个 Markdown 文件，没有数据库、没有服务端、没有 Dashboard
🏗️存量优先	从第一天起就为"改存量系统"设计，而不是只能在空白项目上玩

两个核心概念：Specs 和 Changes

概念	含义	回答的问题
Specs（主规格）	系统当前行为的权威描述——"源真相"	系统现在是怎么运作的？
Changes（变更）	正在进行的修改——每个功能/Bug 修复独立一个文件夹	我们打算怎么改？

当一个变更完成并归档后，它里面的规格变化会合并进 specs——主规格因此更新，变更则移入归档目录。

Specs 长什么样？

核心两部分：需求（Requirements） 和 场景（Scenarios）。

需求 — 用 RFC 2119 关键字表达意图强度

## Purpose
用户认证模块，管理登录、登出和会话维护。

### Requirement: Login Authentication
系统 MUST 在用户提供有效凭证时签发 JWT token。
系统 MUST 在凭证无效时返回 401 错误，且不泄露是用户名还是密码错误。
系统 SHOULD 在连续 5 次失败后触发临时锁定。
系统 MAY 支持"记住我"功能以延长 token 有效期。

关键字	含义
MUST	必须实现，不实现就是 Bug
SHOULD	强烈建议，除非有充分理由可以不做
MAY	可选的增强功能

场景 — Given/When/Then 格式

#### Scenario: Successful Login
Given 用户名 "alice" 存在且密码正确
When 用户提交登录请求
Then 系统返回 200 和有效的 JWT token
And token 有效期为 24 小时

#### Scenario: Invalid Password
Given 用户名 "alice" 存在但密码错误
When 用户提交登录请求
Then 系统返回 401
And 错误信息不区分"用户不存在"和"密码错误"

⚠️ 重要：specs 只描述外部可观察的行为，不描述内部实现。

判断标准：如果你把底层实现换了（比如从 bcrypt 换成 argon2），但系统对外的行为没有任何变化，那这个东西就不该出现在 specs 里。

工件（Artifacts）：从"为什么"到"怎么做"

每个变更包含 4 个工件，有明确的依赖关系：

工件	回答的问题	内容
proposal.md	为什么要做这件事？	动机、范围（做什么和不做什么）、预期收益
specs/	系统行为会怎么改变？	用 Delta Specs 描述新增、修改、删除了哪些行为
design.md	技术上怎么实现？	架构决策、组件设计、技术选型的理由
tasks.md	具体要干哪几件事？	带复选框的实现清单，AI 在 /opsx:apply 时逐条执行

Delta Specs：改存量代码的秘密武器

每个变更的 specs/ 子目录里存放的是三类变化：

## ADDED Requirements

### Requirement: Theme Switching
系统 MUST 提供深色/浅色主题切换功能。
系统 SHOULD 支持跟随操作系统主题设置。

## MODIFIED Requirements

### Requirement: Page Background (MODIFIED)
- 原：系统 MUST 使用固定白色背景（#FFFFFF）
- 新：系统 MUST 根据当前主题设置显示对应的背景色

## REMOVED Requirements

### Requirement: Fixed Color Scheme (REMOVED)
- 原：系统 MUST 使用预设的固定配色方案
- 原因：被新的主题系统取代

归档时，这些增量会自动合并进 openspec/specs/ 主规格：

三个好处：

1. 看变更一目了然 —— 审查时直接告诉你改了什么

2. 并行开发不冲突 —— 各自描述"我改了什么"

3. 存量项目友好 —— 不需要先给整个系统写完整规格

渐进式严格：不需要一步到位

场景	规格详细程度
日常开发（Lite Spec）	简短的行为描述、清晰的范围界定、基本的验收条件
高风险变更（Full Spec）	完整的 Given/When/Then 场景、边界条件分析、错误处理路径

💡 判断标准： 如果这个变更搞砸了的返工成本很高，就多花点时间写规格；如果改错了 5 分钟就能修好，那写个大概就够了。

---

四、命令详解

命令全景图

核心命令（Core Profile，默认可用）

/opsx:propose — 需求清晰时，一步到位

你已经想好了要做什么，AI 会一口气生成全套工件：

You: /opsx:propose 用户可以通过 GitHub OAuth 登录，
     登录后自动创建账号，支持关联已有邮箱账号

AI: ✓ Created openspec/changes/add-github-oauth/
    ✓ proposal.md — scope & intent
    ✓ specs/auth.md — delta specs for authentication
    ✓ design.md — OAuth flow, token handling, account linking
    ✓ tasks.md — 8 implementation tasks
    Ready for review!

💡 生成后花几分钟扫一遍工件——尤其是 tasks.md 的拆分是否合理、specs/ 有没有遗漏边界条件。

/opsx:explore — 不确定的时候，先探索

还没想清楚要做什么？用 explore 让 AI 先帮你搞清楚情况，零副作用：

You: /opsx:explore 我们应该用 WebSocket 还是 SSE 来实现实时通知？
     请分析当前的架构，评估两种方案

AI: Let me investigate your codebase...

    Comparison:
    • WebSocket: bidirectional, but requires nginx upgrade config
    • SSE: simpler, works through existing HTTP stack

    Recommendation: SSE for your use case.

explore 完成后可以自然衔接到 propose 或 new。

/opsx:apply — 按清单执行实现

工件准备好了，让 AI 按 tasks.md 里的清单逐条干活：

You: /opsx:apply add-github-oauth

AI: Reading tasks.md... Found 8 tasks, 0 completed.

    Working on task 1: Install passport-github2 dependency
    ✓ Added to package.json, ran npm install

    Working on task 2: Create OAuth strategy configuration
    ✓ Created src/auth/github-strategy.ts
    ...
    All 8 tasks complete!

每完成一项，AI 会在 tasks.md 里打上勾。如果中途被打断，下次重新执行 /opsx:apply，它会从未完成的任务接着来。

/opsx:archive — 收尾归档

功能实现完了，归档这个变更：

You: /opsx:archive add-github-oauth

AI: ✓ All 8 tasks completed
    ✓ Syncing delta specs to openspec/specs/auth.md
    ✓ Archived to openspec/archive/2026-02-27_add-github-oauth/
    Change closed.

归档做了三件事：

1. 把 Delta Specs 合并进 openspec/specs/ 主规格

2. 把变更目录整体移到带时间戳的归档目录

3. 这个变更的生命周期正式结束

💡 归档前建议先跑一次 /opsx:verify。

---

扩展命令（需启用 Expanded Profile）

/opsx:new — 只建骨架，不急着填内容

和 propose 不同，new 只创建变更目录和元数据，不生成任何工件内容：

You: /opsx:new add-logout-button

AI: Created openspec/changes/add-logout-button/
    Ready to create: proposal

后续用 /opsx:continue 或 /opsx:ff 来生成工件。

/opsx:continue — 一步一步来，每步都能审查

每次执行生成一个工件，按依赖链推进：

You: /opsx:continue add-logout-button

AI: Creating proposal.md...
    ✓ proposal.md created
    Next artifact: specs

You: （审查 proposal，发现范围需要调整，手动编辑）

You: /opsx:continue add-logout-button

AI: Creating specs/...
    ✓ specs/session.md created (delta)
    Next artifact: design

适合需求还在打磨中、每一步都想看看再说的情况。

/opsx:ff — 快进生成所有剩余工件

和 continue 对应——如果你已经确认方向没问题，直接快进补全：

You: /opsx:new add-logout-button

AI: Created openspec/changes/add-logout-button/

You: /opsx:ff

AI: Creating all planning artifacts...
    ✓ proposal.md
    ✓ specs/
    ✓ design.md
    ✓ tasks.md
    Ready for implementation!

场景	选择
需求清晰、能一口气描述完	ff
需求还在打磨、想每步审查	continue
赶时间	ff
复杂变更、需要精细控制	continue

/opsx:verify — 归档前的质量检查

让 AI 拿着规格去对照实际代码，从三个维度报告问题：

You: /opsx:verify add-logout-button

AI: Verifying implementation against specs...

    ✅ Completeness: 4/4 tasks done, all scenarios covered
    ⚠️ Correctness: WARNING — logout doesn't clear localStorage
    ✅ Coherence: Design patterns consistent

    1 issue found. Recommend fixing before archive.

维度	检查内容
完整性	所有任务是否完成？需求场景是否覆盖？
正确性	实现是否匹配规格意图？边界条件是否处理？
一致性	代码结构是否反映设计决策？命名和模式是否统一？

报告分为 CRITICAL、WARNING、SUGGESTION 三个级别。

/opsx:sync — 只同步规格，不归档

有时候一个变更还在进行中，但你希望它的规格先合并进主规格：

You: /opsx:sync add-logout-button

AI: Merging delta specs into main specs...
    ✓ openspec/specs/session.md updated
    Change remains active (not archived).

/opsx:bulk-archive — 并行开发后的批量收尾

一次性全部归档，自动检测并解决规格冲突：

You: /opsx:bulk-archive

AI: Found 3 completed changes:
    • add-logout-button (4/4 tasks)
    • fix-session-timeout (3/3 tasks)
    • update-user-profile (6/6 tasks)

    ⚠️ Conflict in specs/session.md detected
    → Resolved by checking actual implementation

    ✓ All 3 changes archived.

/opsx:onboard — 交互式上手教程

第一次用 OpenSpec？让它用你的真实代码库走一遍完整流程：

You: /opsx:onboard

AI: Welcome to OpenSpec! Let's walk through the workflow
     using your actual codebase...

CLI 工具命令

这些在终端里用，日常管理少不了：

openspec list                    # 查看所有活跃变更
openspec view                    # 交互式仪表盘
openspec show add-dark-mode      # 查看某个变更的详情
openspec status add-dark-mode    # 查看工件完成进度
openspec validate --all --strict # 检查所有变更和规格的格式
openspec archive add-dark-mode   # 从终端归档
openspec config profile          # 切换 Profile

---

五、实战场景

场景总览流程图

场景一：需求清晰，直接开干

Core Profile 路径（最快）：

/opsx:propose → 审查 → /opsx:apply → /opsx:verify → /opsx:archive

You: /opsx:propose 在用户设置页面添加深色模式开关，
     支持跟随系统主题，选择结果持久化到 localStorage

AI: ✓ Created openspec/changes/add-dark-mode/
    ✓ proposal.md — scope & intent
    ✓ specs/ui-theme.md — delta specs
    ✓ design.md — CSS variables approach, theme context
    ✓ tasks.md — 6 implementation tasks
    Ready for review!

You: （扫了一遍 tasks.md，拆分合理，specs 覆盖了跟随系统和手动切换两种场景）

You: /opsx:apply add-dark-mode

AI: Working through tasks...
    ✓ Created ThemeContext with system preference detection
    ✓ Added CSS variables for light/dark themes
    ✓ Implemented toggle switch in Settings page
    ✓ Added localStorage persistence
    ✓ Updated existing components to use theme variables
    ✓ Added transition animations
    All 6 tasks complete!

You: /opsx:verify add-dark-mode

AI: ✅ Completeness: 6/6 tasks, all scenarios covered
    ✅ Correctness: Matches spec intent
    ✅ Coherence: Consistent use of CSS variables
    No issues found.

You: /opsx:archive add-dark-mode

AI: ✓ Synced delta specs → openspec/specs/ui-theme.md
    ✓ Archived to openspec/archive/2026-02-27_add-dark-mode/
    Change closed.

Expanded Profile 路径（更可控）：

/opsx:new → /opsx:ff → /opsx:apply → /opsx:verify → /opsx:archive

---

场景二：需求模糊，需要边探索边明确

推荐路径：

/opsx:explore → /opsx:new → /opsx:continue → ... → /opsx:apply → /opsx:archive

You: /opsx:explore 首页加载时间超过 3 秒，用户反馈很多。
     帮我分析一下瓶颈在哪，有哪些优化方向

AI: Investigating your codebase...

    Found performance bottlenecks:
    1. Homepage fetches 5 API endpoints sequentially (not parallel)
    2. Product images are unoptimized PNGs (avg 2.3MB each)
    3. No code splitting — main bundle is 1.8MB
    4. SSR is disabled, full client-side rendering

    Recommended priority:
    1. Parallelize API calls (quick win, ~40% improvement)
    2. Image optimization pipeline (medium effort, big impact)
    3. Code splitting (one-time setup, ongoing benefit)
    4. SSR (largest effort, evaluate ROI separately)

You: 先做第 1 和第 2 个吧，第 3 个后续再说

You: /opsx:new homepage-performance-fix

You: /opsx:continue homepage-performance-fix