企业官网建设流程全解析

agents 插件实战：用 legacy-modernize 命令编排 Strangler Fig 模式的老旧系统渐进式现代化迁移

【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents

本篇文章基于 GitHub 推荐项目精选 agents24 / agents 仓库中plugins/framework-migration插件提供的legacy-modernize命令，完整剖析一个可落地的老旧系统现代化编排工作流：从技术债盘点、依赖与集成映射、业务风险分级，到测试覆盖建立、Strangler Fig 基础设施搭建、分波次组件迁移、安全加固、性能验证、渐进式灰度，直至停用与文档交接。读完本文，你将掌握该命令的完整行为契约（状态机、检查点、子代理调用、文件产物规范），并理解它与仓库内framework-migration-legacy-modernizer、framework-migration-architect-review两个本地 agent 的协作机制，可直接在 Claude Code 等多 harness 环境中复用于真实迁移项目。

命令概览：一条命令，一套完整的迁移编排协议

legacy-modernize是 plugins/framework-migration 插件下三个命令之一（另两个为 code-migrate.md 与 deps-upgrade.md）。它不是一个"帮写几段迁移代码"的轻量提示词，而是一个带状态机、带硬性执行顺序、带人工审批闸门的多阶段编排命令。

命令的 YAML frontmatter 定义了它的触发语义与参数形态：

--- description: "Orchestrate legacy system modernization using the strangler fig pattern with gradual component replacement" argument-hint: "<legacy codebase path or description> [--strategy parallel-systems|big-bang|by-feature|database-first|api-first]" ---

其中description是该命令在 agent 决策时被检索与匹配的"触发描述"，明确点出了核心方法：Strangler Fig（绞杀藤）模式 + 渐进式组件替换。argument-hint则告诉调用方如何构造参数：第一个位置参数是要现代化的老旧代码库路径或描述（命令中统一记作$TARGET），--strategy可选值包括parallel-systems（并行系统）、big-bang（大爆炸式）、by-feature（按功能）、database-first（数据库优先）、api-first（API 优先），缺省值为parallel-systems。

按仓库的 authoring 规范，命令文件属于插件内容的四大类型之一（commands/<name>.md），由适配层在不同 harness 间转换（Codex 转换为 skill、Copilot 输出为 slash-command 提示词），因此该命令可在多种 harness 中复用，且其正文对$ARGUMENTS的引用遵循"把参数当数据"的规范。

参数解析与状态初始化

命令在执行前先完成三项前置检查（Pre-flight Checks）：

1. 检查既有会话：若.legacy-modernize/state.json存在且status为"in_progress"，则读取它并向用户展示当前步骤，询问"从上次断点继续"或"全新开始（归档旧会话）"；若状态为"complete"，则询问是否归档并重新开始。
2. 初始化状态：创建.legacy-modernize/目录与state.json，初始结构如下：

{ "target": "$ARGUMENTS", "status": "in_progress", "strategy": "parallel-systems", "current_step": 1, "current_phase": 1, "completed_steps": [], "files_created": [], "started_at": "ISO_TIMESTAMP", "last_updated": "ISO_TIMESTAMP" }

3. 解析目标描述：从$ARGUMENTS中提取 flags 之前的部分作为$TARGET，供后续所有子代理 prompt 引用。

这套状态机的价值在于：迁移项目通常跨越数天到数周，会话随时可能中断，而state.json让工作流可以在任何断点精确恢复，且所有中间产物都落盘到.legacy-modernize/，不依赖模型上下文窗口的记忆。

六条不可违反的行为铁律

命令开篇即声明CRITICAL BEHAVIORAL RULES，违反任何一条即视为失败。这六条规则构成了整个编排的"宪法"：

