OpenSpec

工作流 ​

本指南介绍 OpenSpec 的常见工作流模式以及何时使用每种模式。有关基础设置，请参阅开始使用。有关命令参考，请参阅命令。

哲学：行动，而非阶段 ​

传统工作流强制你经历各个阶段：规划、实施，然后完成。但实际工作并不能被整齐地划入这些框框。

OPSX 采取不同的方法：

text
Traditional (phase-locked):

  PLANNING ────────► IMPLEMENTING ────────► DONE
      │                    │
      │   "Can't go back"  │
      └────────────────────┘

OPSX (fluid actions):

  proposal ──► specs ──► design ──► tasks ──► implement

关键原则：

  • 行动，而非阶段 - 命令是你能够做的事情，而不是你被困住的阶段
  • 依赖是使能因素 - 它们展示什么是可能的，而非下一步必须做什么

定制： OPSX 工作流由定义工件序列的 schema 驱动。有关创建自定义 schema 的详细信息，请参阅定制。

工作流程概览 ​

默认工作流程保持灵活：探索和验证是可选的，当实施过程中发现新情况时，你可以随时更新规划工件。

mermaid
flowchart TD
    Idea["Idea or problem"] --> Explore["/opsx:explore<br/>(optional)"]
    Idea --> Propose["/opsx:propose"]
    Explore --> Propose
    Propose --> Review{"Planning artifacts<br/>ready?"}
    Review -->|"Refine"| Update["/opsx:update"]
    Update --> Review
    Review -->|"Implement"| Apply["/opsx:apply"]
    Apply -->|"Plan changed"| Update
    Apply --> Archive["/opsx:archive"]
    Apply --> Verify["/opsx:verify<br/>(optional, custom selection)"]
    Apply --> Sync["/opsx:sync<br/>(optional before archive)"]
    Verify --> Verified{"Ready to archive?"}
    Verified -->|"Fix implementation"| Apply
    Verified -->|"Revise plan"| Update
    Verified -->|"Ready"| Sync
    Verified -->|"Ready"| Archive
    Sync --> Archive

AI 助手驱动工作流程，而 CLI 提供确定性的脚手架、状态和工件指令：

mermaid
sequenceDiagram
    actor Human
    participant Assistant as AI assistant
    participant CLI as OpenSpec CLI
    participant Files as Planning and implementation files

    Human->>Assistant: /opsx:propose "change"
    Assistant->>CLI: openspec new change
    CLI->>Files: Scaffold change metadata
    Assistant->>CLI: Request status and artifact instructions
    CLI-->>Assistant: Build order, paths, and templates
    Assistant->>Files: Write schema-defined planning artifacts
    Assistant-->>Human: Present artifacts for review

    Human->>Assistant: /opsx:apply
    Assistant->>CLI: Request apply instructions
    CLI-->>Assistant: Context files and task state
    Assistant->>Files: Implement tasks and update checkboxes
    Assistant-->>Human: Report implementation status

    Human->>Assistant: /opsx:archive
    Assistant->>CLI: Request archive inputs and artifact status
    CLI-->>Assistant: Planning paths and artifact completion
    Assistant->>Files: Read task state and compare delta specs
    opt Delta specs exist
        Assistant-->>Human: Offer to sync before archiving
        alt Sync accepted
            Human->>Assistant: Confirm sync
            Assistant->>Files: Merge delta specs into main specs
        else Sync skipped
            Human->>Assistant: Archive without syncing
        end
    end
    Assistant->>Files: Move the change into the archive
    Assistant-->>Human: Report archive location and sync result

    Note over Human,CLI: CLI alternative: openspec archive change-name --yes skips confirmation prompts. It still validates, then applies any delta specs and archives

两种模式 ​

默认快速路径 (core 配置方案) ​

新安装默认使用 core，它提供以下命令：

  • /opsx:explore
  • /opsx:propose
  • /opsx:apply
  • /opsx:update
  • /opsx:sync
  • /opsx:archive

典型流程：

text
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
  (optional)

从探索开始（值得养成的习惯） ​

/opsx:explore 是默认配置方案的一部分，而不是高级附加功能。当你有问题但还没有计划时，就应该进行这一步，而在有 AI 助手的情况下，这种情况占大多数。

text
You: /opsx:explore

AI:  What would you like to explore?

You: Our search results feel stale. I'm not sure if it's caching,
     indexing, or the query itself.

AI:  Let me look... [reads the search service and cache layer]
     It's the index: it only rebuilds nightly, so edits don't show
     up until the next day. Two options: rebuild on write (simple,
     more load) or a short-TTL cache invalidation (more moving parts,
     less load). Given your write volume is low, rebuild-on-write is
     the cleaner fix. Want to scope it?

You: Yes.

You: /opsx:propose rebuild-search-index-on-write

探索不会创建任何工件，也不会编写代码。这是一次免费且无风险的对话，能将模糊的担忧转化为精确的变更，从而使随后的提案更加精准。如果你已经确切知道想要什么？跳过它，直接进入 /opsx:propose。完整指南：Explore First。

