Skip to content

OpenSpec Practise v2.1.0

Latest

Choose a tag to compare

@grissomsh grissomsh released this 18 Nov 11:25

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 --strict 7/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-run previewed 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/:orderId in 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 --strict 7/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)