OpenSpec 实战教程：单体服务 vs 微服务多仓库
在 AI 能秒写代码的时代，OpenSpec 解决的是另一件事：先对齐「要做什么」，再动手写代码。
本文是一份可照着做的教程，重点区分两种最常见的落地形态：单体服务（单仓库） 与 微服务多仓库。
文章目录
- OpenSpec 实战教程：单体服务 vs 微服务多仓库
- order-service API Contract（示例骨架）
-
- POST /api/orders
- 日常实战：环境就绪后，新需求怎么操作
- 6. 两种场景对比与选型
- 7. 与 AGENTS.md 的分层配合
- 8. 常用 CLI 与 Slash 命令速查
- 9. 常见问题
-
- Q1：是不是 waterfall？
- Q2：老项目要先写完全部 spec 吗？
- Q3：换 AI 工具后 spec 还有用吗？
- Q4：微服务能否一个 change 自动改多个仓库？
- Q5：每个微服务都要 `store setup` 吗？
- Q6：openspec/ 和 docs/api-contracts/ 重复了怎么办？
- Q7：小 bug 也要走完整流程吗？
- Q8：Stores beta 稳定吗？
- Q9：`platform.code-workspace` 是什么格式？
- Q10：没有 Git 能玩 OpenSpec 吗？
- Q16：Git 是必选的吗？
- Q11：需求是一篇飞书长文档，怎么完整输入？
- Q12：`openspec init` 应该在哪个目录执行？
- Q13：`openspec` 命令需要每个项目装一次吗？
- Q14：终端报 `openspec: command not found`？
- Q15：platform-docs 的 AGENTS.md 要从哪里复制？
- Q17：Cursor / Claude / Trae / Codex 命令不一样怎么办？
- Q18：环境搭好了，来了新需求第一步做什么？
- 10. 参考链接
- 附录：快速启动命令清单
1. OpenSpec 是什么
OpenSpec 是一套轻量级的 规范驱动开发（Spec-Driven Development） 框架，专为 AI 编程助手设计。核心理念：先对齐，再开工（agree first, then build confidently）。
与 Agent 内置的「Plan 模式」不同，OpenSpec 的规范会 持久化在项目目录里的 Markdown 文件（openspec/specs/、openspec/changes/），跨会话、跨人、跨工具都能复用。Git 非必选：个人本地目录即可跑通全流程；团队协同时再用 Git 做版本管理与 PR review（见 §3.1.1）。
解决什么问题
| 痛点 | OpenSpec 的做法 |
|---|---|
| AI 理解错需求，写了 400 行错代码 | 先产出 proposal + delta spec，人工 review 后再 implement |
| 聊天上下文结束，意图丢失 | specs 库是活文档，新会话直接读 spec |
| 老项目改功能，不知现状 | delta spec 只描述「变更」，不必先文档化整个世界 |
| 微服务跨仓库，规划散落各处 | platform-docs 仓库承载 OpenSpec（Stores beta） |
两种落地形态（先建立这个心智模型）
OpenSpec 在工程里只有两种标准落地方式，不是三套并行方案：
| 形态 | OpenSpec 放哪 | 一句话 |
|---|---|---|
| 单体服务 | 业务仓库根目录 openspec/ |
一个仓库、一个真相源 |
| 微服务多仓库 | platform-docs 仓库 + 各服务仓库 references |
跨服务规范在 platform-docs；各服务管本仓实现 change |
微服务场景下，OpenSpec（+ platform-docs） 就是官方 Stores 机制在你团队里的具体实现：
platform-docs= 平台文档仓库（AGENTS.md、platform.code-workspace、依赖图、联调说明；是否用 Git 管理该目录由团队决定）platform-docs/openspec/= 跨服务 活规范（specs 库 + 协同 changes）- 各微服务仓库
openspec/config.yaml里references: [platform-docs]= 读上游规范（可选；默认用 workspace 打开 platform-docs 即可，服务仓可无 openspec）
下文 不要 再另建与 platform-docs 并行的第二套规划仓库；Store 注册 id 建议与仓库名一致，即 platform-docs。
两种命令，两个地方
这是新手最常踩的坑：
| 类型 | 在哪里执行 | 示例 |
|---|---|---|
| CLI 命令 | 终端 | openspec init、openspec list |
| Slash 命令 | AI 助手聊天框 | 写法因工具而异，见 §3.5 |
2. 核心概念（5 分钟读懂）
2.1 五个核心概念
┌─────────────────────────────────────────────────────────────────┐
│ openspec/ │
│ │
│ ┌──────────────────┐ ┌──────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ ◄───── │ │ │
│ │ 真相：系统现在 │ archive │ 提案：这次要改什么 │ │
│ │ 应该怎样工作 │ 合并 │ proposal·design·tasks │ │
│ └──────────────────┘ └──────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
| 概念 | 说明 |
|---|---|
| Specs | 系统当前行为的「真相」，按领域组织在 openspec/specs/ |
| Change | 一次变更单元，文件夹在 openspec/changes/<name>/ |
| Delta Spec | 变更内的规范增量：ADDED / MODIFIED / REMOVED |
| Artifacts | proposal（为什么）→ specs（改什么）→ design（怎么做）→ tasks（步骤） |
| Archive | 完成后 delta 合并进 specs，change 移入 archive/ |
2.2 Delta Spec 示例
# Delta for Auth
## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.
#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented
## MODIFIED Requirements
### Requirement: Session Timeout
The system SHALL expire sessions after 30 minutes of inactivity.
(Previously: 60 minutes)
2.3 标准工作流
/opsx:explore → （可选）先探索、理清思路
/opsx:propose <name> → AI 生成 proposal、delta spec、design、tasks
（人工 review 计划）
/opsx:apply → AI 按 tasks 实施
/opsx:archive → delta 合并进 specs，变更归档
OpenSpec 强调 enablers, not gates：实施中发现设计不对，直接改 design.md 继续，没有僵化的瀑布门禁。
2.4 长篇需求输入（飞书文档 / PRD）
真实需求很少是一句话：常见是一篇 飞书云文档（背景、用户故事、流程图、接口草稿、排期、非功能要求混在一起）。OpenSpec 的做法不是「把整篇 PRD 一次性变成 specs」，而是：
原始 PRD（飞书） → explore 消化 + 划范围 → propose 产出精简的 change 工件 → review → apply
原则：飞书文档是 输入材料；proposal.md / delta spec.md 是 可测试、可归档的规范。前者可以很长，后者要短、结构化。
2.4.1 把飞书内容送进 Cursor 的三种方式
| 方式 | 适用 | 做法 |
|---|---|---|
| A. 链接 + Agent 读取 | 已配飞书 MCP / lark-cli |
聊天里贴飞书 docx/wiki URL，让 Agent 拉正文后再 /opsx:explore |
| B. 导出 Markdown 落库（推荐） | 团队常态、要留痕 | 飞书 导出 Markdown 或复制到仓库固定目录，用 @文件 引用 |
| C. 摘要粘贴 | 文档很短或你已读完 | 只贴「目标 + 验收标准 + 约束」，附原文链接 |
团队落地时，B 最稳：PRD 落库到 docs/requirements/（使用 Git 时便于 PR review），用 @ 引用进 Cursor，不依赖聊天窗口长度。
2.4.2 推荐落库位置
单体（my-monolith/）：
docs/requirements/REQ-2026-001-checkout-promo.md # 原始 PRD（可很长）
openspec/changes/add-checkout-promo/
├── sources/
│ └── prd.md # 可选：本 change 专用副本或链接
├── proposal.md # 摘要 + 指向 REQ 的链接
└── ...
微服务（规范在 platform-docs）：
platform-docs/
├── docs/requirements/REQ-2026-001-checkout-promo.md
└── openspec/changes/add-checkout-promo/
├── sources/prd.md
└── ...
proposal.md 开头建议固定写 来源，便于 archive 后追溯：
## Sources
- PRD: docs/requirements/REQ-2026-001-checkout-promo.md
- 飞书原文: https://xxx.feishu.cn/docx/...
2.4.3 推荐流程（飞书 PRD → OpenSpec change）
Step 1：落库（一次）
- 飞书文档导出 Markdown，或让 Agent 读取 URL 后 写入
docs/requirements/REQ-xxx.md（不要只留在聊天里）。 - 文件名带需求编号，正文保留飞书里的章节结构即可，不必先改写成 OpenSpec 格式。
Step 2：explore（强烈建议，尤其微服务）
在 Cursor 中（workspace 已打开代码 + platform-docs 时）：
/opsx:explore
请阅读 @docs/requirements/REQ-2026-001-checkout-promo.md
结合现有代码与 docs/service-dependencies.md（微服务场景），输出：
1. 本需求目标与明确不在范围内的内容
2. 涉及哪些服务 / 模块
3. 与现有 spec 或实现的冲突点、待澄清问题（编号列出）
4. 建议拆成几个 change（若文档过大）
先不要写 proposal，只探索。
explore 阶段可以 多轮：先消化 PRD，再读代码，再追问产品——比直接 /opsx:propose 少返工。
Step 3：propose（带完整上下文）
/opsx:propose add-checkout-promo
依据 @docs/requirements/REQ-2026-001-checkout-promo.md 与刚才 explore 的结论，
生成本 change 的 proposal、design、tasks、delta spec。
tasks 按 [order-service] 等分段（微服务）。
proposal 的 Sources 章节写上 PRD 路径与飞书链接。
只覆盖本 change 范围，不要把 PRD 里「下期再做」的内容写进 spec。
用 @ 引用本地 Markdown，比粘贴几万字进聊天框更可靠；Agent 会按需重读文件。
Step 4：人工 review
Review 对象是 change 工件，不是整篇飞书：
proposal.md：范围对不对？有没有把 PRD 以外的东西写进来？- delta
spec.md：需求是否可测试（Scenario 是否够具体）？ tasks.md：粒度是否可验证？
飞书 PRD 里含糊的句子，应在 review 时 改 spec 或回飞书澄清，不要留到 apply。
2.4.4 一篇飞书文档 ≠ 一个 change
若 PRD 包含多个独立能力（例如「促销码 + 会员等级 + 结算改造」），应 拆多个 change：
add-checkout-promo ← 本期只做促销码
add-member-tier-pricing ← 下期
每个 change 各自 propose → review → apply → archive。不要试图一次 propose 吞掉整本文档——delta spec 会臃肿，review 也会失效。
判断是否要拆：
| 信号 | 建议 |
|---|---|
| PRD 有独立章节、可独立上线 | 拆 change |
| 涉及多服务但 同一业务故事、同一 PR | 一个 change，tasks 分段 |
| 验收标准无法在一次发布内完成 | 拆 change 或砍 scope |
2.4.5 上下文与长度注意
| 问题 | 做法 |
|---|---|
| 聊天塞不下整篇 PRD | 落库 + @文件，或只 @ PRD 相关章节拆成的多个 md |
| 飞书里有大量截图 / 流程图 | 图导出放 docs/requirements/assets/，PRD 里用相对路径引用；explore 时 @ 图片 |
| 表格、接口附录很长 | 保留在 docs/requirements/，spec 里只写 行为与 Scenario；细节链到 PRD 或 docs/api-contracts/ |
| 希望 Agent 默认知道 PRD 放哪 | 在 openspec/config.yaml 的 context 里写：原始需求见 docs/requirements/，propose 前必须先读 Sources |
2.4.6 与「不要 bulk 转换」的关系
§4.4 提到：已有 PRD 不要一次性 bulk 转成全部 specs。正确姿势是：
- 整篇 PRD 可以 原样归档 在
docs/requirements/（输入层） - 每次只做 当前 change 的 delta spec（规范层）
- archive 多次后，
openspec/specs/自然覆盖到 PRD 涉及的能力，无需预先全量迁移
2.4.7 微服务场景补充
跨服务 PRD 仍在 platform-docs 落库与 propose；各微服务仓 不需要 复制 PRD。流程：
docs/requirements/REQ-xxx.md在 platform-docsplatform.code-workspace打开各服务代码- explore / propose 在 platform-docs 上下文执行，Agent 通过多根读
order-service/src等 - 飞书链接写在
proposal.md，方便产品同事对照
详见 5.7 跨服务功能完整流程。
3. 安装与初始化
3.1 前置条件
- Node.js 20.19.0+（
node --version检查）
3.1.1 Git 非必选
OpenSpec 全流程不依赖 Git。 openspec init、store setup、/opsx:explore～/opsx:archive 在普通本地文件夹即可运行。
| 场景 | 是否需要 Git |
|---|---|
| 个人试玩、自学、单机 demo | 否 |
| 本地 mkdir + Cursor + OpenSpec | 否 |
队友共享 Store、store register |
否（同一台机多人可各用本机路径；跨机器协作才常配合远程仓） |
| 规范 / 代码 PR review、审计、回滚 | 是（团队常规做法，非 OpenSpec 硬性要求） |
微服务初始化时：创建平台模板 与 git init 分开；Step 5～6 整段可跳过。详见 §5.4、§5.11。
3.2 全局安装 CLI（推荐）
OpenSpec 推荐全局安装 CLI：在本机装 一次，任意仓库里都能执行 openspec init、openspec list 等。这与「每个项目根目录里的 openspec/」是两件事（见下表）。
全局 CLI vs 项目内 openspec/
| 层级 | 装在哪 | 命令 / 路径 | 次数 |
|---|---|---|---|
| CLI（全局） | 本机（npm 全局目录） | openspec 命令 |
每台机器装一次 |
| 项目配置（本地） | 仓库根目录 | openspec/、.cursor/commands/ |
每个要用的仓库 init 一次（微服务默认只有 platform-docs） |
全局装 CLI 不会自动给微服务父目录或 docs/ 子目录生成 openspec/——仍须在正确仓库根执行 openspec init（见 §3.3.1）。
安装命令（任选本机已有包管理器）
npm（最常见）
npm install -g @fission-ai/openspec@latest
openspec --version
其它包管理器
pnpm add -g @fission-ai/openspec@latest
bun add -g @fission-ai/openspec@latest
yarn global add @fission-ai/openspec@latest # 仅 Yarn 1.x；Yarn 2+ 请用 npm/pnpm/bun
Nix 用户
nix run github:Fission-AI/OpenSpec -- init
详见官方 Installation。
不全局安装（临时试玩）
不想全局装时，可用 npx 单次执行（适合体验，日常开发仍建议全局装）：
npx @fission-ai/openspec@latest --version
npx @fission-ai/openspec@latest init --tools cursor
安装后验证
openspec --version # 应输出版本号
which openspec # macOS/Linux：确认命令路径
openspec: command not found
CLI 已装但终端找不到命令时，多半是 全局 npm 的 bin 目录不在 PATH：
npm prefix -g # 查看全局安装根目录
# macOS/Linux：将「上述路径/bin」加入 PATH（例如 ~/.zshrc）
# Windows：将上述路径本身加入 PATH
安装需 sudo 或权限报错时，优先检查 npm 全局目录权限，或改用用户级全局前缀（npm config get prefix），不要贸然改系统目录。官方 troubleshooting 见 Installation — Troubleshooting。
3.3 初始化项目
cd your-project # 见 3.3.1：必须是 Agent 工作区对应的仓库根
openspec init --tools <id> # 见 3.5：cursor / claude / trae / codex 等
openspec init 会创建：
openspec/目录（specs、changes）- 所选 Agent 的 skills / commands 文件（路径与触发方式因工具而异，见 §3.5）
- 可选的
openspec/config.yaml
以上文件都落在「执行 init 时终端所在的目录」，不会自动挂到上级或兄弟目录。目录选错会导致：终端里 openspec list 找不到、聊天里没有 OpenSpec 命令。详见 §3.3.1。
3.3.1 openspec init 必须在哪个目录执行
一句话：在 你打算当作 OpenSpec 工作区根的那一层 执行 openspec init --tools <id>（见 §3.5）——终端 cwd 与 Agent 打开的文件夹根 必须一致。
规则
| 场景 | 正确目录（在此 cd 后 init） |
错误示例 |
|---|---|---|
| 单体 | 业务仓库根，如 my-monolith/ |
my-monolith/docs/、my-monolith/src/ |
| 微服务 | platform-docs 仓库根 |
微服务父目录 parent/、子目录 platform-docs/docs/、各 order-service/ |
openspec init 会在 当前目录 创建：
./openspec/
./.cursor/commands/opsx-*.md # 仅 init --tools cursor 时；Claude 为 .claude/…，见 §3.5
OpenSpec CLI 从当前目录 向上查找 最近的 openspec/。若 init 在错误位置：
- 在 父目录
parent/打开 Cursor 或执行 CLI → 看不到platform-docs/openspec/ - 在
docs/下误 init →openspec/和.cursor/落在docs/里，与平台文档混在一起，且 platform-docs 根 打开时没有 slash 命令
磁盘布局对照（微服务）
parent/ ← ❌ 不要在这里 init
├── platform-docs/ ← ✅ init 在这里（仓库根）
│ ├── openspec/ ← init 生成
│ ├── .cursor/commands/ ← init 生成，/opsx:* 依赖此路径
│ ├── AGENTS.md
│ ├── platform.code-workspace
│ └── docs/ ← ❌ 不要在这里 init（只是普通文档目录）
├── order-service/ ← ❌ 默认不要 init（见 5.2.1）
└── inventory-service/
与 Cursor 打开方式的关系
| Cursor 打开方式 | init 应在哪里执行 |
|---|---|
单文件夹：cursor my-monolith |
my-monolith/ 根 |
单文件夹：cursor platform-docs |
platform-docs/ 根 |
Workspace：cursor platform.code-workspace |
platform-docs 根（OpenSpec Store）；各服务根 无需 init |
Multi-Root Workspace 下，每个根目录各自有一套 .cursor/。/opsx:propose 等命令出现在 执行过 init 的那个根（微服务场景 = platform-docs）。在 order-service 根单独聊天时，通常 没有 /opsx:*——跨服务规划应在 platform-docs 上下文或整个 workspace 里做。
实操检查（init 后立刻做）：
# 应在 platform-docs 根（或单体仓库根）执行
pwd
ls openspec .cursor/commands
openspec list # 应正常，无「找不到 openspec」
然后在 同一目录 打开 Cursor：
cursor . # 单体或 platform-docs 单根
# 或
cursor platform.code-workspace # 微服务多根（workspace 文件在 platform-docs 内）
聊天框应能输入 OpenSpec 命令（拼写见 §3.5）。若看不到，多半是 init 目录与打开根不一致，或需要 openspec update 并重启 Agent。
已经 init 错目录怎么办
- 确认误生成的
openspec/、/.cursor/commands/opsx-*位置（例如在docs/下）。 - 删除错误位置的
openspec/与误放的.cursor/commands/opsx-*（勿删团队其它.cursor配置）。 cd到正确仓库根，重新openspec init --tools <你的 Agent id>。- 微服务场景：在 platform-docs 根 再执行
openspec store setup --path "$(pwd)"（若 Store 曾指向错误路径，需修正或重做 setup）。
3.4 升级 CLI 与刷新项目内命令
两步：先升级 全局 CLI，再在 各已 init 的仓库根 刷新 slash 命令等本地文件。
# 1. 升级全局 CLI（与 3.2 相同命令）
npm install -g @fission-ai/openspec@latest
openspec --version
# 2. 进入已 init 的仓库根（单体仓或 platform-docs）
cd your-project
openspec update
微服务场景：通常只需在 platform-docs 根 执行 openspec update；各微服务仓若无 openspec/ 则无需执行。
3.5 不同 AI 编码 Agent（Cursor / Claude / Trae / Codex）
OpenSpec 同一套 openspec/ 规范与 CLI，但各 Agent 的 init 参数、生成文件路径、聊天里怎么敲命令 不同。openspec init 会为所选工具生成对应适配文件——以生成文件与 init 结束时的提示为准，不要死记一种写法。
官方参考：Supported Tools、How Commands Work、Commands。
3.5.1 总览对比
| Agent | openspec init 的 --tools id |
聊天里怎么触发（core 工作流） | 项目内主要生成路径 |
|---|---|---|---|
| Cursor | cursor |
/opsx-propose、/opsx-apply（连字符） |
.cursor/commands/opsx-*.md、.cursor/skills/openspec-*/ |
| Claude Code | claude |
/opsx:propose、/opsx:apply（冒号，opsx/ 子目录） |
.claude/commands/opsx/*.md、.claude/skills/openspec-*/ |
| Trae | trae |
/opsx-propose、/opsx-apply（与 Cursor 同类） |
.trae/commands/opsx-*.md、.trae/skills/openspec-*/ |
| Codex CLI | codex |
$openspec-propose、$openspec-apply-change（$ + skill 名） |
.agents/skills/openspec-*/（无 opsx-* 命令文件） |
教程下文为便于阅读，canonical 写法用 Claude 风格的 /opsx:propose；你用 Cursor / Trae 时改为 /opsx-propose，Codex 改为 $openspec-*（见下表）。
3.5.2 core 工作流：四种 Agent 命令对照
| 意图 | Claude Code | Cursor / Trae | Codex CLI（skill） |
|---|---|---|---|
| 探索（可选） | /opsx:explore |
/opsx-explore |
$openspec-explore |
| 提案 | /opsx:propose <name> |
/opsx-propose <name> |
$openspec-propose |
| 实施 | /opsx:apply |
/opsx-apply |
$openspec-apply-change |
| 更新规划工件 | /opsx:update |
/opsx-update |
$openspec-update-change |
| 同步 spec | /opsx:sync |
/opsx-sync |
$openspec-sync-specs |
| 归档 | /opsx:archive |
/opsx-archive |
$openspec-archive-change |
Codex 不识别 /opsx:* 或 /openspec-* 作为命令前缀时，用 $ 触发（init 完成时终端会打印准确拼写）。
3.5.3 初始化示例
在 仓库根（单体仓或 platform-docs）执行，按你实际用的 Agent 选一个或多个 id：
# 只配一种
openspec init --tools cursor
openspec init --tools claude
openspec init --tools trae
openspec init --tools codex
# 同一仓库多人用不同 Agent（会生成多套 skills/commands，互不冲突）
openspec init --tools cursor,claude,trae,codex
# 查看全部 id
openspec init --help
升级 OpenSpec 后，在已 init 的仓库根执行 openspec update，会按 config.yaml 里已选工具 刷新 对应 skills/commands。
3.5.4 各 Agent 使用差异（实操）
Cursor
- 打开项目：
cursor .或cursor platform.code-workspace（微服务 Multi-Root，见 §5.4.1）。 - 命令：聊天框输入
/opsx-propose，依赖.cursor/commands/opsx-*.md。 - 注意：init 目录必须与 Cursor 打开的根一致（§3.3.1）；看不到命令时 重载窗口 或重启 Cursor，并确认
openspec update已执行。
Claude Code
- 打开项目：在终端
cd到仓库根，用 Claude Code 在该目录启动会话。 - 命令：
/opsx:propose（文件在.claude/commands/opsx/下，带 冒号 命名空间）。 - 注意：与 Cursor 混用时 init 会同时生成
.claude/与.cursor/，openspec 内容只有一份，两套入口读同一openspec/。
Trae
- 打开项目：在 Trae 中打开仓库根或 workspace（Trae 为 IDE 类工具，路径与 Cursor 类似）。
- 命令：
/opsx-propose等（生成在.trae/commands/），语法与 Cursor 同属「文件名即命令」 一类，不是 Claude 的/opsx:。 - 注意：微服务仍建议 platform-docs 根 init；跨服务改代码需能同时访问各服务目录（workspace 或多根打开方式以 Trae 当前能力为准）。
Codex CLI
- 打开项目：终端进入仓库根，在 Codex 会话中工作；规范仍在
openspec/。 - 命令：仅 skills，聊天里用
$openspec-propose、$openspec-apply-change等；不会生成.cursor/commands或 Codex 的opsx-*文件。 - 生成位置：
.agents/skills/openspec-*/SKILL.md（与部分工具的共享 skills 根相同；若同时 initcodex与agents，OpenSpec 会合并处理，见官方 Supported Tools）。 - 注意：旧版可能在用户目录有
~/.codex/prompts/opsx-*；openspec init可能清理旧文件，init 前可先备份自定义 prompt。
3.5.5 终端 vs 聊天（所有 Agent 通用）
| 在哪里 | 做什么 | 示例 |
|---|---|---|
| 终端 | 装 CLI、init、list、validate、store | openspec init --tools cursor |
| Agent 聊天 | 跑工作流 | Cursor：/opsx-propose；Claude：/opsx:propose；Codex：$openspec-propose |
混用是最常见踩坑：在终端跑了 init，却到另一个未配置该工具的 IDE 里找 /opsx:*——应在 init 时选了该工具 的 Agent 里触发，或 openspec init --tools 补上该工具后 openspec update。
3.5.6 微服务场景与 Agent 选择
| 事项 | 说明 |
|---|---|
| OpenSpec Store 位置 | 仍在 platform-docs 根 init，与 Agent 品牌无关 |
| 跨仓改代码 | Cursor / Trae 用 platform.code-workspace 最顺手；Claude / Codex 需在会话中能读多目录或通过 workspace 打开父目录 |
| 团队混用 | openspec init --tools cursor,claude,trae,codex，同一 openspec/ 一套规范，各人用自己 Agent 的入口 |
| Git | 与 Agent 无关，仍 非必选 |
4. 场景一：单体服务（单仓库）
4.1 适用条件
- 一个仓库 = 一个可部署单元（常见为单 Git 仓；OpenSpec 不要求 Git）
- 典型：Spring Boot 单体、Django 全栈、Next.js 全栈应用
- 团队规模小到中，无跨仓库协作需求
4.2 推荐目录结构
my-monolith/
├── src/ # 业务代码
├── openspec/
│ ├── config.yaml # 项目约定、context
│ ├── specs/ # 活文档：按功能域组织
│ │ ├── auth/
│ │ │ └── spec.md
│ │ ├── orders/
│ │ │ └── spec.md
│ │ └── payments/
│ │ └── spec.md
│ └── changes/
│ ├── add-guest-checkout/ # 进行中的变更
│ └── archive/ # 已归档变更
├── AGENTS.md # Agent 静态上下文（可选）
└── .cursor/
└── commands/opsx-*.md
领域划分建议（按团队心智模型，不必事先设计完整 taxonomy）：
- 按功能域：
auth/、orders/、payments/ - 按分层：
api/、domain/、workers/（若团队按层思考）
4.3 从零到第一次变更（完整教程）
假设项目是一个电商单体，要给登录加「记住我」功能。
Step 0：初始化（若尚未 init）
cd my-monolith # 仓库根，与 Agent 打开的目录一致
openspec init --tools cursor # 或 claude / trae / codex，见 §3.5
目录要求见 §3.3.1。
Step 1：配置项目上下文（推荐）
编辑 openspec/config.yaml，让 AI 提案时尊重你的技术栈：
# openspec/config.yaml
context: |
Java 17 + Spring Boot 3 单体应用。
分层：Controller → Service → Repository。
会话存 Redis，Cookie 策略遵循现有 SecurityConfig。
编码规范见根目录 AGENTS.md。
Step 2：探索（可选但强烈推荐）
在 Agent 聊天框（Cursor 示例；其它工具见 §3.5）：
/opsx:explore
我想给登录加「记住我」，延长会话到 30 天。
请先读现有 auth 相关代码和 SecurityConfig，告诉我插入点在哪。
AI 会读代码、梳理现状，避免提案脱离实际结构。
Step 3：提案
/opsx:propose add-remember-me
生成目录：
openspec/changes/add-remember-me/
├── proposal.md # 为什么做、范围、方案概要
├── design.md # Cookie 策略、Redis key 设计
├── tasks.md # 可勾选任务清单
└── specs/
└── auth-session/
└── spec.md # delta：ADDED/MODIFIED requirements
人工 review 重点：
proposal.md：范围是否对？有没有过度设计？specs/auth-session/spec.md：只看规范 diff，不必翻代码tasks.md：粒度是否可独立验证？
Step 4：实施
/opsx:apply
AI 按 tasks.md 逐项实施并勾选。若实施中发现设计需调整：
- 直接编辑
design.md或tasks.md - 继续
/opsx:apply或让 AI 接着做
Step 5：归档
/opsx:archive
结果：
openspec/specs/auth-session/spec.md已包含「记住我」需求changes/add-remember-me/移至changes/archive/2026-08-14-add-remember-me/
Step 6：终端验证
openspec list
openspec show add-remember-me # 若仍在 active
openspec validate add-remember-me
openspec view # 交互式仪表盘
之后每个新需求按 日常实战 重复 explore → propose → apply → archive。
4.4 存量项目（Brownfield）要点
不必先文档化整个系统。 OpenSpec 是 brownfield-first：
- 选一个 本周真要做的 小改动
/opsx:explore让 AI 读相关代码/opsx:propose只写这一块 delta- archive 后，specs 自然「长」出来
已有 PRD/SRS？当作 explore 的输入材料，不要一次性 bulk 转换。长篇飞书文档的落库、@ 引用与拆 change 见 §2.4。
首次上手可用扩展命令 /opsx:onboard（需先 openspec config profile 启用 expanded workflows）。
4.5 单体场景最佳实践
| 实践 | 说明 |
|---|---|
| 小步 archive | 每个 change 做完即 archive；使用 Git 时 可与代码变更同一 PR 合并 |
| specs 落盘保存 | openspec/specs/、archive/ 是工程资产（Git 可选，见 §3.1.1） |
| 一个 change 一件事 | 避免「大杂烩 change」难以 review |
| trivial fix 可跳过 | 改 typo、一行 bug 不必走完整流程 |
| 用 explore 防跑偏 | 老代码库里，探索比直接 propose 省大量返工 |
日常每个新需求的标准流程见 日常实战。
5. 场景二：微服务多仓库（OpenSpec + platform-docs）
5.1 适用条件
- 每个微服务 独立仓库（常见为独立 Git 仓；OpenSpec 本身不要求 Git）
- 一次需求常跨多个服务（改 Event、改 API、改网关路由）
- 平台团队维护公共契约，各服务团队各自 implement
- 需要 规划与代码解耦、多人协作 review 规范
5.2 标准形态：OpenSpec + platform-docs
微服务多仓库的 默认推荐实现 只有一种：
在 platform-docs 仓库里跑 OpenSpec（作为 Store）即可。 各微服务仓库 不必 再建 openspec/（见 5.2.1）。
| 组件 | 是否在 platform-docs | 说明 |
|---|---|---|
openspec/specs/ |
✅ | 跨服务活规范（Event、API 契约、业务流程） |
openspec/changes/ |
✅ | 协同变更 + 实施 tasks（可跨多服务代码仓） |
AGENTS.md |
✅ | 平台拓扑、联调、跨服务检查规则 |
platform.code-workspace |
✅ | Multi-Root 联调入口 |
docs/service-dependencies.md |
✅ | 依赖图；explore / propose 的输入 |
docs/api-contracts/ |
✅ | 可与 openspec/specs/api-contracts/ 合并或互链 |
不是「platform-docs 只管 Markdown、OpenSpec 另放别的仓库」——platform-docs 仓库里同时放 openspec/ 与平台文档，才是微服务侧的标准形态。
5.2.1 为什么推荐「服务仓不加 openspec/」
| 做法 | 优点 | 缺点 |
|---|---|---|
| 仅 platform-docs 有 openspec/（推荐） | 规范一处提交、少 PR 冲突；协同 change 集中 review | apply 时需用 workspace 改各服务代码 |
| 各服务另有 openspec/changes/ | 本仓独立 implement 历史 | 多仓提交 openspec、多人易冲突；规范易重复 |
OpenSpec 不会把 tasks 自动路由到多个 Git 仓库。既然实施本来就要靠 workspace 多根编辑，把 spec + change + tasks 都放在 platform-docs 更一致。
各服务仓库保留 AGENTS.md（启动、分层、编码约定），并 链接 platform-docs 中的契约即可。
5.2.2 可选进阶：服务仓最小 openspec（一般不需要）
仅当某服务团队 长期只打开本服务仓、从不开 platform-docs，又希望 Agent 自动索引上游 spec 时，可加：
order-service/openspec/config.yaml # references: [platform-docs]
仍 不建议 在各服务建 changes/，除非你们明确要本仓独立 implement 周期（见 5.10）。
5.3 目标架构
platform-docs/ ← OpenSpec Store + 平台文档（一体）
├── .openspec-store/store.yaml # Store 身份（openspec store setup 生成）
├── AGENTS.md # 平台拓扑、联调、跨服务检查
├── platform.code-workspace # Multi-Root Workspace
├── docs/
│ ├── service-dependencies.md # 依赖图（explore 输入）
│ └── api-contracts/ # 可与 openspec/specs 互链或逐步迁入
└── openspec/
├── specs/
│ ├── order-checkout/ # 跨服务业务能力
│ ├── events/ # OrderCreatedEvent 等
│ └── api-contracts/ # 可测试需求级契约（推荐）
└── changes/
└── add-checkout-promo/ # 跨服务协同规划
order-service/ ← 服务仓库：只有代码 + Agent 上下文
├── src/
└── AGENTS.md # 链到 platform-docs 契约与拓扑
inventory-service/
├── src/
└── AGENTS.md
职责分层：
| 层级 | 仓库 | 内容 |
|---|---|---|
| 跨服务规范、协同变更、实施 tasks | platform-docs/openspec/ |
specs + changes（proposal、delta、design、tasks） |
| 平台 Agent 上下文 | platform-docs/AGENTS.md |
拓扑、联调顺序、跨服务禁止事项 |
| 业务代码 | 各服务 src/ |
由 platform-docs 的 change + workspace 驱动修改 |
| 服务 Agent 上下文 | 各服务 AGENTS.md |
启动、目录、本服务编码约定（无 openspec/） |
5.4 教程：从零初始化 platform-docs（连贯操作）
以下命令 按顺序在同一终端会话执行，全程在 platform-docs 仓库根（Step 1 cd 之后不要换目录）。
推荐顺序：先 openspec init 搭好工作流，再补充 AGENTS.md、docs/ 等平台文件（init 不会自动生成这些）。
Git 与 OpenSpec 无关：Step 1～4、8 本地试玩时 可不做任何 Git 操作；团队协同时再执行可选 Step 5～6。详见 §5.11。
| 步骤 | 是否必需 | 说明 |
|---|---|---|
| Step 1 | ✅ | 创建并进入 platform-docs 根 |
| Step 2 | ✅ | openspec init（生成 openspec/、Agent 命令） |
| Step 3 | ✅ | 补充平台模板（AGENTS.md、docs/、workspace） |
| Step 4、8 | ✅ | Store 注册、打开 workspace 联调 |
| Step 5 | 可选 | git init、提交、推送 |
| Step 6 | 可选 | 队友协作；需远程 Git 仓 |
| Step 7 | 可选 | 全局 defaultStore |
Step 1：创建目录并进入（仓库根）
mkdir platform-docs
cd platform-docs
此时仓库根就是当前目录，后续 --path 可直接用 $(pwd)。
Step 2：初始化 OpenSpec（在 platform-docs 根目录）
# 确认 cwd 是 platform-docs 根，不是 parent/ 也不是 docs/
pwd # 应类似 .../platform-docs
openspec init --tools cursor # 或 claude / trae / codex；多人混用见 §3.5.3
不要在 docs/ 子目录或微服务父目录 parent/ 执行——openspec/ 与 Agent 命令文件会落在错误位置。详见 §3.3.1。
本步生成 openspec/ 及 Agent 的 OpenSpec 命令（如 Cursor 的 .cursor/commands/opsx-*.md）。此时目录大致为：
platform-docs/ ← 你当前的 cwd
└── openspec/ ← Step 2 生成
├── specs/
└── changes/
Step 3：补充平台模板文件
仍在 platform-docs 根目录（与 Step 1、2 相同，不要 cd 到别处）。
openspec init 不会自动生成 AGENTS.md、platform.code-workspace、docs/——本步手动补上，供 Agent 读拓扑、依赖图与联调方式。
与 Git 分开：本步只创建 Markdown / JSON 文件，不要执行 git init（Git 见可选 Step 5）。
无需从任何外部目录复制。 下列文件可在终端用脚本一次性创建，或在 Agent IDE 里 New File 粘贴保存。这是 最小可运行骨架，后续按真实服务名、端口、契约自行扩充。
mkdir -p docs/api-contracts
方式 A：终端一键创建（仍在 platform-docs 根目录）
cat > platform.code-workspace << 'EOF'
{
"folders": [
{ "name": "platform-docs", "path": "." },
{ "name": "order-service", "path": "../order-service" },
{ "name": "inventory-service", "path": "../inventory-service" }
],
"settings": {
"files.exclude": { "**/target": true, "**/node_modules": true },
"search.exclude": { "**/target": true, "**/node_modules": true }
}
}
EOF
cat > AGENTS.md << 'EOF'
# Platform Agent Instructions
> 平台级说明：多微服务拓扑、联调、跨服务改动检查。放在 platform-docs 仓库根。
## 1. 项目概览
- **业务域**：<!-- 例：电商交易 -->
- **技术栈**：<!-- 例：Java 17 + Spring Boot 3 -->
- **仓库组织**：各微服务独立目录/仓库，用 `platform.code-workspace` 聚合开发（是否 Git 管理由团队决定）
## 2. 服务拓扑（示例，请按实际修改）
| 服务 | 职责 | 依赖 |
|------|------|------|
| order-service | 订单创建、状态流转 | inventory-service |
| inventory-service | 库存查询、扣减 | — |
详细依赖图：`docs/service-dependencies.md`
## 3. 跨服务开发规则
1. 只改本服务内部 → 读该服务仓库 `AGENTS.md`
2. 改 API / Event → 检查所有 consumer，并更新 `docs/api-contracts/` 与 `openspec/specs/`
3. 不要跨服务直连数据库
## 4. OpenSpec（本仓库）
- 活规范：`openspec/specs/`
- 进行中变更：`openspec/changes/`
- 跨服务规划在本仓库或 workspace 内执行 `/opsx:propose`、`/opsx:apply`
## 5. Workspace
- 单服务开发：只打开对应服务仓库
- 跨服务联调：`cursor platform.code-workspace`
EOF
cat > docs/service-dependencies.md << 'EOF'
# Service Dependencies
## 依赖图（示例）
```mermaid
flowchart LR
ORDER[order-service] --> INV[inventory-service]
异步事件（示例）
| Event | Producer | Consumers |
|---|---|---|
| OrderCreatedEvent | order-service | inventory-service |
改动影响速查
| 若改了… | 还需检查… |
|---|---|
| OrderCreatedEvent 字段 | inventory-service consumer |
| EOF |
cat > docs/api-contracts/order-service.md << ‘EOF’
order-service API Contract（示例骨架）
| 项 | 值 |
|---|---|
| Service | order-service |
| Base URL | /api/orders |
POST /api/orders
创建订单。Caller：gateway-service。
正式契约与 Scenario 以 openspec/specs/ 为准；本文件可作人类可读的补充。
EOF
**方式 B：在 Cursor 中手动创建**
新建上述 4 个文件，内容与方式 A 中 `EOF` 之间的正文相同（`platform.code-workspace` 为 JSON，其余为 Markdown）。
**方式 C（可选）**：若你们组织已有统一的 `platform-docs` 模板 Git 仓库，clone 或 `cp` 等价于方式 A/B，**不是 OpenSpec 官方要求**。
创建完成后检查：
```bash
ls AGENTS.md platform.code-workspace docs/service-dependencies.md docs/api-contracts/order-service.md openspec/
Step 1～3 完成后，platform-docs 目录大致为：
platform-docs/
├── AGENTS.md
├── platform.code-workspace
├── docs/
└── openspec/ ← Step 2 生成；Step 3 与之间无冲突
Step 4：注册为 Store（仍在同一目录，不要 cd 到微服务）
store setup 只执行一次（搭建 platform-docs 的人）。--path 填 当前仓库根的绝对路径：
# 仍在 platform-docs 目录内
# 无 Git 时可省略 --remote
openspec store setup platform-docs --path "$(pwd)" \
--remote git@github.com:your-org/platform-docs.git
无远程仓库时：
openspec store setup platform-docs --path "$(pwd)"
说明：
| 参数 | 含义 |
|---|---|
platform-docs |
Store 在本机注册表里的 逻辑 id（建议与仓库名一致） |
--path "$(pwd)" |
就是 此刻的 platform-docs 根目录，即 Step 1 的 mkdir 位置 |
--remote |
可选；有 Git 远程时写入 Store 身份，方便队友 clone；本地试玩可省略 |
不需要在每个微服务目录下执行 store setup。微服务业务仓 甚至不需要 任何 openspec 命令。
Step 5（可选）：初始化 Git 并推送远程
本步整段可跳过（个人试玩、尚未建远程仓时）。OpenSpec 与 openspec init 不依赖 Git。
需要团队通过 Git 协作、走 PR review 时再执行：
git init
git add .
git commit -m "chore: init platform-docs with OpenSpec"
git remote add origin git@github.com:your-org/platform-docs.git
git push -u origin main
若目录里 早已 git init 过，只需 add / commit / push，不必重复 git init。
Step 6（可选）：队友加入（每人每台机器一次，与微服务仓无关）
依赖 Step 5 已推送的远程仓库。队友 不 跑 store setup（负责人已 setup），只 clone + register：
# 队友自选 clone 位置，例如与负责人相同的工作习惯
mkdir -p ~/code && cd ~/code
git clone git@github.com:your-org/platform-docs.git
cd platform-docs
openspec store register "$(pwd)" --id platform-docs
id 必须一致（platform-docs），--path 是队友本机 clone 路径，可以与负责人不同。
Step 7：可选——全局默认 Store
若希望在其他目录执行 openspec list 时默认指向 platform-docs：
openspec config set defaultStore platform-docs
Step 8：配置 Workspace 并联调各微服务
编辑 platform.code-workspace，把各微服务 clone 路径写进去，然后：
# 仍在 platform-docs 目录
cursor platform.code-workspace
日常 OpenSpec 操作在 platform-docs 上下文 或该 workspace 中执行；改代码时 Agent 通过多根访问 order-service/src 等。环境就绪后每次新需求的操作见 日常实战：环境就绪后，新需求怎么操作。
格式与维护见下一节 5.4.1 platform.code-workspace 格式。
命令分工速查
| 命令 | 谁执行 | 在哪执行 | 次数 | 需 Git |
|---|---|---|---|---|
openspec init（Step 2） |
搭建者 | platform-docs 根 | 一次 | 否 |
| 创建平台模板（Step 3） | 搭建者 | platform-docs 根 | 一次 | 否 |
openspec store setup（Step 4） |
搭建者 | platform-docs 根，--path "$(pwd)" |
一次 | 否（--remote 可选） |
git init / push（Step 5） |
搭建者 | platform-docs 根 | 可选 | 是 |
git clone + store register |
每个开发者 | 队友本机 clone 的 platform-docs 根 | 每机一次 | 是 |
| 各微服务仓 | — | 无需 store setup / openspec init |
— | — |
5.4.1 platform.code-workspace 格式与维护
platform.code-workspace 是 VS Code / Cursor 多根工作区（Multi-Root Workspace） 配置文件，格式为 JSON。Cursor 与 VS Code 共用同一规范，不是 Cursor 私有格式。
文件是什么
| 项 | 说明 |
|---|---|
| 扩展名 | .code-workspace |
| 本质 | 列出「同时打开的多个本地文件夹」 |
| 打开方式 | 在 platform-docs 目录执行 cursor platform.code-workspace，或 Cursor：File → Open Workspace from File |
| 与单文件夹区别 | 单文件夹打开某个目录；workspace 打开这份 JSON，侧边栏出现 多个根 |
顶层结构
{
"folders": [ ... ], // 必填：工作区包含哪些目录
"settings": {
... }, // 可选：整个工作区的 IDE 设置
"extensions": {
... }, // 可选：推荐扩展
"launch": {
... }, // 可选：调试配置
"tasks": {
... } // 可选：任务配置
}
模板里通常只用 folders + settings。
模板示例（教程 §5.4 Step 3 最小骨架；可按团队扩充）
{
"folders": [
{
"name": "platform-docs",
"path": "."
},
{
"name": "order-service",
"path": "../order-service"
},
{
"name": "inventory-service",
"path": "../inventory-service"
}
],
"settings": {
"files.exclude": {
"**/target": true,
"**/node_modules": true
},
"search.exclude": {
"**/target": true,
"**/node_modules": true
}
}
}
folders 字段说明
每个元素表示工作区里的一个「根」：
| 字段 | 必填 | 说明 |
|---|---|---|
path |
✅ | 该目录在本机的路径 |
name |
可选 | 侧边栏显示名；不写则用文件夹名 |
path 写法：
| 写法 | 含义 | 示例场景 |
|---|---|---|
"." |
workspace 文件所在目录 | platform-docs 自身（OpenSpec、AGENTS.md） |
"../order-service" |
相对 workspace 文件的兄弟目录 | 与 platform-docs 平级 的微服务仓 |
/Users/you/code/order-service |
绝对路径 | clone 位置与模板假设不一致时 |
相对路径规则：以 .code-workspace 文件所在目录 为基准解析（不是终端 cwd）。
模板假设的磁盘布局：
parent/
├── platform-docs/
│ ├── platform.code-workspace ← "path": "." 指这里
│ ├── AGENTS.md
│ └── openspec/
├── order-service/ ← "path": "../order-service"
├── inventory-service/
└── gateway-service/
若你的目录不是这样，修改 folders[].path 即可，例如：
{
"name": "order-service", "path": "/Users/wujinwei/Desktop/code/order-service" }
settings 字段说明
写在 workspace 文件里的设置作用于 整个多根工作区（各文件夹下的 .vscode/settings.json 仍可覆盖单根设置）。
模板中 files.exclude / search.exclude 用于隐藏 target、node_modules，减少 Java 微服务工程的干扰。可按团队需要增加格式化、Java 路径等，键名与普通 settings.json 相同。
与 OpenSpec 微服务流程的关系
| 根（folder） | 内容 | OpenSpec 角色 |
|---|---|---|
platform-docs（通常放第一位） |
openspec/、AGENTS.md |
propose / apply / archive 的规范与 change |
order-service 等 |
src/、服务 AGENTS.md |
apply 时按 tasks 改代码；无 openspec/ |
因此教程采用「仅 platform-docs 有 openspec」：Agent 在一个会话里既能读 platform-docs/openspec/changes/.../tasks.md，又能编辑 order-service/src/...。
维护注意
- 各服务 clone 路径变了 → 只改对应
folders[].path。 - 团队共享 → 优先用相对路径
../service-name；每人目录结构一致即可。 - 个人路径不同 → 本地改绝对路径，或使用不提交的私有 workspace 副本。
- 无 Git 本地玩 → 只要
path指向真实存在的文件夹即可，与 Git 无关。 - 文件可进 platform-docs 仓库 → 各
path指向的其它仓仍是独立目录（可有各自 Git）。
最小示例（本地两个文件夹试玩）
{
"folders": [
{
"name": "platform-docs", "path": "." },
{
"name": "order-service", "path": "../order-service" }
],
"settings": {
}
}
保存为 platform-docs/platform.code-workspace 后：
cd platform-docs
cursor platform.code-workspace
5.5 组织 platform-docs 内的跨服务 specs
按 业务能力 而非按服务名组织（跨服务功能往往才是规划单元）：
openspec/specs/
├── events/
│ └── spec.md # OrderCreatedEvent、PaymentSuccessEvent
├── order-checkout/
│ └── spec.md # 下单全流程（涉及 order、inventory、payment）
├── activity-reward/
│ └── spec.md # 活动发奖（涉及 activity、order、payment）
└── api-contracts/
└── order-service.md # 对外 REST 契约
events/spec.md 示例片段：
# Events Specification
## Requirement: OrderCreatedEvent
When an order is successfully created, order-service MUST publish OrderCreatedEvent.
#### Scenario: Standard order
- GIVEN a valid order with skuId and quantity
- WHEN order creation succeeds
- THEN publish event with fields: orderId, userId, skuId, quantity, activityId
### Consumers
- inventory-service: deduct stock
- activity-service: trigger reward eligibility check
5.6 各微服务仓库要做什么（无 openspec/）
服务仓 不需要 openspec init，也 不需要 store setup / store register。
在各服务仓库根目录 创建或补充 AGENTS.md（无需从外部模板复制）。最小示例：
# 在 order-service 仓库根执行，或于 Cursor 中 New File
cat > AGENTS.md << 'EOF'
# order-service Agent Instructions
| 项 | 值 |
|----|-----|
| 服务名 | order-service |
| 端口 | 8081 |
## 跨服务契约与拓扑
- 平台拓扑：platform-docs 仓库 `AGENTS.md`
- 依赖图：`platform-docs/docs/service-dependencies.md`
- API/Event 规范：`platform-docs/openspec/specs/`
- 进行中变更：`platform-docs/openspec/changes/`
开发跨服务需求时用 `platform.code-workspace` 同时打开 platform-docs 与本服务。
EOF
将 order-service、端口等换成实际值。完整服务级模板可按团队规范自行扩展（目录结构、启动命令、编码约定等）。
也可只在已有 AGENTS.md 中增加「跨服务契约与拓扑」一节，例如：
## 跨服务契约与拓扑
- 平台拓扑与联调：platform-docs 仓库 `AGENTS.md`
- 依赖图：`platform-docs/docs/service-dependencies.md`
- API/Event 规范：`platform-docs/openspec/specs/`（OpenSpec 活文档）
- 当前进行中的变更：`platform-docs/openspec/changes/`
开发时请用 `platform.code-workspace` 同时打开 platform-docs 与本服务。
验证 Store 是否在本机可用（在 platform-docs 目录 执行，不是进微服务）：
cd platform-docs # 你的 clone 路径
openspec doctor
openspec context
5.7 教程：跨服务功能完整流程（仅 platform-docs）
本节是 跨服务促销码 的完整示例。通用「每次新需求」步骤见 日常实战。
场景：结账促销码（add-checkout-promo），涉及 order-service、inventory-service、gateway。
前置：已用 platform.code-workspace 打开 platform-docs + 各服务。若需求来自飞书长文档，先按 §2.4 落到 docs/requirements/，再 propose。
阶段 1：在 platform-docs 规划并 review 契约
在 platform-docs 根目录的 Cursor Agent 中（无需 --store，当前目录就是 Store）：
/opsx:propose add-checkout-promo
促销码在结账时校验：输入 promoCode，eligible 则减价，ineligible 展示原因。
写清 API 字段、OrderCreatedEvent 变更、错误码。tasks 按服务分段标注路径。
tasks.md 建议按服务分段，例如：
## [order-service] API 与 Event
- [ ] T1 修改 `order-service/src/.../OrderController.java` ...
- [ ] T2 发布 OrderCreatedEvent 增加 promoCode、discountAmount
## [inventory-service] Consumer
- [ ] T3 修改 `inventory-service/src/.../OrderCreatedConsumer.java` ...
Review proposal.md 与 delta spec（使用 Git 时 可走 platform-docs PR，merge 后再实施；无 Git 时本地 review 即可）。
阶段 2：在同一 workspace 内 apply（不建各服务 change）
仍在 platform-docs 上下文：
/opsx:apply
Agent 通过 workspace 多根修改 order-service/src、inventory-service/src 等；openspec 工件只保存在 platform-docs（有 Git 时再 commit / PR）。
/opsx:archive
delta 合并进 platform-docs/openspec/specs/。
阶段 3（可选，使用 Git 时）：各服务提交代码变更
无 Git 时跳过本阶段，本地改完即可。
| 仓库 | 提交内容 |
|---|---|
| platform-docs | openspec/ 变更（规范 + archive） |
| order-service | 仅 src/ 等业务代码 |
| inventory-service | 仅业务代码 |
使用 PR 时，服务 PR 描述中可链接 platform-docs 的 change / PR。
阶段 4：可选 workset（个人快捷打开）
若不用 platform.code-workspace，可用 workset 记住常一起打开的目录（路径用你本机实际 clone 位置）：
cd platform-docs
openspec workset create checkout-promo \
--member "$(pwd)" \
--member /path/to/order-service \
--member /path/to/inventory-service \
--tool cursor
openspec workset open checkout-promo
Workset 是 本机个人配置，不提交 Git。
注意：OpenSpec 不会自动把 tasks 路由到各 Git 仓；一个 change 在 platform-docs，代码靠 workspace 跨根修改——这正是「服务仓不加 openspec/」的原因。
5.8 微服务场景的 spec 组织建议
| 放在 platform-docs/openspec/ | 放在各服务仓库 |
|---|---|
| 跨服务 Event 字段与语义 | 仅 src/ 代码（无 openspec） |
| 对外 API 契约（REST/gRPC） | AGENTS.md 链到 platform-docs |
| 跨服务业务流程 | — |
| 协同 change 的 design、tasks（可含多服务路径） | — |
| 平台级错误码、鉴权规则 | — |
避免在每个服务仓库重复定义 OrderCreatedEvent——只在 platform-docs 的 specs 定义一次。
5.9 微服务场景最佳实践
| 实践 | 说明 |
|---|---|
| 规范只保存在 platform-docs | 减少多仓 openspec 冲突 |
| 先 review 规范再改代码（Git 时 可先 merge platform-docs PR） | 契约先对齐 |
tasks 按 [service-name] 分段 |
apply 时 Agent 知道改哪个根 |
| 用 workspace 开发 | propose/apply 与改代码同一上下文 |
队友只 register，不 setup |
setup 仅建仓时一次 |
openspec doctor 在 platform-docs 跑 |
检查 Store 与引用健康 |
| Stores 仍是 beta | 升级 CLI 后重读 Stores 文档 |
5.10 可选进阶：各服务本仓 openspec（一般不推荐）
仅在以下情况考虑各服务 openspec/changes/：
- 服务团队 从不 打开 platform-docs，坚持只在本仓跑
/opsx:* - 需要本仓独立的 implement archive 历史，且接受多仓提交 openspec 的协作成本
默认团队应使用 5.7 的「仅 platform-docs」流程。
若仍不用中央 platform-docs、每个服务各自 openspec init（小团队、少跨服务改）：
order-service/openspec/specs/orders/spec.md
缺点：Event 变更需多仓同步，易 drift——成熟后应迁到 platform-docs。
5.11 Git 非必选
OpenSpec 与 Cursor 的 /opsx:* 不依赖 Git。git init、commit、push、store register 均为 团队协作文档化时的可选步骤，不是跑通 OpenSpec 的前提。
最小路径（无 Git）
按 §5.4 执行 Step 1～4、8，跳过 Step 5～6 即可：
- Step 1：创建
platform-docs目录 - Step 2：
openspec init - Step 3：补充
AGENTS.md、docs/、platform.code-workspace - Step 4：
store setup --path "$(pwd)"（可不带--remote） - Step 8：
cursor platform.code-workspace→ propose → apply → archive
单体（单文件夹）
mkdir -p ~/play/my-app && cd ~/play/my-app
openspec init
cursor .
在 Cursor 中 /opsx:propose → /opsx:apply 即可；无需 git init。
微服务（platform-docs + workspace，无 Git）
与 §5.4 Step 1～4 相同：
mkdir -p ~/play/parent/{
platform-docs,order-service,inventory-service}
cd ~/play/parent/platform-docs
openspec init --tools cursor # Step 2
openspec store setup platform-docs --path "$(pwd)" # Step 4；无 --remote
# Step 3：创建 AGENTS.md、platform.code-workspace、docs/...（见 §5.4 Step 3）
cursor platform.code-workspace # Step 8
| 维度 | 无 Git（本地目录） | 使用 Git（团队常见） |
|---|---|---|
| OpenSpec 能否跑通 | ✅ 完全可以 | ✅ |
store setup |
--path 即可 |
可加 --remote |
| 队友协作 | 拷目录 / 共享盘 / 后补 Git | clone + store register |
| 规范 review | 本地或会议对齐 | platform-docs PR |
| 代码交付 | 本地改完即用 | 各服务 PR |
要点：
openspec store setup --path "$(pwd)"与 Git 无关，只声明本机 Store 根目录。platform.code-workspace只要求folders[].path指向真实文件夹。- PR、远程协作、审计 才需要 Git；学习与试玩可全程省略。
日常实战：环境就绪后，新需求怎么操作
适用：已完成 §4.3 或 §5.4 的初始化，日常接到产品/业务 新需求 时按本节重复执行。
聊天命令写法因 Agent 而异（Cursor/opsx-propose、Claude/opsx:propose、Codex$openspec-propose），下表用 Claude 写法 作代表，请按 §3.5 替换。
总览：一条需求走一遍
新需求进入
→（可选）PRD 落库 + explore 消化
→ propose：生成 change（proposal / spec / design / tasks）
→ 人工 review 规划工件（不是 review 全部代码）
→ apply：按 tasks 改代码
→（可选）跑测试、openspec validate
→ archive：delta 并入 openspec/specs/
→（可选）Git 提交 / PR
| 阶段 | 终端（openspec …） |
Agent 聊天 |
|---|---|---|
| 看现状 | openspec list、openspec show <change> |
/opsx:explore |
| 规划 | — | /opsx:propose <change-id> |
| 实施 | — | /opsx:apply |
| 收尾 | openspec validate <change> |
/opsx:archive |
单体服务：新需求步骤清单
打开方式：Agent IDE 打开 业务仓库根（如 my-monolith/），确保该目录已 openspec init。
| 步骤 | 做什么 | 示例 |
|---|---|---|
| 0 | 需求进上下文 | 一句话直接 propose；长 PRD 见 §2.4 |
| 1 | （可选）探索 | /opsx:explore + 描述需求，让 Agent 读相关 src/ |
| 2 | 提案 | /opsx:propose add-remember-me |
| 3 | Review | 看 openspec/changes/add-remember-me/ 下 proposal.md、delta spec.md、tasks.md |
| 4 | 实施 | /opsx:apply；中途可改 design.md / tasks.md 再继续 apply |
| 5 | 验证 | 跑单测/联调；openspec validate add-remember-me |
| 6 | 归档 | /opsx:archive → 能力写入 openspec/specs/ |
| 7 | （可选）Git | 代码 + openspec/ 一并提交 |
聊天示例（探索 + 提案）：
/opsx:explore
要给登录加「记住我」，请先读 auth 相关代码，说明改动点。
/opsx:propose add-remember-me
按 explore 结论生成 change；范围仅限记住我，不要扩到注册流程。
微服务：新需求步骤清单
打开方式：cursor platform.code-workspace（或 Trae 打开同一 workspace），确保 platform-docs 根 已 init 且为 Store。
| 步骤 | 在哪里做 | 做什么 |
|---|---|---|
| 0 | platform-docs | 长 PRD → docs/requirements/REQ-xxx.md（§2.4） |
| 1 | platform-docs 上下文 | /opsx:explore：读 PRD、docs/service-dependencies.md、相关服务 src/ |
| 2 | platform-docs | /opsx:propose <change-id>；tasks 用 [order-service] 等分段 |
| 3 | 人工 | Review platform-docs 的 change 工件（范围、Event/API、跨服务 tasks） |
| 4 | workspace（platform-docs 聊天） | /opsx:apply：Agent 跨根改各服务 src/ |
| 5 | 终端 platform-docs | openspec validate <change-id>；各服务跑测试 |
| 6 | platform-docs | /opsx:archive |
| 7 | （可选）Git | platform-docs 提交 openspec/；各服务只提交业务代码 |
不要在各微服务仓单独 /opsx:propose 同一需求（除非走 §5.10 特殊模式）。
聊天示例（跨服务）：
/opsx:explore
请读 @docs/requirements/REQ-2026-001-checkout-promo.md
和 docs/service-dependencies.md，列出涉及服务与待澄清问题。
/opsx:propose add-checkout-promo
依据 PRD 与 explore 结论生成 change。
tasks 按 [order-service]、[inventory-service] 分段，路径写清各服务 src。
更完整的促销码 walkthrough 见 §5.7。
需求形态怎么选入口
| 需求形态 | 建议 |
|---|---|
| 一句话 / 口头 | 直接 explore → propose |
| 飞书 / PRD 长文 | 先落库 docs/requirements/，@ 文件后 explore → propose |
| 小 bug、typo | 可 跳过 OpenSpec，直接改代码（见下节） |
| 一个大 PRD 多个功能 | 拆多个 change，每个独立 propose → archive |
什么时候可以不走完整流程
| 情况 | 建议 |
|---|---|
| 改 typo、明显单点 bug | 直接改代码 |
| 纯重构、行为不变 | 可不 propose；若影响对外契约仍建议走 spec |
| 紧急 hotfix | 可先 apply 代码，事后补 change + archive（团队需约定） |
| 对齐成本高、范围清晰 | 可省略 explore，直接 propose |
每次新需求自检（Checklist）
规划阶段（propose 之后）
-
proposal.md范围是否与需求一致？有没有「顺便多做」？ - delta
spec.md的 Scenario 能否据此写测试？ -
tasks.md是否可独立验证？微服务是否标了服务名与文件路径？
实施阶段（apply 之后）
- 代码是否只实现了本 change 的 tasks？
- 跨服务 Event/API 是否与 platform-docs 里 spec 一致？
-
openspec validate <change-id>是否通过？
收尾
- 已
/opsx:archive，openspec/specs/已更新 - （Git）platform-docs 与各服务提交内容是否分离清楚
常用终端命令（新需求周期内）
在 openspec 所在仓库根（单体仓或 platform-docs）执行：
openspec list # 当前有哪些 active change
openspec show add-checkout-promo # 某个 change 详情
openspec validate add-checkout-promo
openspec doctor # 微服务：Store 是否健康
6. 两种场景对比与选型
6.1 对比表
| 维度 | 单体服务（单仓库） | 微服务多仓库 |
|---|---|---|
| openspec 位置 | 业务仓库根目录一个 | 仅 platform-docs |
| spec 组织 | 按功能域 auth/、orders/ |
platform-docs 按业务能力 |
| 跨模块变更 | 同一 change 文件夹 | platform-docs 一个 change（tasks 含多服务路径） |
| 协作方式 | 本地 review 即可 | 本地或 Git PR（platform-docs 规范 + 各服务代码） |
| Git | 非必选（团队协同时推荐） | 非必选（团队协同时推荐） |
| Agent 上下文 | 本地 openspec + AGENTS.md | workspace 多根 + platform-docs |
| 上手成本 | 低（10 分钟） | 中（建仓 + store setup/register 一次） |
| 规范漂移风险 | 低 | 低（契约只在 platform-docs） |
| 适合团队规模 | 1～10 人 | 5～50+ 人、多团队 |
6.2 决策树
你的代码怎么组织？
│
├─ 单仓库单体 / 单服务
│ → openspec/ 放根目录，按功能域分 specs/
│
├─ Monorepo 多服务（一个 Git 多个 deployable）
│ → 多数情况仍是一个根 openspec/，domains 按服务名：
│ specs/order-service/、specs/inventory-service/
│ → 若 package 间耦合弱，可考虑 Store
│
└─ 多 Git 仓库微服务
│
└─ 默认推荐
→ 仅 platform-docs 有 openspec/；服务仓只有代码 + AGENTS.md
→ workspace 联调；**Git 时** 规范 PR 在 platform-docs，代码 PR 在各服务
6.3 从单体演进到微服务
- 单体阶段：
my-app/openspec/按功能域积累 specs - 拆服务时：新建 platform-docs，
openspec store setup，把跨边界 spec 迁入 - 各微服务仓库：不必
openspec init；AGENTS.md链到 platform-docs - 原单体 archive 历史可保留在版本库中；跨服务部分复制/摘要进 platform-docs specs
7. 与 AGENTS.md 的分层配合
OpenSpec 与 AGENTS.md 互补，不重复：
┌─────────────────────────────────────────────────────────┐
│ AGENTS.md / .cursor/rules │
│ 「这个仓库长什么样」— 静态、仓库级、很少变 │
├─────────────────────────────────────────────────────────┤
│ openspec/specs/ │
│ 「系统应该怎样工作」— 动态演进、可测试需求 │
├─────────────────────────────────────────────────────────┤
│ openspec/changes/ │
│ 「这次要改什么」— 临时、review 后 archive │
├─────────────────────────────────────────────────────────┤
│ Superpowers / 其他 skills（可选） │
│ 「怎么做」— TDD、review 过程强制 │
└─────────────────────────────────────────────────────────┘
在 openspec/config.yaml 的 context 中引用 AGENTS.md：
context: |
编码规范、目录结构、启动方式见根目录 AGENTS.md。
跨服务依赖见 platform-docs（多仓库场景）。
微服务 AGENTS.md 与平台文档分层（见 §5.4 Step 3、§5.6 创建示例）：
| 文件 | OpenSpec 关系 |
|---|---|
platform-docs AGENTS.md |
与 openspec/ 同仓；拓扑 + 联调 |
各服务 AGENTS.md |
服务仓静态上下文；链到 platform-docs，无 openspec |
docs/api-contracts/*.md |
可迁入 openspec/specs/api-contracts/ 或互链 |
docs/service-dependencies.md |
explore 时的补充材料 |
8. 常用 CLI 与 Slash 命令速查
8.1 Slash 命令（AI 聊天框）
下表为 Claude Code 的 canonical 写法（/opsx: + 冒号）。Cursor / Trae 用连字符：/opsx-propose；Codex 用 $openspec-propose 等。完整对照见 §3.5.2。
| 命令（Claude 写法） | 作用 |
|---|---|
/opsx:explore |
探索代码、理清思路，不写 artifact |
/opsx:propose <name> |
创建 change，生成全套 artifacts |
/opsx:apply |
按 tasks 实施 |
/opsx:archive |
合并 delta，归档 change |
/opsx:update |
更新 change 内 artifacts |
/opsx:sync |
同步状态（core profile） |
/opsx:onboard |
引导式首次体验（expanded profile） |
命令未被识别时：确认 openspec init --tools <你的 Agent>、执行 openspec update、重启或重载 IDE/Agent，并在聊天里用 该工具支持的拼写（见 §3.5）。
8.2 CLI（终端）
CLI 需先 全局安装（§3.2）：npm install -g @fission-ai/openspec@latest。下列命令在任意已 init 的仓库根或 platform-docs 中执行。
| 命令 | 作用 |
|---|---|
npm install -g @fission-ai/openspec@latest |
全局安装 / 升级 CLI（本机一次） |
openspec init |
在 当前仓库根 初始化 openspec/ 与 Agent 集成文件（--tools 见 §3.5） |
openspec update |
更新 agent 集成文件 |
openspec list |
列出 active changes |
openspec show <change> |
查看 change 详情 |
openspec validate <change> |
校验 spec 格式 |
openspec view |
交互式仪表盘 |
openspec doctor |
检查 root、references 健康 |
openspec context |
查看当前工作上下文 |
openspec store setup <id> |
创建 Store |
openspec store register <path> |
注册 Store |
openspec new change <id> --store <id> |
在 Store 中新建 change |
openspec workset create/open |
管理多根工作区 |
8.3 Root 解析优先级（多仓库必知）
1. --store <id> 显式指定
2. 当前目录向上 nearest openspec/
3. config.yaml 的 store: 指针
4. 全局 defaultStore
5. 以上皆无 → 经典单目录行为或报错提示
每次命令开头的 Using OpenSpec root: 行告诉你实际作用在哪个仓库。
9. 常见问题
Q1：是不是 waterfall？
不是。OpenSpec 要求的是 10 分钟对齐，不是数月规划。计划可随时改 artifact，没有锁死阶段。
Q2：老项目要先写完全部 spec 吗？
不需要。 每次 change 只 delta 你正在改的那一块。详见 Existing Projects 指南。
Q3：换 AI 工具后 spec 还有用吗？
有用。specs 是 Markdown 文件；使用 Git 时 便于 diff 与 review。OpenSpec 支持 20+ 工具集成，目标是 universal planning layer。
Q4：微服务能否一个 change 自动改多个仓库？
不能自动路由。 推荐在 platform-docs 一个 change 里写清各服务 tasks，用 workspace 在 apply 时跨根改代码；openspec 工件只保存在 platform-docs（有 Git 时再 commit / PR）。
Q5：每个微服务都要 store setup 吗？
不需要。 store setup 只在 创建 platform-docs 时执行一次（在 platform-docs 目录内，--path "$(pwd)"）。队友 clone 后只 store register。微服务业务仓无需任何 openspec 命令。
Q6：openspec/ 和 docs/api-contracts/ 重复了怎么办？
选一处为 规范真相（推荐 platform-docs/openspec/specs/），另一处改为链接或逐步废弃。不要两处各改各的。
Q7：小 bug 也要走完整流程吗？
不必。trivial fix 直接改代码；OpenSpec 适合「对齐有价值」的变更。
Q8：Stores beta 稳定吗？
API、flag、JSON 格式可能随版本变化。升级后跑 openspec doctor，并重读 Stores 文档。
Q9：platform.code-workspace 是什么格式？
标准 VS Code / Cursor Multi-Root Workspace JSON：folders[] 列出多个本地目录（path + 可选 name），可选 settings 等。相对路径以 workspace 文件所在目录为基准。详见 5.4.1。
Q10：没有 Git 能玩 OpenSpec 吗？
可以，且这是 官方支持的用法。openspec init、store setup、/opsx:* 均不依赖 Git。详见 §3.1.1、§5.11。
Q16：Git 是必选的吗？
不是。 Git 仅用于团队 PR、远程协作与审计；OpenSpec 核心流程在本地文件夹即可完成。微服务场景跳过 §5.4 Step 5～6 即可。
Q11：需求是一篇飞书长文档，怎么完整输入？
不要指望一句话或一次粘贴搞定。推荐：飞书导出 / Agent 拉取 → 写入 docs/requirements/REQ-xxx.md → /opsx:explore 读 @ 文件消化 → /opsx:propose 生成精简 change；一篇 PRD 可拆多个 change。详见 §2.4。
Q12：openspec init 应该在哪个目录执行？
在 Cursor 要打开的仓库根 执行：单体 = 业务仓根；微服务 = platform-docs 根，不是 docs/ 子目录，也不是包含各服务的父目录。init 会在当前目录生成 openspec/ 与 .cursor/commands/，目录错了 CLI 和 /opsx:* 都找不到。详见 §3.3.1。
Q13：openspec 命令需要每个项目装一次吗？
CLI 全局装一次（§3.2）；每个要用的仓库根 init 一次 生成 openspec/ 与 Cursor 命令文件。微服务默认只在 platform-docs init，不是每个微服务仓都装 CLI。
Q14：终端报 openspec: command not found？
先全局安装：npm install -g @fission-ai/openspec@latest。仍找不到则检查 PATH 是否包含 npm prefix -g 下的 bin 目录。详见 §3.2。
Q15：platform-docs 的 AGENTS.md 要从哪里复制？
不需要复制。 按 §5.4 Step 3 在 platform-docs 内 创建 最小骨架即可（Step 2 先 openspec init）；各服务仓按 §5.6 创建/补充 AGENTS.md。若组织内有统一模板仓库，clone 后使用亦可，非 OpenSpec 硬性要求。
Q17：Cursor / Claude / Trae / Codex 命令不一样怎么办？
正常。init 时选对应 --tools id（cursor、claude、trae、codex），聊天里用该工具生成的拼写：Cursor/Trae 多为 /opsx-propose，Claude 为 /opsx:propose，Codex 为 $openspec-propose。对照表见 §3.5。
Q18：环境搭好了，来了新需求第一步做什么？
打开正确工作区（单体：业务仓根；微服务：platform.code-workspace），长 PRD 先落库，再 /opsx:explore（可选）→ /opsx:propose → review → /opsx:apply → /opsx:archive。完整清单见 日常实战。
10. 参考链接
| 资源 | URL |
|---|---|
| OpenSpec 官网 | https://openspec.dev/ |
| Getting Started | https://openspec.dev/docs/getting-started |
| 核心概念 | https://openspec.dev/docs/overview |
| 安装 | https://openspec.dev/docs/installation |
| Supported Tools | https://openspec.dev/docs/reference/supported-tools |
| Slash 命令参考 | https://openspec.dev/docs/reference/slash-commands |
| 存量项目 | https://openspec.dev/docs/existing-projects |
| Stores（多仓库） | https://openspec.dev/docs/stores |
| GitHub | https://github.com/Fission-AI/OpenSpec |
| 支持的工具列表 | https://openspec.dev/ |
附录：快速启动命令清单
以下假定已按 §3.2 全局安装 CLI。若未安装，先执行：
npm install -g @fission-ai/openspec@latest
单体服务
cd my-monolith && openspec init --tools cursor # 或 claude / trae / codex，见 §3.5
# Agent 聊天：按工具输入 propose → apply → archive（Cursor: /opsx-propose …）
微服务多仓库（仅 platform-docs 有 openspec）
# 1. 建目录 + init OpenSpec（§5.4 Step 1～2）
mkdir platform-docs && cd platform-docs
openspec init --tools cursor # 或 claude / trae / codex；多人混用见 §3.5.3
# 2. 补充平台模板（§5.4 Step 3）
mkdir -p docs/api-contracts
# 创建 AGENTS.md、platform.code-workspace、docs/...
openspec store setup platform-docs --path "$(pwd)" \
--remote git@github.com:your-org/platform-docs.git # 无 Git 时省略 --remote；Step 4
# 3.（可选）Git：git init → commit → push（§5.4 Step 5）
# 4.（可选）队友：clone + store register（§5.4 Step 6）
# 5. 各微服务：在服务仓根创建/补充 AGENTS.md（§5.6），无需 openspec init
# 6. 开发：编辑 platform.code-workspace 后
cursor platform.code-workspace
# /opsx:propose → /opsx:apply → /opsx:archive（均在 platform-docs 上下文）
# 日常每个新需求：见「日常实战：环境就绪后，新需求怎么操作」
本文基于 OpenSpec 官方文档（2026 年初版本）整理。Stores 为 beta 功能，请以官方文档最新版为准。