1. 按顺序执行步骤：不得跳步、重排或合并步骤。
2. 每一步必须落盘：每个步骤在进入下一步之前，必须先在.legacy-modernize/中产出自己的输出文件；后续步骤读取前序步骤的文件，不得依赖上下文窗口记忆。
3. 在检查点停车：到达PHASE CHECKPOINT时必须停止，使用 AskUserQuestion 工具给出明确选项，等待用户显式批准后才继续。
4. 失败即停：任何步骤失败（agent 报错、测试失败、依赖缺失）立即停止，呈现错误并询问用户如何处理，不得静默继续。
5. 仅使用本地 agent：所有subagent_type引用只使用本插件自带的 agent 或general-purpose，无跨插件依赖。
6. 绝不自主进入计划模式：不得调用 EnterPlanMode，因为"这条命令本身就是计划"，直接执行。

规则 1、2、4 共同保证了工作流的确定性、可审计性与可恢复性；规则 5 与仓库的插件自治设计一致——按 authoring.md 的要求，agent 名必须全局唯一（采用<plugin-directory>-<agent-file-stem>的插件级命名），CI 还会运行 check_agent_name_collisions.py 防止命名冲突，这正是"只依赖本地 agent、不跨插件耦合"能在多插件并装环境下成立的基础。

Phase 1：遗留系统评估与风险分析（步骤 1–3）

Step 1：遗留系统全面分析

命令使用 Task 工具，以subagent_type="framework-migration-legacy-modernizer"派发子代理，prompt 要求对$TARGET代码库做迁移就绪度分析：

• 建立技术债清单：过时依赖与废弃 API、安全漏洞与性能瓶颈、架构反模式；
• 生成迁移就绪度报告：组件复杂度评分（1–10）、模块间依赖映射、数据库耦合分析、速赢项（quick wins）与复杂重构目标的区分。

产出保存为.legacy-modernize/01-legacy-assessment.md，随后更新state.json（current_step置 2、将01-legacy-assessment.md加入files_created、step 1 加入completed_steps）。

这里引用的framework-migration-legacy-modernizer是本插件自带的专用 agent（见 legacy-modernizer.md），其定位是"关注安全、增量升级的遗留系统现代化专家"，聚焦领域包括框架迁移（jQuery→React、Java 8→17、Python 2→3）、数据库现代化（存储过程→ORM）、单体拆微服务、依赖升级与安全补丁、遗留代码测试覆盖、API 版本化与向后兼容。它的方法论与本文档完全同构：Strangler Fig 渐进替换、先补测试再重构、保持向后兼容、用特性开关灰度。换句话说，命令文档是"编排协议"，而 agent 文件是"执行专家的人设与能力声明"。

Step 2：依赖与集成映射

读取01-legacy-assessment.md后，改用subagent_type="framework-migration-architect-review"生成依赖图与集成点目录，交付物包括：

1. 内部模块依赖；
2. 外部服务集成；
3. 共享数据库 schema 与跨系统数据流；
4. 需要 Facade 模式或适配层保护的集成点；
5. 需要解决的循环依赖与紧耦合。

产出保存为.legacy-modernize/02-dependency-map.md。framework-migration-architect-review（见 architect-review.md）是仓库中能力最全面的架构评审 agent 之一，明确覆盖了反腐层（Anti-corruption layers）与适配器模式、事件驱动架构、Saga/Outbox、熔断器/舱壁等分布式模式，恰好与 Step 2 要求的"Facade/适配层识别"以及后续 Phase 3 的基础设施建设形成能力闭环。

Step 3：业务影响与风险评估

这一步切换为general-purpose子代理，扮演"技术转型与风险评估方向的业务分析师"，要求输出：

1. 风险评估矩阵，考量：业务关键性（收入影响）、用户流量模式、数据敏感度、监管要求、回滚复杂度；
2. 加权排序的组件优先级：(业务价值 × 0.4) + (技术风险 × 0.3) + (速赢潜力 × 0.3)；
3. 每个组件的回滚策略；
4. 推荐的迁移顺序。

产出保存为.legacy-modernize/03-business-impact.md。

PHASE CHECKPOINT 1 — 用户审批闸门

到达第一个检查点，命令强制停止并展示 Phase 1 三份产物的摘要（关键组件、风险等级、推荐迁移顺序），询问用户三个选项：

