OpenRig 弃用切片模板：用 backlog-deprecation 规范化 Deprecation 迁移全流程

• 人工智能
• AI Agent
• 多智能体
• Agent 编排
• 代码智能体
• CLI

导读：本文讲解 OpenRig（多 Agent 协作软件工厂）内置的backlog-deprecation切片模板——当项目需要弃用一个 API、命令、配置项或行为，并希望以"可观察结果 + 证据"的方式完成迁移与移除时，用它一次性生成规范化的 SPEC.md 骨架。读完本文，你将掌握该模板的逐节语义、rig scope slice create --template backlog-deprecation的生成机制、弃用四问（Target / Current state / Migration / Removal）的填写方法，以及配套的rig proof add证据落地与rig scope audit验证闭环。

OpenRig 把一切工作表达为 mission 与 slice：人类记录意图，Agent 把意图变成计划、把计划变成构建、把构建变成证据。其中"弃用（deprecation）"是一类高频但极易失控的工作——旧行为往往被多处依赖，直接删除会破坏调用方，拖着不删又会积累技术债。backlog-deprecation模板正是为这类工作预置的标准化切片骨架，它把"弃用什么、现状如何、怎么迁移、何时移除"四个问题固化进 SPEC.md，让一次弃用从开始到收尾都有可审计的轨迹。

一、模板定位：六类切片模板中的"弃用专用模板"

在 OpenRig 的 scope 体系里，切片模板类型由SliceTemplateKind联合类型定义，共六种，见 types.ts：

backlog-deprecation与backlog-tech-debt同属"backlog 系列"：它们服务的都是积累在主线之外、需要被显式排期的存量工作，而非新功能开发。二者的差异在于——技术债切片关注"修复"存量问题，弃用切片关注"告别"存量行为：它要求你在计划阶段就明确迁移路径与移除条件，而不是只写"这个旧东西很糟糕"。

从模板本身看（backlog-deprecation.md），它的正文在通用三节（Intent / Mini-requirements / Proof contract）之后，额外编排了四个专门小节：## Target、## Current state、## Migration、## Removal。这四节就是一次弃用工作的完整叙事：弃用什么 → 现状如何 → 怎么走开 → 何时删除。模板自带的说明文字还特别强调："For a small deprecation this may BE the whole plan"——小型弃用的 mini-requirements 可以就是整个计划，不需要额外造仪式（这与 SDLC 约定的 A5「弹性中间地带」原则一致，详见下文第八节）。

二、模板骨架逐节拆解

模板全文是一个带占位符的 Markdown 文件。以下逐节说明每个部分的语义（{{...}}为渲染时替换的占位符，机制见第三节）。

2.1 Frontmatter 字段

--- id: {{id}} slice: {{slice_number}}-{{slug}} mission: {{mission}} status: placeholder stage: wip verified: {{created_date}} against scaffold (rig scope create) created: {{created_date}} intent: {{intent_yaml}} depends_on: {{depends_on}} ---

2.2 正文七节

1. # Slice {{slice_number}} — {{title}}—— 切片标题，渲染后为# Slice 12 — Deprecate Legacy Flag这类形态。
2. ## Intent—— 记录意图原文。这是整个切片的锚点，后续一切计划与证据都要能回溯到这里。
3. ## Mini-requirements—— 简洁的一览式需求层（编号列表）。模板提示：弃用路径以**可观察结果（observable outcomes）**的形式写出；对于小型弃用，这一节可以就是整个计划。
4. ## Proof contract—— 承诺交付物的复选框清单，每条都是"迁移落地 / 移除干净"这类可验证结果，配证据收尾。
5. ## Target—— 回答"被弃用的东西是什么"。
6. ## Current state—— 回答"今天它是怎么工作的、什么依赖它"。
7. ## Migration—— 回答"离开它的路径是什么"。
8. ## Removal—— 回答"它什么时候、怎么被删除"。

其中 3、4 两节属于 SDLC 约定的切片必备三节（Intent / Mini-requirements / Proof contract），5～8 是弃用场景的专属增量；5、6 是"信息输入"，7、8 是"行动输出"，四个问题一问一答，缺一不可。