扩展/完整工作流程（自定义选择） ​

如果你需要显式的脚手架和构建命令（/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard），请通过以下方式启用它们：

bash
openspec config profile
openspec update

工作流程模式（扩展模式） ​

快速特性开发 ​

当你清楚要构建什么，只需要执行时：

text
/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

示例对话：

text
You: /opsx:new add-logout-button

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

You: /opsx:ff

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

You: /opsx:apply

AI:  Working through tasks...
     ✓ Added logout button to header
     ✓ Implemented session clearing
     ✓ Added confirmation dialog
     All tasks complete!

You: /opsx:archive

AI:  ✓ Merged specs
     ✓ Archived change

最适合： 中小型特性、错误修复、简单的变更。

探索式 ​

当需求不明确或你需要先进行调查时：

text
/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply

示例对话：

text
You: /opsx:explore

AI:  What would you like to explore?

You: I want to improve page load performance but I'm not sure
     where the bottlenecks are.

AI:  Let me help investigate...
     [Analyzes bundle sizes, identifies slow queries, reviews
     component render patterns]

     I found three main bottlenecks:
     1. Large unoptimized images
     2. Synchronous data fetching in ProductList
     3. Re-renders from context changes

     Which would you like to address first?

You: Let's tackle the data fetching issue.

You: /opsx:new optimize-product-list-fetching

AI:  Created change. Ready to create: proposal

You: /opsx:continue

AI:  Creating proposal based on our exploration...
     [Writes proposal incorporating investigation insights]

     Ready to create: specs, design
     Which would you like next?

You: /opsx:continue

AI:  Creating specs...

最适合： 性能优化、调试、架构决策、需求不明确的情况。

并行变更 ​

同时处理多个变更：

text
Change A: /opsx:new ──► /opsx:ff ──► /opsx:apply (in progress)
                                         │
                                    context switch
                                         │
Change B: /opsx:new ──► /opsx:ff ──────► /opsx:apply

示例对话：

text
You: I'm working on add-dark-mode but got pulled into a bug fix

You: /opsx:new fix-login-redirect

AI:  Created openspec/changes/fix-login-redirect/

You: /opsx:ff

AI:  ✓ Created planning artifacts

You: /opsx:apply

AI:  Working on fix-login-redirect...
     [Implements the fix]
     All tasks complete!

You: /opsx:archive

AI:  ✓ Archived fix-login-redirect

You: Let's get back to dark mode

You: /opsx:apply add-dark-mode

AI:  Resuming add-dark-mode...
     Picking up at task 2.3: Update Header...

最适合： 并行工作流、紧急中断、团队协作。

当你有多个已完成的变更时，使用 /opsx:bulk-archive：

text
You: /opsx:bulk-archive

AI:  Found 3 completed changes:
     - add-dark-mode (all tasks done)
     - fix-login-redirect (all tasks done)
     - update-footer (all tasks done)

     Checking for spec conflicts...
     ⚠ add-dark-mode and update-footer both touch specs/ui/

     Inspecting codebase to resolve...
     Both changes are implemented. Will apply in chronological order.

     Archive all 3 changes?

You: Yes

AI:  ✓ Archived add-dark-mode
     ✓ Archived fix-login-redirect
     ✓ Archived update-footer
     Specs merged in order: add-dark-mode → update-footer

批量归档会检测多个变更是否触及相同的规范，并通过检查实际实现的内容来解决冲突。

完成变更 ​

推荐的完成流程：

text
/opsx:apply ──► /opsx:verify ──► /opsx:archive
                    │                 │
              validates          prompts to sync
              implementation     if needed

验证：检查工作成果 ​

/opsx:verify 从三个维度验证实施是否符合你的工件：

text
You: /opsx:verify

AI:  Verifying add-auth...

     COMPLETENESS
     ✓ All 12 tasks in tasks.md are checked
     ✓ All requirements in specs have corresponding code
     ⚠ Scenario "Session timeout after inactivity" not tested

     CORRECTNESS
     ✓ Implementation matches spec intent
     ✓ Edge cases from scenarios are handled
     ✓ Error states match spec definitions

     COHERENCE
     ✓ Design decisions reflected in code structure
     ✓ Naming conventions consistent with design.md
     ⚠ Design mentions "event-driven" but implementation uses polling

     SUMMARY
     ─────────────────────────────
     Critical issues: 0
     Warnings: 2
     Ready to archive: Yes (with warnings)

     Recommendations:
     1. Add test for session timeout scenario
     2. Consider refactoring to event-driven as designed, or update design.md

验证检查内容：

维度验证内容
完整性所有任务已完成，所有需求已实现，场景已覆盖
正确性实施符合规范意图，边缘情况已处理
一致性设计决策反映在代码结构中，模式保持一致

验证不会阻止归档，但它会显示你可能希望首先解决的问题。