Legacy assessment and risk analysis complete. Please review: - .legacy-modernize/01-legacy-assessment.md - .legacy-modernize/02-dependency-map.md - .legacy-modernize/03-business-impact.md 1. Approve — proceed to test coverage establishment 2. Request changes — tell me what to adjust 3. Pause — save progress and stop here

只有选择选项 1 才能进入 Phase 2；选 2 则修订后重新检查点；选 3 则更新state.json状态并停止。这个"人工审批闸门"把高风险阶段转换控制在人手中，是整条命令风险治理的核心设计。

Phase 2：测试覆盖建立（步骤 4–6）

Step 4：遗留代码测试覆盖分析

以general-purpose子代理扮演"遗留系统特征化测试方向的测试自动化工程师"：

1. 使用覆盖率工具识别未测试代码路径、缺失的集成测试与缺失的端到端场景；
2. 对覆盖率 <40% 的组件，生成特征化测试（characterization tests），捕获当前行为但不修改功能；
3. 为安全重构建立测试台架；
4. 遵循项目现有测试模式与框架。

产出保存为.legacy-modernize/04-test-coverage.md。这一步骤与framework-migration-legacy-modernizeragent 的"先加测试再重构"方法论（Approach 第 2 条）完全呼应——特征化测试是 Strangler Fig 迁移中"确保行为不变"的保险丝。

Step 5：契约测试实现

以general-purpose子代理扮演"契约测试与 API 验证方向的测试自动化工程师"：

1. 为 API、消息队列交互、数据库 schema 创建消费者驱动契约（consumer-driven contracts）；
2. 在 CI/CD 管道中配置契约验证；
3. 生成响应时间与吞吐量的性能基线，用于验证现代化组件仍满足 SLA；
4. 遵循项目现有测试模式与框架。

产出保存为.legacy-modernize/05-contract-tests.md。

Step 6：测试数据管理策略

以general-purpose子代理扮演"测试数据管理与数据管道设计方向的数据工程师"：

1. 为边界场景创建数据生成脚本；
2. 对敏感信息实现数据脱敏（data masking）；
3. 建立测试数据库刷新流程；
4. 在迁移期间建立遗留组件与现代化组件间的数据一致性监控。

产出保存为.legacy-modernize/06-test-data.md。Step 6 的"并行系统运行期数据一致性监控"直接服务于 Step 7 即将搭建的双系统并行基础设施——迁移期间新旧两套系统同时服务流量，数据一致性是最容易出问题的环节。

PHASE CHECKPOINT 2 — 用户审批闸门

展示 Phase 2 三份产物并询问同样三选项（批准进入 Phase 3 / 请求修改 / 暂停存档），未批准不得进入 Phase 3。

Phase 3：增量迁移实施（步骤 7–9）

Step 7：Strangler Fig 基础设施搭建

以general-purpose子代理扮演"分布式系统与迁移基础设施方向的资深后端架构师"：

1. 配置API 网关，实现新旧组件间的流量路由；
2. 用环境变量或特性管理服务搭建特性开关（feature flags），支持渐进灰度；
3. 实现代理层，基于 URL 模式、请求头或用户分群制定路由规则；
4. 实现熔断器与降级机制保证韧性；
5. 建立双系统监控的可观测性看板；
6. 遵循项目现有基础设施模式。

产出保存为.legacy-modernize/07-infrastructure.md。这正是 Strangler Fig 模式的落地骨架：API 网关负责把流量"绞杀"式地从旧系统切向新系统，特性开关让每次切换都可控、可逆。

Step 8：组件现代化——第一波

命令要求先读取01-legacy-assessment.md、03-business-impact.md、04-test-coverage.md、07-infrastructure.md四份文件，从遗留评估中探测目标语言/技术栈，然后以general-purpose子代理扮演"目标语言专家"，prompt 中的角色描述为You are an expert [DETECTED LANGUAGE] developer specializing in legacy code modernization，随后对第一波组件（评估中识别的速赢项）执行：

