重构开发工作流是做什么的？

使用此技能将架构重构转变为可交付的开发包。输出不仅仅是一张图表：它是一份关于将要构建的内容、如何迁移、如何测试以及哪些功能暂不支持的受限合约。将重构视为持续的迁移计划。每个包都是一个可审查的交付增量，而非指定或实现整个未来系统的承诺。

操作原则

区分权威与意图。 首先阅读当前代码、测试、架构权威和仓库说明。将重构文档标记为目标、计划或证据；切勿将其描述为当前行为。
命名现有事物。 将每个提议的模块映射到当前的类、合约、注册表、存储库或入口点。不要用杜撰的名词隐藏现有内容。
明确所有权。 说明每个边界拥有什么以及不得拥有什么，谁负责写入持久化事实，谁授权变更，以及谁负责恢复。
从真实消费者中赢取抽象。 仅当真实消费者移除了命名依赖、统一了真实注册或使不变性可强制执行时，才接纳新的抽象。通用抽象通常需要两个消费者；狭窄的安全边界可为一个消费者接纳。
从真实的垂直切片开始。 保留一个遗留测试夹具，并为同一场景添加一个目标边界测试夹具。合成图可以测试机制，但无法证明架构。
在替换前冻结合约。 在移除具体依赖之前，定义输入、输出、授权、身份、幂等性、失败、持久化、恢复和兼容性。
将性能视为证据，而非理由。 首先保留权威、持久化兼容性和恢复；然后针对当前路径测量等效工作负载。
保持文档可维护。 为每个声明指定一个规范所有者，保持当前/目标/历史状态可见，并链接到相应策略，而非在文档间复制。
规划增量交付。 每个增量包说明交付物、延期事项、下一个推进触发条件以及所需的推进证据。

工作流与模块加载

L1（层级 1）表示系统边界，L2（层级 2）表示稳定的模块/边界合约，L3（层级 3）表示任务特定的实现细节。将项目现有标签映射到这些含义，而非引入另一套分类体系。

首先确定合适的大小。阅读 references/deliverable-matrix.md 并选择使下一个决策可审查的最小交付包。以下阶段是完整路径，而非每个请求的强制性清单。仅当对应阶段或关注点处于激活状态时，才加载其他参考文档。

每个包或迁移增量必须声明其交付范围。交付矩阵拥有模式、仅设计缩减、延期事项和推进条件的定义。

阶段 0 — 解析权威与基线

阅读仓库说明、README、开发指南和架构权威（如果存在）。
在得出结论认为不存在更早的重构计划之前，搜索方向、文档、发布、迁移、任务和交接记录。
对于每个与请求相关的活跃计划，在定义新范围之前，阅读其最新的增量记录、审查决策、未解决的延期事项、未关闭的 L1/L2 声明、ADR 以及记录的下一个任务。
验证先前的推进触发条件和推进证据。如果任一条件未满足，或存在未关闭的阻塞性发现，则向用户说明当前状态和选项，然后再继续。如果用户授权例外，则在当前增量记录中记录原因、审批人和受影响的范围。
识别源层次结构和确切的基线版本。检查当前的入口点、状态/数据所有者、持久化、测试、示例和扩展注册表（如果存在）。
记录哪些已实现、哪些是目标意图以及哪些未知。
在声明减少耦合之前，创建一个可重现的依赖或注册清单：一个可重用的命令/脚本、一个已检入的输出或报告，以及用于前后对比的相同方法。

遵循仓库现有的任务台账、问题系统和交接格式。不要求特定的协作工具，也不将对话历史用作架构权威。

阶段 1 — 定位与范围

记录：

系统是什么，以及谁在其上构建；
当前耦合或增长导致的问题；
第一阶段部署边界；
非目标和延期能力；
有限的优势以及每个声明的比较基线。

同时，建立复杂度预算。加载 references/document-and-complexity-gates.md 以了解预算、文档所有权规则和停止条件。优先使用有限声明，而非“更模块化”或“更可扩展”之类的词语。

用户决策门

不要从代码或图表推断产品意图。当仓库证据无法回答关于范围、所有权、部署、兼容性、安全性、成功标准或迁移顺序等实质性问题时，暂停并向用户询问。捆绑相关选择，展示观察到的事实和权衡，并在有理由时推荐保守的默认值。

使用references/user-decision-gates.md获取针对特定阶段的问题和持久化记录位置。如果用户明确委托了实质性选择，则选择推荐或最有支持的可逆选项，记录委托事项和假设，然后继续。将非实质性的可逆假设明确化，而不是阻塞进度。

阶段 2 — 层级 1 目标架构

定义主要子系统或协调层面、状态/数据权威和唯一写入者、身份所有权、依赖方向、应用程序入口点、进程/部署边界以及受控通信形式。