三、渲染机制与占位符：模板如何变成 SPEC.md

模板文件与 CLI 源码同目录存放（packages/cli/src/lib/scope-templates/），构建时随包发布。运行时由 templates.ts 负责定位与渲染：resolveTemplate按"源码树 → dist → 随包源码"三个候选根依次查找（templates.ts），保证本地开发与安装后的包都能读到模板；renderSliceTemplate(kind, opts)读取模板原文后，由applyPlaceholders完成替换（templates.ts）。

applyPlaceholders处理的占位符及默认行为如下：

值得注意的两个默认行为：{{intent}}与{{intent_yaml}}在未提供--intent时都会回退到标题，保证任何调用方都能渲染成功（源码注释称之为"backwards-compatible callers"，见 templates.ts）；{{depends_on}}缺省渲染为显式的[]——按 SDLC 约定 EC-1（sdlc-conventions.md），显式的[]是一种"声明"（此切片无硬依赖），而字段缺失才是"不确定（INDETERMINATE）"，二者语义不同。

四、用 rig scope slice create 生成弃用切片

backlog-deprecation通过rig scope slice create的子命令create触发，命令定义见 scope.ts：

rig scope slice create <mission> <slug> \ --template backlog-deprecation \ --title "Deprecate legacy --flag on rig up" \ --intent "Users have fully moved to --config; remove the legacy flag cleanly" \ --depends-on OPR.0.3.2.11

参数说明：

命令执行的核心流程（scope.ts）：

1. 校验--template合法性 → slugify → 查找 mission → 计算下一序号NN，生成文件夹NN-slug；
2. 铸造 dot-ID：sliceIdFromMission(missionId, nn)，形如OPR.0.3.2.12（OPR为项目前缀、0.3.2为版本、12为切片序号，格式见 types.ts）；
3. 渲染 SPEC.md 正文（renderSliceTemplate）与 PROOF.md（renderSliceProofTemplate）；
4. 在同一个写边界内持久化父 mission ID、创建切片目录并落盘四个工件：SPEC.md、PROGRESS.md（进度清单）、slice.yaml（切片清单）、PROOF.md（证据摘要），以及proof/证据目录；
5. 任何一步失败则整体回滚（fs.rmSync删除切片目录、恢复 mission README 原文），保证"校验阶段零写入、写入阶段零半成品"。

生成后的切片目录结构：

backlog/ └── slices/ └── 12-deprecate-legacy-flag/ ├── SPEC.md # 由 backlog-deprecation 模板渲染而成 ├── PROGRESS.md # 验收清单（模板：slice-progress.md） ├── PROOF.md # 证据摘要（模板：proof.md） ├── slice.yaml # 切片清单 └── proof/ # 证据工件目录

五、弃用四问的填写实战指南

backlog-deprecation模板把弃用工作压缩成四个必须回答的问题，这也是它与普通特性切片最大的区别。以下结合仓库约定给出每个问题的填写要领。

## Target（弃用什么）点名被弃用的具体事物：某个命令 flag、某个 API 端点、某个配置键、某个默认行为或某个内置 skill。要具体到"哪个文件哪一行"的可定位程度——SDLC 约定 A4 明确要求，当实现发现意图依赖的某个能力根本不存在时，要在文档里"按来源指名每个缺失能力，并给出证明其缺失的文件与行号"（sdlc-conventions.md）。弃用切片的 Target 节同理：说清"要告别的是哪一段字节/行为"，而不是"有个旧东西很烦"。

## Current state（现状如何）回答两个子问题：今天它是怎么工作的；当前谁在依赖它。依赖清单是迁移排期的输入——--depends-on只能表达切片间构建顺序，真正的调用方分析要写在这里。如果现状不明，模板的诚实做法是写出"未知"，而不是含糊带过（SDLC 约定 A6：unknown 报告为 unknown，不是 failure，sdlc-conventions.md）。

## Migration（迁移路径）给出"离开旧行为"的具体路径：新行为是什么、调用方如何切换、切换是否有过渡期、是否需要双写（dual-write）或兼容垫片。迁移要写成可观察结果，例如"所有rig up --flag调用方切换到--config后，rig ps输出不再出现 legacy 列"，而不是"修好它"这种不可验证的表述。