1. 从遗留代码中抽取业务逻辑；
2. 用现代模式实现（依赖注入、SOLID 原则）；
3. 通过适配器模式保证向后兼容；
4. 用事件溯源（event sourcing）或双写（dual writes）维持数据一致性；
5. 遵循 12-factor 应用原则；
6. 运行特征化测试验证行为被保留。

命令特别注明：将[DETECTED LANGUAGE]替换为从遗留评估中实际检测到的语言（如 Python、TypeScript、Go、Rust、Java）；若代码库是多语言（polyglot），则为每种语言并行启动 agent。产出保存为.legacy-modernize/08-first-wave.md。这一步是整条命令的"重活"所在，其"适配层保兼容 + 双写保数据一致 + 特征化测试验证行为"三件套，与 legacy-modernizer agent 的 Output 定义（兼容层/适配层、行为保留测试、回滚流程）一一对应。

Step 9：安全加固

以general-purpose子代理扮演"应用安全审计、OWASP 合规与安全编码方向的工程师"，对已现代化组件执行：

1. 适用处实现 OAuth 2.0/JWT 认证；
2. 增加基于角色的访问控制（RBAC）；
3. 实现输入校验与清洗；
4. 验证 SQL 注入防护与 XSS 防护；
5. 配置密钥管理（secrets management）；
6. 验证 OWASP Top 10 合规；
7. 配置安全响应头并实现限流（rate limiting）。

要求产出按严重级别（Critical/High/Medium/Low）分级的审计报告并列出全部加固改动，写入.legacy-modernize/09-security.md。

PHASE CHECKPOINT 3 — 用户审批闸门

展示 Phase 3 三份产物，并特别要求总结09-security.md中的 Critical/High/Medium 漏洞计数，询问是否批准进入 Phase 4。

Phase 4：性能验证与发布（步骤 10–11）

Step 10：性能测试与优化

以general-purpose子代理扮演"负载测试、基准测试与应用性能优化方向的性能工程师"，对照新旧组件：

1. 模拟生产流量模式运行负载测试；
2. 测量响应时间、吞吐量与资源利用率；
3. 识别性能回退并优化：数据库查询加索引、缓存策略、连接池、异步处理；
4. 对照 SLA 验证：P95 延迟须在基线 110% 以内。

要求提供带对比表格的性能测试结果与优化建议，产出保存为.legacy-modernize/10-performance.md。这里引用的性能基线与 SLA 阈值来自 Step 5 的契约测试产物，体现了步骤间的数据依赖链。

Step 11：渐进式发布计划

以general-purpose子代理扮演"渐进交付、特性开关管理与生产发布策略方向的部署工程师"：

1. 配置特性开关的流量切换阶梯：5% → 25% → 50% → 100%；
2. 定义自动回滚触发器：错误率 >1%、延迟超过基线 2 倍、或业务指标恶化；
3. 每个阶段之间设置24 小时观察期；
4. 编写完整的流量切换 runbook；
5. 为每个阶段提供监控查询与看板。

产出保存为.legacy-modernize/11-rollout.md。这与仓库中大量渐进交付实践一脉相承，也与 deps-upgrade.md 中"增量升级 + 回滚点"的设计哲学一致：任何变更都必须可灰度、可回滚。

PHASE CHECKPOINT 4 — 用户审批闸门

展示10-performance.md与11-rollout.md，总结关键性能指标，询问是否批准进入 Phase 5（停用与文档）。

Phase 5：迁移完成与文档（步骤 12–13）

Step 12：遗留组件安全停用

重新调用subagent_type="framework-migration-legacy-modernizer"，规划已替换遗留组件的安全停用：

1. 通过流量分析确认无剩余依赖（最少 30 天 0% 流量观察期）；
2. 归档遗留代码并记录原始功能文档；
3. 更新 CI/CD 管道，移除遗留构建；
4. 清理未使用的数据库表、下线废弃 API 端点；
5. 对任何保留的遗留组件记录日落时间表（sunset timeline）。

产出保存为.legacy-modernize/12-decommission.md。注意 30 天观察期与 Step 11 的 24 小时阶段观察期形成两层时间尺度：前者用于证明"旧系统确实没流量了"，后者用于灰度阶段的快速反馈。

