遗留系统理解、渐进式现代化

遗留系统往往文档缺失、测试薄弱、技术栈老旧且隐含大量历史约束。代理在这类系统中最大的价值不是"立刻重写"，而是先读懂、锁定行为、小步安全演进。本节给出可复用的渐进式现代化路线。

一、第一阶段：只读建模，摸清现状

• 用只读探索子代理梳理：程序入口、核心模块、关键数据流、外部依赖、定时任务/接口边界与数据存储关系。
• 产出现状说明：模块职责、调用关系、风险热点（缺测试、历史补丁、晦涩逻辑、外部系统耦合点）。
• 对不明语义保持取证态度：优先以代码、日志、调用方与现有行为为准；无法确定的行为显式标注为待确认，不臆测推断。
• 把摸清的架构结论与团队约定写入项目记忆，后续会话不必从零摸索（呼应第 9 章记忆治理）。

二、第二阶段：行为锁定，先补保护网

1. 为关键路径补充特征测试或行为基线（现有输出、边界条件、错误返回），把"当前真实行为"固定下来。
2. 在能稳定构建、能跑基线检查的前提下才进入改造；缺少自动化检查时，先建立最小可重复的验证方式。
3. 把已知高危边界单列：对外接口、数据迁移、权限/认证、定时批处理、并发与外部集成，单独评审处理。

三、第三阶段：绞杀式渐进替换

步骤	做法	代理承担的工作
划定边界	选择低耦合、收益明确的模块先迁移	分析依赖、给出候选顺序与风险评级
并行过渡	新实现与旧逻辑并行，逐步切换流量/调用	生成草稿、适配层代码、测试用例与迁移清单
小步替换	每次只迁移一小块并通过基线验证	按测试驱动实现、自检并报告偏差
下线旧代码	确认无调用后删除，避免新旧混杂长期腐化	扫描残留引用、整理删除说明

四、代理与人工的分工原则

• 代理擅长：代码探索、现状文档、迁移方案草案、测试草稿、机械重构与变更影响清单。
• 人工把关：架构方向、兼容性裁决、数据迁移策略、上线窗口与回滚决策、安全合规审查。
• 每个安全节点用版本控制固化（提交/检查点），保证任何一步可回到可运行状态；检查点不替代 git，正式基线仍以提交为准。

五、必须避免的陷阱

• 大爆炸式重写：在缺少测试与完整理解时一次性替换，风险不可控。
• 把猜测当事实：对历史逻辑想当然，改造后改变了隐藏业务行为。
• 只追求技术栈新鲜度而忽略业务连续性与兼容成本。
• 改造后不更新文档与记忆，下一轮又回到"系统看不懂"的状态。