## Removal（何时移除）定义删除条件与删除动作：满足什么信号后允许删除（如依赖方全部迁移、观测窗口内零回退）、删除时执行什么（删代码、删文档、删测试还是降级为注释）、删除后如何验证"移除是干净的"。模板的 proof contract 提示语"the removal is clean — captured"正是要求这个验证结果要被证据捕获，而不是口头宣称。

四个问题共同构成一次弃用的"完整叙事"，这正是模板在 backlog-deprecation.md 中要求的写作基调——它服务于"下一个读者"：无论是人类审查者还是接手该切片的 Agent，只读 SPEC.md 就能还原完整决策链。

六、Mini-requirements 与 Proof contract：把弃用写成可验证结果

模板的## Mini-requirements与## Proof contract两节不是普通的待办清单，它们遵循 SDLC 约定的工件规范（sdlc-conventions.md）：

• Mini-requirements是"人类操作者的第一结构化检查点"，审批从这里开始。模板明确：弃用路径以可观察结果写出，小型弃用可以整节即计划；
• Proof contract是 Markdown 复选框列表，每条是一个承诺交付物，以可观察结果书写，例如：

## Proof contract - [ ] The deprecation path as observable outcomes. For a small deprecation this may BE the whole plan.

渲染后应由作者改写为具体交付物，例如：

## Proof contract - [ ] Legacy `--flag` removed from `rig up` and its help text — captured. - [ ] All in-repo call sites migrated to `--config` — captured. - [ ] `rig ps` no longer renders the legacy column — captured.

• 每条交付物会被按"条目文本或 1-based 序号"与证据工件配对——这个配对正是 UI 的 DELIVERED 区渲染的内容，人类审查者不需要在几十个工件里翻找"哪个证明哪条"；
• 若弃用涉及 UI 交付物，则计划时必须附带 mockup（plannedRef），无 mockup 的 UI 切片是不完整计划；纯后端/技能/Markdown 类弃用不需要 mockup，这不算缺口也不算门槛（sdlc-conventions.md）。

七、证据落地：rig proof add 与 C1 头

弃用切片"未完成"的判定标准只有一个：承诺的结果还没有证据。证据不允许手工放置，必须通过rig proof add落地。命令定义见 proof.ts：

rig proof add 12-deprecate-legacy-flag \ --artifact-type qa \ --verdict PASS \ --candidate-sha <迁移完成后的提交 SHA> \ --money-evidence "legacy flag removed; 3 call sites migrated; ps no longer renders legacy column" \ --evidences "1,2,3" \ --media "up-help.png,ps-output.txt" \ --self-check "I looked at the captures; they show the flag is gone and call sites migrated"

关键参数语义：

proof add一次 drop 写一个 C1 头 + 工件文件；drop 时即校验（--media传绝对路径会被拒绝；文件尚不存在会告警显示 unavailable，见 proof.ts）。审计（rig scope audit）会兜底检查proof/里是否有带合法 C1 头的工件（sdlc-conventions.md）。

反模式：不经过 drop、直接往proof/塞文件——这样交付物不会被配对，在 DELIVERED 视图里永远是unverified。弃用切片的移除证明尤其要遵守"媒体必须经--media挂到 drop 上"这一条。

八、SOP 执行路径：从 COMPONENT MENU 到验证

模板末尾的 SOP 说明（backlog-deprecation.md）指向的是一整套可复用的执行规范，核心都在 sdlc-conventions.md 里：

1. 先读 COMPONENT MENU，别假设重流程。该文档是"菜单而非流水线"：每条 mission 按需挑选组件。默认路径是PART A 简单 SDLC（意图 → 构建 → 亲眼测试 → 如实记录验证过/未验证的 → 交接或停止），对小型弃用切片，这一条流就是全部。PART B 严格覆盖层（proof contract、plan-lock、C1 drops、proof-lock）只在该工作被显式指定时才生效——模板强调"do not assume the heavy flow unless your mission or dispatch assigns it"。