在进入实现方向之前，L1 是必需的，并且必须明确定义范围内的目标。它无需描述每个未来模块，但不能使所有权、依赖方向或部署范围模糊。未解决的 L1 问题需命名所有者和决策门。

加载references/architecture-contracts.md以了解 L1 图表规则以及后续阶段使用的 L2/L3/接口模式。

阶段 3 — 当前到目标映射

对于每个当前热点，将第一个动作归类为保留、暴露、适配、拆分、合并、弃用或移除。记录当前所有者、目标所有者、保留的通信/持久化路径以及移除门。将交付范围作为详细延期事项的规范所有者。

不要仅仅因为某个主题有趣就创建文档。首先找到规范所有者；只有当所有权、状态、受众或生命周期存在实质性差异时，才创建新文档。

阶段 4 — 层级 2 模块合约

为每个稳定模块或跨模块边界创建一个 L2 合约。涵盖职责和非职责、当前组件、提供/需要的服务、可写权限、允许的调用/数据可见性、生命周期/失败、兼容性以及推迟到实现的决策。

在第一个包中，L2 可以是不完整的。将重要声明标记为已确立、有条件或未决。每个未决选择都需要一个有限的实验、证据阈值或能够解决它的实现门；不要为了表面光鲜而编造精确度。

使用references/architecture-contracts.md中的 L2 和交互形式规则。当包包含多个文档时，使用references/document-and-complexity-gates.md中的导航和规范所有者检查。

阶段 5 — MVP 和任务本地合约

选择能够行使预期边界的最小真实闭环。一个读/生命周期闭环切片可以优先于第一个写边界切片。仅当本地 MVP 标签与描述性名称配对时才保留它，并准确说明该切片证明了什么以及未证明什么。

在编码一个有限的实现任务之前，仅冻结该任务消费的 L3 合约。该 L3 合约保持候选状态，直到实现任务采用它或记录对其进行修订。不要为未选中的模块创建 L3 文档。使用references/architecture-contracts.md中的 L3 和接口检查清单。

阶段 6 — 对抗性审查与双向钢人法

进行一次试图打破所有权、恢复、兼容性、迁移和证据声明的对抗性审查，然后进行一次钢人法，陈述最强的价值和故意保守的边界。优先选择未编写该包的独立审查者；否则使用新上下文并披露该限制。

使用references/adversarial-review.md了解审查时机、问题和单一协调台账。立即处理每个发现。阻塞性发现使门保持关闭，直到风险被解决或由用户或独立审查者明确降级/接受为例外；仅拒绝或推迟它不会打开门。

阶段 7 — 迁移、验证与推进

定义分阶段迁移，包括兼容性层、中止条件、移除门、回滚/重启边界、遗留/目标测试夹具以及等效证据。仅在实现、兼容性证据和仓库权威更新合并在一起后，才将目标文本提升为当前架构。

在每个增量结束时，选择一个结果：继续、运行命名实验、修订目标/合约，或者停止并保留当前路径。下一个增量仅在其触发条件和推进证据满足时才开始。加载references/migration-and-promotion.md以了解详细的证据、实验和 ADR 规则。

阶段 8 — 交接与发布

在发布前：

验证元数据、链接、目录以及相关的一致性/回归检查；
检查完整差异以发现不相关的文件或未经支持的实施声明；
更新项目现有的变更/交接记录；
使增量记录可从方向或目录条目中发现；
说明确切的下一个任务和所有者。

除非用户授权该外部变更，否则不要创建 PR 或推送分支。当授权时，将包描述为目标设计/文档，除非运行时行为实际发生了变化。

可选关注点

插件、版本共存、进程隔离、热替换和动态卸载并非默认架构要求。仅当请求的设计实际激活了这些关注点之一时，才加载references/optional-concerns.md。

模块路由

需求	加载模块
选择最小的工件集和交付范围	`deliverable-matrix.md`
询问或记录实质性用户决策	`user-decision-gates.md`
定义 L1/L2/L3 或面向实现的接口	`architecture-contracts.md`
控制文档增长、复杂度或过度设计	`document-and-complexity-gates.md`
运行对抗性审查和钢人法	`adversarial-review.md`
规划迁移、实验、ADR 或推进	`migration-and-promotion.md`
设计插件、隔离或版本共存	`optional-concerns.md`

默认不加载所有模块。活跃阶段和请求的交付物决定需要哪些参考文档。

禁止事项

不要在证明一个真实切片之前重写整个代码库。
不要将每个文件/类变成插件。
不要在没有明确目标决策和失败模型的情况下创建重复的状态所有者、调度器、存储库、总线或生命周期权限。
不要通过重命名的透传包装器隐藏混合职责。
不要仅凭较低的依赖计数就声称解耦。
不要将合成演示用作主要的 MVP 退出条件。
不要让扩展清理暗示领域完成或销毁。
不要将任务笔记、基准分数或生成式散文视为当前架构权威。

重构开发工作流