---
name: soloforge-compatibility-assessment
description: 评估 brownfield 变更的调用方、数据、接口、部署和迁移风险。
when: 兼容性与迁移评估 / brownfield / 高影响变更
---

# 兼容性与迁移评估

## 适用性

修改既有接口、数据模型、目录、部署单元、配置格式或用户行为时使用。若无法枚举主要调用方和现状版本，先做发现，不得直接断言“兼容”。

## 事实输入

- 当前代码、接口、数据契约与演进资产、配置和部署拓扑。
- 调用方、客户端版本、数据量、流量、合规和停机约束。
- 监控、备份、回放、灰度和恢复能力。
- `template.md` 与 `examples.md`。

## 关键决策

- 兼容策略：保持、双轨、适配层、版本化、expand/contract 或明确 breaking change。
- 数据迁移采用可逆脚本、备份恢复或前向修复，按实际风险选择。
- 切换和退出条件必须可观测，并有用户或业务负责人确认。

## 产出方法

1. 按调用方、接口、数据、配置、部署和运维逐项建立影响矩阵。
2. 为每个影响记录现状证据、目标行为、兼容窗口和责任人。
3. 设计分阶段迁移、校验、灰度、停止和恢复步骤。
4. 对不可逆操作写备份、校验和演练要求。
5. 明确哪些风险已验证、哪些只评估、哪些仍未知。

## 禁止项

- 不得用“向后兼容”一句话覆盖字段、语义和行为差异。
- 不得默认 down migration 安全；涉及数据删除或重写时优先安全恢复方案。
- 不得漏掉离线任务、报表、缓存、搜索索引、第三方和旧客户端。
- 不得伪造调用方确认、演练结果或生产容量。

## 交付自检

- 所有已知消费者和数据路径都有结论或待确认责任人。
- breaking change 有版本、沟通、窗口和退出方案。
- 迁移步骤可暂停、可观察，失败后不会处于未知中间态。
- 风险分级与实际影响、概率和可恢复性一致。

## 权威验证

调用 `sf_verify action="full" task_id="当前任务ID" artifact="compatibility_assessment"`。随后确保 design、database、API、deployment 的真实产物与本评估一致；文档结构通过不等于迁移已演练。


## 交付前对抗审查

`sf_verify` 通过只证明结构/编译/测试层；语义质量（承接正确性、异常/并发/权限/边界是否可靠、是否含空话或无法证伪的承诺）须经独立对抗审查。advance/deliver 前用 `sf_review action="start" task_id="当前任务ID" artifact="<本产物 kind>"` 发起 per_artifact 审查，用**独立 session/subagent**（非产出本产物的同一会话）执行返回的 prompt、submit findings，按 next_step 完成 K 次独立采样与闭环。deliver 会阻断未完成/未闭环的审查；活跃豁免与被驳回 error 会被注入审查 focus 供独立复核。