2. 规划严格度按 P0–P4 刻度选择。P0 最小需求 + 指针（简单可逆工作）；P1 带 proof contract 的书面 SPEC（默认）；P2 加冻结前调研轮；P3 加非作者的对抗评审；P4 加盲写初稿与既有方案 diff（sdlc-conventions.md）。一个依赖面很大的弃用切片可能值得 P2/P3，一个小 flag 的移除 P0 就够——刻度由工作本身决定。

3. 完整流程交给 mission-slice-sop skill。该 skill 是"操作手册"，在技能索引中登记为："you're working a mission/slice (the SDLC: intent → mini-requirements + proof contract → build → QA → proof). The operating manual"（openrig-skills/SKILL.md），并由启动引导技能在开始 mission/slice 工作时加载（agent-startup-and-context-ingestion/SKILL.md）。

4. 每天跟踪 PROGRESS.md，证据只经 drop 落地，最后用rig scope audit验证。rig scope audit是只读审计（scope.ts）：检查章节标题是否齐全、proof contract 是否成形、proof/工件是否带合法 C1 头；它"记录并建议、永不阻塞写路径、永不把退出码变成门槛"（sdlc-conventions.md）。

若弃用工作被指定走 PART B，则追加两个锁：rig scope slice approve <slice> --scope spec（plan-lock，锁定"要构建的工件集"）与--scope delivery（proof-lock，终态签收，触发冻结）；批准是冻结/签收，绝不等于 proven-green——proven-green 必须由 C1 证据工件承载（sdlc-conventions.md）。

九、一个完整的弃用切片示例

综合以上机制，一次小型弃用切片从创建到落证的全貌如下（以假设的rig up --flag弃用为例）：

创建：

rig scope slice create backlog deprecate-legacy-flag \ --template backlog-deprecation \ --title "Deprecate legacy --flag on rig up" \ --intent "rig up --flag is fully superseded by --config; migrate call sites and remove the flag" \ --depends-on OPR.0.3.2.11

生成的 SPEC.md（渲染后要点）：

--- id: OPR.0.3.2.12 slice: 12-deprecate-legacy-flag mission: backlog status: placeholder stage: wip verified: 2026-09-30 against scaffold (rig scope create) created: 2026-09-30 intent: "rig up --flag is fully superseded by --config; migrate call sites and remove the flag" depends_on: ["OPR.0.3.2.11"] --- # Slice 12 — Deprecate Legacy --flag on rig up ## Intent rig up --flag is fully superseded by --config; migrate call sites and remove the flag. ## Mini-requirements 1. No `--flag` invocation remains in-repo; all migrated to `--config`. 2. `rig up --help` no longer lists `--flag`. 3. `rig ps` and `rig up` run clean with no legacy warnings. ## Proof contract - [ ] Legacy `--flag` removed from `rig up` and its help text — captured. - [ ] All in-repo call sites migrated to `--config` — captured. - [ ] `rig ps` no longer renders the legacy column — captured. ## Target `--flag` on `rig up`（见 packages/cli/src/commands/up.ts 的 flag 解析段）. ## Current state `--flag` 目前与 `--config` 等价生效；3 个内部调用点仍使用 `--flag`（demo/run.sh、packages/cli/test/up.test.ts 等）。 ## Migration 调用点切换到 `--config`；保留一个过渡告警（当 `--flag` 被传入时提示 deprecated）直至移除。 ## Removal 当所有调用点迁移且观测窗口（两周）内无 `--flag` 回退后删除 flag 解析与告警分支；以 `rig proof add` drop 记录删除后 `rig up --help` 输出作为证据。

收尾证据：

rig proof add 12-deprecate-legacy-flag \ --artifact-type qa \ --verdict PASS \ --candidate-sha abc1234 \ --money-evidence "flag removed from parser and help; 3 call sites migrated; zero legacy warnings" \ --evidences "1,2,3" \ --media "help-output.txt" \ --self-check "I read help-output.txt and grep -R --flag; both confirm removal"

最后用rig scope audit复查章节完整性与证据配对，切片的弃用旅程即告闭环。这个流程把"弃用"从一次随手删除变成一条可回放、可审计、可交接的工程记录——这正是 OpenRig 切片体系的意图所在。

• 人工智能
• AI Agent
• 多智能体
• Agent 编排
• 代码智能体
• CLI