Step 13：文档与知识移交

读取此前所有.legacy-modernize/*.md文件，以general-purpose子代理扮演"系统迁移文档与开发者知识移交方向的文档工程师"：

1. 创建架构图（迁移前/后）；
2. 编写带迁移指南的 API 文档；
3. 编写双系统运行的 runbook；
4. 编写常见问题排障指南；
5. 产出经验教训报告（lessons learned）；
6. 为现代化后的系统生成开发者上手指南；
7. 记录迁移中的技术决策与权衡（trade-offs）。

产出保存为.legacy-modernize/13-documentation.md。这份文档包既是知识资产，也是项目收尾的正式交付物。

完成：收尾与成功标准

最后一步更新state.json（status置"complete"、刷新last_updated），并向用户呈现完整的会话文件清单与成功标准：

Legacy modernization complete: $TARGET ## Session Files - .legacy-modernize/01-legacy-assessment.md — Legacy system analysis - .legacy-modernize/02-dependency-map.md — Dependency and integration mapping - .legacy-modernize/03-business-impact.md — Business impact and risk assessment - .legacy-modernize/04-test-coverage.md — Test coverage analysis - .legacy-modernize/05-contract-tests.md — Contract tests and baselines - .legacy-modernize/06-test-data.md — Test data management strategy - .legacy-modernize/07-infrastructure.md — Strangler fig infrastructure - .legacy-modernize/08-first-wave.md — First wave component modernization - .legacy-modernize/09-security.md — Security audit and hardening - .legacy-modernize/10-performance.md — Performance testing results - .legacy-modernize/11-rollout.md — Progressive rollout plan - .legacy-modernize/12-decommission.md — Decommissioning checklist - .legacy-modernize/13-documentation.md — Documentation package ## Success Criteria - All high-priority components modernized with >80% test coverage - Zero unplanned downtime during migration - Performance metrics maintained (P95 latency within 110% of baseline) - Security vulnerabilities reduced by >90% - Technical debt score improved by >60%

随后列出四项"下一步"建议：审查全部产出、执行11-rollout.md的渐进发布计划、按12-decommission.md进行 30 天迁移后监控、观察期结束后完成停用。

设计要点总结：这条命令为什么值得直接复用

纵观整条命令，可以从四个维度提炼其可复用价值：

1. 状态机驱动 + 产物落盘：13 个步骤对应 13 个.legacy-modernize/*.md产物，state.json贯穿始终（current_step、completed_steps、files_created、started_at、last_updated），任何一步中断都能断点续跑，产物链本身就是完整的迁移审计档案。
2. 人工审批闸门：四个 Phase Checkpoint 把"评估→测试→迁移→发布→停用"五个阶段用强制人工批准隔开，高危操作（流量切换、停用）前必然有人确认，配合"失败即停"规则，把失控风险压缩到最小。
3. 专家子代理分工：专用 agentframework-migration-legacy-modernizer负责遗留分析与停用规划，framework-migration-architect-review负责依赖图与集成点目录，其余业务分析、测试、安全、性能、部署、文档任务交给general-purpose扮演对应专家角色；多语言代码库还支持并行 agent。全部只依赖插件本地 agent，符合仓库的插件自治与全局唯一命名规范（见 authoring.md 与 check_agent_name_collisions.py）。
4. 量化成功标准：>80% 测试覆盖、零计划外停机、P95 延迟 ≤ 基线 110%、安全漏洞减少 >90%、技术债评分改善 >60%——这些可度量指标让"迁移完成"不再是一句空话，而是可以验收的合同条款。

如果你正在面对一个老旧系统，想避免"大爆炸式重写"的高风险，这条命令提供的 5 阶段 13 步 + 4 检查点编排，加上 code-migrate.md（框架/语言/平台间迁移的代码级方案）与 deps-upgrade.md（依赖升级的安全路径），构成了 framework-migration 插件从"策略编排"到"代码执行"再到"依赖治理"的完整工具链，值得在真实迁移项目中直接套用或按此模式自定义。

【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents