用约束驱动AI写好代码：OpenSpec 完全使用指南
·
OpenSpec 完全使用指南
用规格驱动 AI 编码 —— 让 AI 真正理解你要什么
如果你正在用 AI 写代码，却总觉得"沟通成本"比"写代码"还高——OpenSpec 可能是你一直缺的那块拼图。
目录
- [为什么需要 OpenSpec](#一为什么需要 openspec)
- 安装与初始化
- 核心理念
- 命令详解
- 实战场景
- 场景一：需求清晰，直接开干
- 场景二：需求模糊，需要边探索边明确
- 场景三：并行开发多个功能
- [场景四：已完成未归档的 change 发现 Bug](#场景四已标记完成但未归档的 change 发现 bug 如何修复)
- 场景五：重新开启客户端继续工作
- [场景六：未完成的 change 有场景遗漏](#场景六发现未完成的 change 有场景遗漏怎么处理)
- 场景七：有明确的需求文档怎么开始
- 最佳实践
一、为什么需要 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 直接写代码 → 发现理解不一致 → 返工
OpenSpec 工作流：
写规格 → AI 理解规格 → 基于规格写代码 → 基于规格验收
规格是给 AI 看的行为契约——它告诉 AI 系统应该表现出什么行为。你基于这份契约去验收。
四个设计原则
| 原则 | 说明 |
|---|---|
| 🧘 灵活，而非死板 | 没有"规划阶段不许写代码"这种锁定。写到一半发现 specs 不对？回去改就是了 |
| 🔄 迭代，而非瀑布 | 不要求一次把所有事情想清楚。先写个大概，边做边完善 |
| 📄 简单，而非复杂 | 就是几个 Markdown 文件，没有数据库、没有服务端、没有 Dashboard |
| 🏗️ 存量优先 | 从第一天起就为"改存量系统"设计，而不是只能在空白项目上玩 |
两个核心概念：Specs 和 Changes
openspec/
├── specs/ ← "系统现在是什么样的"
│ ├── auth/
│ ├── payments/
│ └── ...
└── changes/ ← "我们打算改什么"
├── add-dark-mode/
└── fix-login-bug/
| 概念 | 含义 | 回答的问题 |
|---|---|---|
| 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/ → design.md → tasks.md
为什么做？ 做什么？ 怎么做？ 具体步骤
| 工件 | 回答的问题 | 内容 |
|---|---|---|
| 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/ 主规格：
- ADDED 的内容追加进去
- MODIFIED 的内容替换旧版本
- REMOVED 的内容被移除
三个好处：
- 看变更一目了然——审查时直接告诉你改了什么
- 并行开发不冲突——各自描述"我改了什么"
- 存量项目友好——不需要先给整个系统写完整规格
渐进式严格：不需要一步到位
| 场景 | 规格详细程度 |
|---|---|
| 日常开发（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.
归档做了三件事：
- 把 Delta Specs 合并进
openspec/specs/主规格 - 把变更目录整体移到带时间戳的归档目录
- 这个变更的生命周期正式结束
归档前建议先跑一次 /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
场景三：并行开发多个功能
# 功能 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 内容 | OpenSpec 工件 |
|---|---|
| 问题陈述/背景 | proposal.md — Problem |
| 功能范围 | proposal.md — Scope |
| 功能列表 | specs/ — Requirements |
| 用户故事/用例 | specs/ — Scenarios |
| 技术方案 | design.md |
| 任务分解 | tasks.md |
| 验收标准 | specs/ — Scenarios |
💡 最佳实践：
- PRD 越详细，AI 生成的工件越准确
- 生成后务必人工审查 specs，确保边界条件完整
- 需求文档中的"非功能需求"（性能、安全）也要写入 specs
- 用
/opsx:verify确保最终实现覆盖所有需求
六、最佳实践
✅ 推荐做法
| 做法 | 说明 |
|---|---|
| 📝 先写规格再写代码 | 花 5 分钟写规格，可能节省 1 小时返工 |
| 🎯 渐进式严格 | 日常开发用 Lite Spec，高风险变更用 Full Spec |
| 🔄 及时归档 | 功能完成后立即归档，保持 specs 最新 |
| 🔍 归档前 verify | 跑一次 /opsx:verify 抓住遗漏 |
| 📁 配置 context | 一次配置，AI 永远知道你的技术栈 |
| 🧩 小步快跑 | 一个变更聚焦一个功能，不要贪大 |
❌ 避免的坑
| 坑 | 建议 |
|---|---|
| 🚫 跳过 specs 直接写代码 | 失去规格驱动的意义 |
| 🚫 规格写得太细 | 描述行为，不要描述实现细节 |
| 🚫 长期不归档 | specs 会过时，失去参考价值 |
| 🚫 一个大变更包含太多功能 | 拆分成小变更，便于审查和回滚 |
| 🚫 忽略 context 配置 | 每次都要重复交代技术栈 |
工作流总结
┌─────────────────────────────────────────────────────────┐
│ 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 实战经验整理，持续更新中。
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
1
0- 0
已为社区贡献1条内容
所有评论(0)