归档：最终确定变更 ​

/opsx:archive 完成变更并将其移动到归档中：

text
You: /opsx:archive

AI:  Archiving add-auth...

     Artifact status:
     ✓ proposal.md exists
     ✓ specs/ exists
     ✓ design.md exists
     ✓ tasks.md exists (12/12 tasks complete)

     Delta specs: Not yet synced to main
     → Would you like to sync now?

You: Yes

AI:  ✓ Synced specs to openspec/specs/auth/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-auth/

     Change archived successfully.

如果规范未同步，归档将发出提示。它不会因为任务未完成而阻止操作，但会发出警告。

何时使用什么 ​

/opsx:ff 与 /opsx:continue ​

情况使用
需求明确，准备构建/opsx:ff
正在探索，希望审查每一步/opsx:continue
希望在规范之前迭代提案/opsx:continue
时间紧迫，需要快速推进/opsx:ff
复杂变更，希望掌控节奏/opsx:continue

经验法则： 如果你能提前描述完整的范围，请使用 /opsx:ff。如果你是边做边摸索，请使用 /opsx:continue。

何时更新 vs 从头开始 ​

一个常见的问题是：什么时候更新现有变更是可以接受的，什么时候应该开始一个新的变更？

当以下情况时更新现有变更：

  • 意图相同，执行方式更完善
  • 范围缩小（先 MVP，其余稍后）
  • 基于学习的修正（代码库与你预期的不同）
  • 基于实施发现的微调设计

当以下情况时开始新变更：

  • 根本意图发生了改变
  • 范围爆炸式增长到完全不同的工作
  • 原始变更可以独立标记为“完成”
  • 补丁会比澄清带来更多困惑
text
                     ┌─────────────────────────────────────┐
                     │     Is this the same work?          │
                     └──────────────┬──────────────────────┘
                                    │
                 ┌──────────────────┼──────────────────┐
                 │                  │                  │
                 ▼                  ▼                  ▼
          Same intent?      >50% overlap?      Can original
          Same problem?     Same scope?        be "done" without
                 │                  │          these changes?
                 │                  │                  │
       ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
       │                 │  │             │   │               │
      YES               NO YES           NO  NO              YES
       │                 │  │             │   │               │
       ▼                 ▼  ▼             ▼   ▼               ▼
    UPDATE            NEW  UPDATE       NEW  UPDATE          NEW

示例：“添加深色模式”

  • “还需要支持自定义主题” → 新变更（范围爆炸）
  • “系统偏好检测比预期的难” → 更新（意图相同）
  • “让我们先发布切换功能，稍后再添加偏好设置” → 更新然后归档，然后开始新变更

最佳实践 ​

保持变更聚焦 ​

每次变更只处理一个逻辑单元。如果你在做"添加功能 X 同时重构 Y"，建议拆分为两个独立的变更。

为什么这很重要：

  • 更易于审查和理解
  • 归档历史更清晰
  • 可以独立发布
  • 需要回滚时更简单

需求不明确时使用 /opsx:explore ​

在确定变更方案之前，先探索问题空间：

text
You: /opsx:explore

AI:  What would you like to explore?

You: How should we handle rate limiting for our API?

AI:  Let me investigate your current setup and options...
     [Researches codebase, considers patterns]

     I see three approaches we could take:
     1. Middleware-based (simple, per-endpoint)
     2. Redis-backed (scalable, shared state)
     3. Token bucket per user (fair, complex)

     Your current stack suggests #1 or #2. What's your scale?

探索有助于在创建工件之前理清思路。

归档前先验证 ​

使用 /opsx:verify 检查实现是否与工件一致：

text
You: /opsx:verify

AI:  Verifying add-dark-mode...

     ✓ All tasks in tasks.md are checked
     ✓ Requirements in specs have corresponding code
     ✓ Design decisions are reflected in implementation

     Ready to archive!

在关闭变更之前发现不匹配的问题。

清晰命名变更 ​

好的命名让 openspec list 更有用：

text
Good:                          Avoid:
add-dark-mode                  feature-1
fix-login-redirect             update
optimize-product-query         changes
implement-2fa                  wip

命令速查 ​

完整的命令详情和选项，请参阅 Commands。

命令用途使用时机
/opsx:propose创建变更及规划工件快速默认路径（core 配置）
/opsx:explore与 AI 一起梳理想法不确定时从这里开始：需求不明确、调查、比较方案
/opsx:new创建变更脚手架扩展模式，显式控制工件
/opsx:continue创建下一个工件扩展模式，逐步创建工件
/opsx:ff创建所有规划工件扩展模式，范围明确
/opsx:apply实现任务准备编写代码时
/opsx:verify验证实现扩展模式，归档前
/opsx:sync合并增量规格扩展模式，可选
/opsx:archive完成变更所有工作已完成
/opsx:bulk-archive批量归档多个变更扩展模式，并行工作

下一步 ​