用约束驱动AI写好代码：OpenSpec 完全使用指南

OpenSpec 完全使用指南

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

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

目录

1. [为什么需要 OpenSpec](#一为什么需要 openspec)
2. 安装与初始化
3. 核心理念
4. 命令详解
5. 实战场景
   • 场景一：需求清晰，直接开干
   • 场景二：需求模糊，需要边探索边明确
   • 场景三：并行开发多个功能
   • [场景四：已完成未归档的 change 发现 Bug](#场景四已标记完成但未归档的 change 发现 bug 如何修复)
   • 场景五：重新开启客户端继续工作
   • [场景六：未完成的 change 有场景遗漏](#场景六发现未完成的 change 有场景遗漏怎么处理)
   • 场景七：有明确的需求文档怎么开始
6. 最佳实践

一、为什么需要 OpenSpec

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

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

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

OpenSpec 的解决思路

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

• 需求是什么
• 技术方案怎么设计
• 实现步骤有哪些

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

二、安装与初始化

前置要求

• Node.js 20.19.0+

安装

npminstall-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.jsrules: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 直接写代码 → 发现理解不一致 → 返工 

OpenSpec 工作流：

写规格 → AI 理解规格 → 基于规格写代码 → 基于规格验收 

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

四个设计原则

两个核心概念：Specs 和 Changes

openspec/ ├── specs/ ← "系统现在是什么样的" │ ├── auth/ │ ├── payments/ │ └── ... └── changes/ ← "我们打算改什么" ├── add-dark-mode/ └── fix-login-bug/ 

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

Specs 长什么样？

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

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

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

场景 - 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/ → design.md → tasks.md 为什么做？ 做什么？ 怎么做？ 具体步骤 

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/ 主规格：

• ADDED 的内容追加进去
• MODIFIED 的内容替换旧版本
• REMOVED 的内容被移除

三个好处：

1. 看变更一目了然——审查时直接告诉你改了什么
2. 并行开发不冲突——各自描述"我改了什么"
3. 存量项目友好——不需要先给整个系统写完整规格

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

判断标准： 如果这个变更搞砸了的返工成本很高，就多花点时间写规格；如果改错了 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! 

/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 

场景三：并行开发多个功能

# 功能 A /opsx:propose feature-a → /opsx:apply feature-a # 功能 B（同时进行） /opsx:propose feature-b → /opsx:apply feature-b # 全部完成后批量归档 /opsx:bulk-archive 

每个变更在各自的 changes/ 子目录里工作，互不干扰。

场景四：已标记完成但未归档的 change 发现 Bug 如何修复

问题： 一个 change 已经全部任务完成（tasks.md 全勾），但测试时发现 Bug，还没归档。

处理流程：

/opsx:verify → 定位问题 → 手动修复或追加任务 → /opsx:apply → /opsx:verify → /opsx:archive 

步骤详解：

Step 1: 先用 verify 确认问题

You: /opsx:verify add-dark-mode AI: Verifying implementation against specs... ✅ Completeness: 6/6 tasks done ⚠️ Correctness: WARNING — Theme doesn't persist after page refresh ✅ Coherence: Design patterns consistent 1 issue found: localStorage write missing 

Step 2: 根据问题类型选择修复方式

方式 A - 小 Bug 直接修复：

You: 发现 localStorage 写入逻辑缺失，请补充 AI: Fixing the issue... ✓ Added localStorage.setItem('theme', selectedTheme) in ThemeContext ✓ Added loadSavedTheme() on app initialization Fix complete! 

方式 B - 需要多个步骤，追加任务：

You: /opsx:continue add-dark-mode AI: All planning artifacts exist. You can: - Edit tasks.md manually to add new tasks - Or describe what needs to be added You: 在 tasks.md 里追加两个任务： 1. 添加 localStorage 读取逻辑 2. 添加主题切换后的持久化写入 AI: ✓ Updated tasks.md with 2 new tasks Ready for /opsx:apply 

Step 3: 执行修复

You: /opsx:apply add-dark-mode AI: Reading tasks.md... Found 2 new tasks, 0 completed. Working on task 1: Add localStorage read logic ✓ Added loadSavedTheme() in App.tsx Working on task 2: Add persistence on theme change ✓ Added useEffect hook in ThemeContext All tasks complete! 

Step 4: 再次 verify 确认修复

You: /opsx:verify add-dark-mode AI: ✅ Completeness: 8/8 tasks done ✅ Correctness: Theme persists correctly after refresh ✅ Coherence: No issues found Ready for archive! 

Step 5: 归档

You: /opsx:archive add-dark-mode AI: ✓ Synced delta specs → openspec/specs/ui-theme.md ✓ Archived to openspec/archive/2026-03-11_add-dark-mode/ Change closed. 

⚠️ 注意事项：

• 如果 Bug 涉及规格遗漏，先更新 specs/ 再修复代码
• 修复后务必再跑一次 /opsx:verify
• 如果 Bug 是规格设计问题，可能需要 /opsx:explore 重新评估方案

场景五：重新开启客户端，如何继续工作

问题： 关闭对话/客户端后重新打开，如何继续之前的工作。

核心原理： OpenSpec 的所有状态都持久化在 openspec/ 目录中，新对话只需读取即可继续。

恢复流程：

Step 1: 查看活跃变更列表

You: /opsx:list AI: Active changes: • add-dark-mode (6/6 tasks) — Ready for verify • fix-login-bug (2/5 tasks) — In progress • new-feature (0/4 tasks) — Planning complete 

或者用终端命令：

openspec list 

Step 2: 查看某个变更的详情

You: /opsx:show fix-login-bug AI: Change: fix-login-bug Status: In progress (2/5 tasks completed) Artifacts: ✓ proposal.md ✓ specs/auth.md ✓ design.md ✓ tasks.md (2 checked, 3 pending) Pending tasks: ☐ Task 3: Add rate limiting to login endpoint ☐ Task 4: Implement account lockout after 5 failures ☐ Task 5: Add unit tests for lockout logic 

或者：

openspec status fix-login-bug 

Step 3: 继续执行

情况 A - 实现中途：

You: /opsx:apply fix-login-bug AI: Reading tasks.md... Found 3 tasks pending. Working on task 3: Add rate limiting to login endpoint ✓ Added express-rate-limit middleware ... All 3 tasks complete! 

情况 B - 规划中途（工件还没生成完）：

You: /opsx:continue fix-login-bug AI: Last completed artifact: specs Next artifact: design.md Creating design.md... ✓ design.md created Next artifact: tasks 

情况 C - 需要先看规格再决定：

You: 帮我读一下 openspec/changes/fix-login-bug/specs/auth.md AI: Reading specs... Current delta specs for auth module: - ADDED: Account lockout after 5 failed attempts - MODIFIED: Login error response (no distinction between "user not found" and "wrong password") Based on these specs, the implementation should... 

Step 4: 必要时同步规格

You: /opsx:sync fix-login-bug AI: Merging delta specs into main specs... ✓ openspec/specs/auth.md updated Change remains active (not archived). 

💡 最佳实践：

• 每天下班前用 /opsx:list 看一眼活跃变更
• 新对话第一件事：/opsx:show <change-name> 了解进度
• 长期中断后，先用 /opsx:verify 检查已完成的部分

场景六：发现未完成的 change 有场景遗漏，怎么处理

问题： 做到一半发现 specs 里的场景（Scenarios）有遗漏，需要补充。

处理流程：

编辑 specs/ → /opsx:sync → 更新 tasks.md → /opsx:apply → /opsx:verify 

步骤详解：

Step 1: 识别遗漏的场景

You: /opsx:verify fix-login-bug AI: Verifying implementation against specs... ⚠️ Completeness: WARNING — Missing scenario coverage The following scenario is not tested: - Scenario: Account Unlock After Timeout Recommendation: Add this scenario to specs and implement corresponding logic. 

Step 2: 编辑 specs 补充场景

手动编辑 openspec/changes/fix-login-bug/specs/auth.md：

## ADDED Requirements ### Requirement: Account Lockout (MODIFIED) 系统 MUST 在连续 5 次登录失败后锁定账户。 系统 MUST 在锁定 30 分钟后自动解锁。← 新增 #### Scenario: Account Lock After Failed Attempts Given 用户连续 5 次输入错误密码 When 第 5 次登录请求提交 Then 系统返回 401 And 账户被锁定 30 分钟 #### Scenario: Account Unlock After Timeout ← 新增场景 Given 账户因多次失败被锁定 When 30 分钟过去 Then 账户自动解锁 And 用户可以重新尝试登录 

Step 3: 同步规格到主规格（可选）

You: /opsx:sync fix-login-bug AI: Merging delta specs into main specs... ✓ openspec/specs/auth.md updated Change remains active. 

Step 4: 更新 tasks.md 追加任务

手动编辑 openspec/changes/fix-login-bug/tasks.md，追加任务：

## Tasks - [x] Task 1: Install rate limiting library - [x] Task 2: Create login attempt counter - [x] Task 3: Implement account lockout logic - [ ] Task 4: Add automatic unlock after 30 minutes ← 新增 - [ ] Task 5: Add unit tests for unlock logic ← 新增 

或者让 AI 帮你追加：

You: 在 tasks.md 里追加两个任务： 1. 添加 30 分钟后自动解锁逻辑 2. 添加解锁场景的单元测试 AI: ✓ Updated tasks.md with 2 new tasks 

Step 5: 执行新增任务

You: /opsx:apply fix-login-bug AI: Reading tasks.md... Found 2 new tasks. Working on task 4: Add automatic unlock logic ✓ Added scheduled job to clear lockouts Working on task 5: Add unit tests ✓ Created auth-unlock.test.ts with 3 test cases All tasks complete! 

Step 6: 最终 verify

You: /opsx:verify fix-login-bug AI: ✅ Completeness: 5/5 tasks done, all scenarios covered ✅ Correctness: Implementation matches updated specs ✅ Coherence: No issues found Ready for archive! 

💡 关键要点：

• Specs 是活的文档，发现遗漏随时可以改
• 改了 specs 后，记得同步更新 tasks.md
• 用 /opsx:verify 验证场景覆盖是否完整
• 如果遗漏影响很大，可能需要 /opsx:explore 重新评估

场景七：有明确的需求文档，怎么开始

问题： 手里已经有 PRD/需求文档，如何用 OpenSpec 开始工作。

两种路径：

路径 A：让 AI 从需求文档生成工件（推荐）

Step 1: 创建变更目录

You: /opsx:new user-registration-module AI: Created openspec/changes/user-registration-module/ Ready to create: proposal 

Step 2: 提供需求文档，生成 proposal

You: 这是我们的 PRD 文档，请帮我生成 proposal.md： [粘贴 PRD 内容或上传文件] AI: Analyzing requirements... ✓ Created proposal.md with: - Problem statement: User registration friction - Scope: Email registration, verification, welcome flow - Out of scope: Social login, SSO (future phases) - Expected impact: 30% reduction in signup drop-off 

Step 3: 基于 proposal 生成 specs

You: /opsx:continue user-registration-module AI: Creating specs/... ✓ specs/registration.md created (delta) Generated 8 requirements and 12 scenarios based on the proposal. Please review for accuracy. 

Step 4: 审查并调整 specs

You: （阅读 specs/registration.md，发现需要调整） You: 第 3 个场景需要修改，密码强度要求应该是： - 至少 8 个字符 - 包含大小写字母和数字 而不是现在的 6 个字符 AI: ✓ Updated specs/registration.md 

Step 5: 继续生成 design 和 tasks

You: /opsx:ff user-registration-module AI: Creating remaining artifacts... ✓ design.md — Database schema, API endpoints, validation logic ✓ tasks.md — 12 implementation tasks Ready for /opsx:apply! 

路径 B：手动创建 proposal，再让 AI 生成后续

Step 1: 手动写 proposal.md

在 openspec/changes/user-registration-module/proposal.md 中写：

# Proposal: User Registration Module ## Problem 当前注册流程转化率仅 45%，主要流失点在邮箱验证环节。 ## Scope ### In Scope - 邮箱注册表单 - 邮箱验证邮件发送 - 验证码校验接口 - 欢迎邮件流程 ### Out of Scope - 社交账号登录（后续迭代） - SSO 企业登录（后续迭代） ## Expected Impact - 注册转化率提升至 65% - 验证邮件打开率 > 80% 

Step 2: 让 AI 基于 proposal 生成 specs

You: /opsx:continue user-registration-module AI: Reading proposal.md... ✓ Creating specs/registration.md Generated 8 requirements and 12 scenarios 

Step 3: 继续生成 design 和 tasks

You: /opsx:ff user-registration-module AI: ✓ design.md created ✓ tasks.md created — 12 tasks Ready for /opsx:apply! 

路径 C：需求文档是外部链接或文件

Step 1: 让 AI 读取需求文档

You: 请读取这个需求文档并帮我创建 OpenSpec 工件： https://docs.company.com/prd/user-registration AI: Fetching and analyzing document... ✓ Created openspec/changes/user-registration-module/ ✓ proposal.md — extracted from PRD ✓ specs/registration.md — 8 requirements, 12 scenarios ✓ design.md — technical approach ✓ tasks.md — 12 implementation tasks Ready for review! 

Step 2: 审查并调整

You: （审查生成的工件，调整 specs 中的边界条件） You: specs 里需要增加一个场景： 当邮箱已经被注册时，应该提示"该邮箱已注册" 而不是"注册失败" AI: ✓ Updated specs/registration.md Added Scenario: Duplicate Email Registration 

📋 需求文档映射表：

💡 最佳实践：

• PRD 越详细，AI 生成的工件越准确
• 生成后务必人工审查 specs，确保边界条件完整
• 需求文档中的"非功能需求"（性能、安全）也要写入 specs
• 用 /opsx:verify 确保最终实现覆盖所有需求

六、最佳实践

✅ 推荐做法

❌ 避免的坑

工作流总结

┌─────────────────────────────────────────────────────────┐ │ OpenSpec 工作流 │ ├─────────────────────────────────────────────────────────┤ │ │ │ 需求清晰 需求模糊 │ │ ↓ ↓ │ │ /opsx:propose /opsx:explore │ │ ↓ ↓ │ │ 审查工件 /opsx:new │ │ ↓ ↓ │ │ /opsx:apply /opsx:continue/ff │ │ ↓ ↓ │ │ /opsx:verify /opsx:apply │ │ ↓ ↓ │ │ /opsx:archive /opsx:verify │ │ ↓ │ │ /opsx:archive │ │ │ └─────────────────────────────────────────────────────────┘ 

附录

相关资源

• GitHub: https://github.com/Fission-AI/OpenSpec
• 官方文档: https://github.com/Fission-AI/OpenSpec/blob/main/docs/
• 迁移指南: https://github.com/Fission-AI/OpenSpec/blob/main/docs/migration-guide.md

常见问题

Q: 小项目需要用 OpenSpec 吗？
A: 如果项目会持续迭代、或者需要多人协作，建议用。一次性脚本项目可以不用。

Q: 规格要写多详细？
A: 够 AI 理解你要干什么就行。返工成本高的变更多写，改错了 5 分钟能修好的少写。

Q: 可以和现有工作流混用吗？
A: 可以。OpenSpec 不搞"规划阶段不许写代码"这种锁定，灵活使用即可。

Q: specs 和项目文档有什么区别？
A: specs 描述外部可观察的行为，是给 AI 看的行为契约；项目文档可以是任何内容（架构说明、API 文档等）。

本指南基于 OpenSpec 实战经验整理，持续更新中。