openspec/
├─ specs/               # 当前系统行为规范
├─ changes/             # 正在进行中的增量工作区
│   ├─ account-auto-pricing/
│   │   ├─ proposal.md      # 为什么要Zuo
│   │   ├─ specs/
│   │   │   └─ account/
│   │   │       └─ spec.md   # 本次行为增量
│   │   ├─ design.md        # 怎么实现
│   │   └─ tasks.md         # 实施步骤清单
│   └─ order-status-notification/ ……
└─ archive/            # Yi完成变geng的历史归档



specs/ 保存系统当前Neng够执行的全部行为，是所有人共享的唯一真相。
changes/ 类似 Git 分支，每个子目录对应一个功Neng点。内部四个文件形成闭环，从「为什么」到「怎么Zuo」再到「怎么落地」。
archive/ 用时间戳或版本号命名，用来回溯过去的决策脉络。

2️⃣ 四大文档角色与衔接方式

文件名
职责定位
关键产出示例
proposal.md
阐明业务动因与价值诉求。
“玩家希望快速了解账号在二手市场的大概售价，以便决定是否出售。当前缺少统一报价导致用户流失率提升 12%。”
specs/.../spec.md
Delt​a Spec，只记录本次行为变化。
“新增 GET /api/v1/accounts/pricing 接口；返回 low/mid/high 三个价格区间以及样本数量。”
design.md
提供技术选型、架构图与关键决策依据。
“采用分位数算法计算价格；使用 Redisson 缓存 key=pricing:{game_type}:{level_bucket}；缓存 TTL=30min。”
tasks.md
把 design 拆解为可执行原子任务。
“① 在 account_transaction 表添加联合索引；② 实现 PricingRepository.findComparablePrices；③ 编写 PricingServiceTest…”

3️⃣ 场景驱动验证必不可少 

Scenario: 正常报价请求
  GIVEN Yi有至少 30 条同类账号成交记录
  WHEN 调用 GET /api/v1/accounts/pricing?gametype=LOL&level=30
  THEN 响应 body 包含 low、mid、high 三个数值且 samplesize>= 20

Scenario: 数据不足降级
  GIVEN 同类记录不足 5 条
  WHEN 调用同一接口
  THEN 返回字段 insufficient:true 且 HTTP 状态码 200


这些文字会被 /opsx:verify 自动解析，对照实际测试代码检查覆盖率，一旦发现缺口，就会在 CI 中报错。
4️⃣ Out of Scope 

No UI mockup design – 前端页面交互留给 UI 团队自行规划，仅提供接口合约。
No legacy data migration – 本章节只关注新功Neng实现，不涉及历史数据迁移脚本。
No third‑party payment integration – 定价服务不直接调用支付系统，相关联调另起章节说明。


三、成功标准—— 如何判断工作Yi完成？ 

/opsx:apply 完成且无错误日志：所有 tasks.md 中勾选项均Yi标记为 ✓，对应代码Yi提交至 main 分支。
/opsx:verify 全部通过：PASSED 场景数等于 spec 中列出的 Scenario 总数，且每个 GIVEN/WHEN/THEN dou匹配至少一条单元测试或集成测试。
/opsx:archive 成功归档：Delt​a Spec 被合并进 specs/account/spec.md，archive 中出现带时间戳的新目录，并且 proposal/design/tasks 均保持只读状态。
KPI 验证： 新增报价 API 的 P95 响应时间 ≤ 150ms； 功Neng上线后用户转化率提升 ≥ 8%； QA 回归缺陷 ≤ 2 条。
Linter & CI 检查通过：No lint errors in markdown files; CI pipeline shows “OpenSpec Check” step passed.

当上述全部条件满足时我们Ke以自信地说：「这个功NengYi经按照 OpenSpec 流程完成，从需求捕获到代码交付再到历史归档，dou留下了完整且可机器读取的痕迹。」

四、一点情绪温度——为什么你会爱上这套结构？ 
    想象一下当你凌晨两点打开仓库，只kan到一堆散乱的 .md 文件时会不会心里一阵阵发凉？而Ru果眼前是一排整齐划一的文件夹，每个子目录dou像是一本小册子——先讲「为什么要这样」，再说「我们到底怎么干」，Zui后列出“一步一步该干啥”。这种层层递进带来的安全感，会让你瞬间摆脱焦虑，甚至对即将开始的新特性充满期待。团队成员之间不再因为「我kan不到需求细节」而争执，因为所有答案dou藏在同一个 change 子目录里只要点开就Nengkan到完整脉络。AI 同事也会因为上下文足够丰富而geng靠谱，你不再需要不停纠正它跑题，而是让它在明确边界里自由发挥，这种协同感真的hen让人激动！😊 

五、快速上手示例 

$ openspec init
$ openspec propose account-auto-pricing
$ opsx:apply          # AI 根据 tasks 自动生成代码
$ opsx:verify         # 检查 G/W/T 场景是否被测试覆盖
$ opsx:archive        # 合并 Delta Spec 到 specs/, 移入 archive/


* 小技巧：Ru果你想临时修改某个决策，只需要回到对应 change 子目录重新编辑 proposal 或 design，然后重新跑一次 apply → verify → archive 即可，无需手工改动主规格库里的旧内容。

六、 
    OpenSpec 并不是一种枯燥的模板，它是一套帮助团队把「思考」写进文件，把「执行」写进任务，把「回顾」写进历史的方法论。尤其一旦把每一次功Neng升级dou封装进独立且自洽的 change 文件夹，你会惊讶于它带来的透明度和速度提升。别忘了在每一次提交前，让 G/W/T 场景说话，让 AI 按规矩编码，让 CI 为你的决定保驾护航——这样，你就真正拥有了一条从需求到价值闭环的高速公路。
🚀 开始使用 OpenSpec，让你的项目从此不再迷路！ 🚀