第 07 章 | OpenSpec 的世界观

第 7 章：OpenSpec 的世界观

学习目标

理解为什么 OpenSpec 不是"普通文档系统"——而是一套规约的版本管理系统。

三个目录 = 三种身份

flowchart TB
    subgraph Now["当下"]
        Specs["specs/
系统现在承诺什么
(单一真相)"]
    end

    subgraph WIP["进行中"]
        Changes["changes/active/
正在评审/实现的变更
(delta 形式)"]
    end

    subgraph Past["历史"]
        Archive["changes/archive/
已完成的变更
(完整快照)"]
    end

    Changes -->|/opsx:archive| Archive
    Archive -.->|delta 合并| Specs

    style Now fill:#c8e6c9
    style WIP fill:#fff9c4
    style Past fill:#e1bee7

Git 类比（最快理解的方式）

→ specs 是"代码"，change 是"PR"，archive 是"git log"。

一次完整生命周期

sequenceDiagram
    participant U as 用户
    participant E as opsx:explore
    participant P as opsx:propose
    participant Files as 文件系统
    participant A as opsx:apply
    participant Ar as opsx:archive

    U->>E: "我想加 OAuth"
    E->>U: 澄清问题、聊清楚
    U->>P: 确认了，做这个 change
    P->>Files: changes/add-oauth/{proposal,design,specs,tasks}
    U->>A: 按 tasks.md 实现
    A->>Files: src/ + tasks.md 勾选
    U->>Ar: 完成
    Ar->>Files: change 移动到 archive/
    Ar->>Files: specs/auth.md 合并 delta

为什么这样设计能"防需求漂移"

普通做法的问题：

你今天写 PRD 在 Notion       ── 6 个月后没人记得改过几次
ticket 在 Jira              ── 2 年后 Jira 过期，链接全坏
代码 commit 在 git          ── 知道"改了什么"，不知道"为什么"

→ 三套系统漂移、撕裂、对不上号

OpenSpec 把这些绑在一起：

changes/archive/2026-04-add-oauth/
├── proposal.md      ← 取代 Notion 的 PRD
├── design.md        ← 取代设计文档
├── tasks.md         ← 取代 Jira 的 ticket 列表
└── specs/auth.md    ← 这次改了 spec 的哪几条

加上 git commit 关联，代码也能从 change 反查回来。一个文件夹 = 一次完整的"为什么 + 怎么做 + 改了什么"。

Delta 是关键

changes/<name>/specs/auth.md 不是完整 spec，是变更。例子：

## ADDED Requirements

### Requirement: 用户支持 OAuth 登录
系统 SHALL 支持 Google / GitHub OAuth 流程。

#### Scenario: Google 成功授权
- WHEN 用户在登录页点击"用 Google 登录"
- THEN 跳转到 Google OAuth 页面，授权后回到 /callback

archive 时，OpenSpec 把这段合并进 specs/auth.md——后者才是完整 spec。

一句话总结这章

specs 是"系统的当前镜像"，archive 是"事件流"，change 是"事件流里正在编辑的那一条"。

→ 跟数据库的 schema migration 系统一模一样。区别是：migration 管的是数据，OpenSpec 管的是需求。

你现在能做什么

• 解释 specs/changes/archive 各自身份
• 用 Git 类比向同事讲清楚 OpenSpec
• 知道为什么 delta 要单独存，而不是写完整 spec

下一章开始动手——用 explore 模式探索我们的第一个想法。