Repository navigation
OpenSpec Practise v2.1.0
基于 OpenSpec v2.1.0 的实践更新(v1.16.0 → v2.1.0,覆盖 v1.16.1 / v1.17.0 / v2.0.0(首个 BREAKING 大版本) / v2.1.0)。工作流本身没有变化,变的是技能位置与调用方式。
2.x 迁移
- CLI 升级至 2.1.0,
update --dry-run预览 25 个文件后--force应用 - 技能统一到
.agents/skills/(唯一真身),.claude/skills/变为符号链接;.claude/commands/opsx/的 6 个/opsx:*命令文件移除,改为技能名 / 自然语言调用 - 非交互环境不询问 scope,技能留在项目内(教学仓库随仓库分发);npm 安装 Node 门槛升至 ≥ 22.20
完整工作流实践:payment-implementation
- 补齐 7 个能力中最后一个「spec 完整、代码为零」的缺口:双实现
POST /api/payments/:orderId - 状态机集中在服务层(仅 PENDING_PAYMENT → PAID);重复支付按幂等成功(spec 允许);404 沿用各自错误风格
- 以
skip_specs: true归档(行为契约已在 payment spec 中定义,4 场景逐条核对) - Node 22/22、Python 8/8 全绿;
validate --specs --strict7/7,归档 8/8 - 至此 7 个能力 spec-code 全闭环,仅剩错误响应格式差异一项在册债务
- 产物:
openspec/changes/archive/2026-11-18-payment-implementation/ - 复盘文章:
docs/openspec-v2.1.0-workflow-practice.md(中英双语)
OpenSpec Practise v2.1.0
Practice update based on OpenSpec v2.1.0 (v1.16.0 → v2.1.0, covering v1.16.1 / v1.17.0 / v2.0.0, the first breaking major release / v2.1.0). The workflows themselves are unchanged — what changed is where skills live and how to invoke them.
The 2.x migration
- CLI upgraded to 2.1.0;
update --dry-runpreviewed 25 files before--force - Skills unified in
.agents/skills/(single real copy);.claude/skills/became symlinks; the six/opsx:*command files under.claude/commands/opsx/were removed — invoke skills by name or natural language - Non-interactive runs skip the scope question and keep skills in-project (a teaching repo ships them with the repo); npm installs now require Node ≥ 22.20
Full workflow practice: payment-implementation
- Closed the last "complete spec, zero code" gap:
POST /api/payments/:orderIdin both implementations - The state machine lives in the service layer (only PENDING_PAYMENT → PAID); repeat payment is an idempotent success (allowed by the spec); 404 follows each implementation's error style
- Archived with
skip_specs: true(the payment spec already defines the behavior; all 4 scenarios cross-checked) - Node 22/22, Python 8/8 green;
validate --specs --strict7/7, archived 8/8 - All seven capabilities now close the spec-code loop; the only debt left is the error-response format difference
- Artifacts:
openspec/changes/archive/2026-11-18-payment-implementation/ - Retrospective:
docs/openspec-v2.1.0-workflow-practice.md(bilingual)