医疗 IT 技术债迁移实战：用 HumanLayer 自定义 Claude Code Agent 一周完成 .NET 现代化改造-迪斯科星球

医疗 IT 技术债迁移实战：用 HumanLayer 自定义 Claude Code Agent 一周完成 .NET 现代化改造

【免费下载链接】humanlayerThe best way to get AI coding agents to solve hard problems in complex codebases.项目地址: https://gitcode.com/GitHub_Trending/hu/humanlayer

导读

本文以 HumanLayer 开源仓库中 docs/case-studies/healthcare-case-study.md 的案例研究为主体，剖析一家医疗 IT 公司如何借助自定义 Claude Code Agent 与高级上下文工程（Advanced Context Engineering）方法，将积压多年的 .NET Framework 4.5 平台在一周内迁移到 .NET Core 9.0。文中不仅完整还原了案例的挑战、实施路径、结果与关键经验，还结合本仓库中 hlyr、docs/workshop.mdx、CONTRIBUTING.md 等源码与文档，深入拆解"研究—规划—实施"工作流、Agent 化命令体系、thoughts 知识管理工具等底层支撑技术，帮助读者掌握一套可复制的"AI 驱动技术债治理"实战方案。

案例背景：一份在医疗 IT 领域"被搁置多年"的技术债

遗留系统如何拖慢创新

案例主角是一家医疗 IT 公司，其旗舰企业级平台长期停留在.NET Framework 4.5（2012 年发布、接近生命周期终点）之上。向现代 .NET Core 的迁移多年来一直在路线图上，却因以下原因被反复降级：

感知风险高：害怕在医疗关键系统中引入破坏性变更；
资源受限：工程团队忙于功能交付与合规审计；
复杂度高：代码库庞大，存在依赖复杂、遗留模式与大量未文档化行为；
无人愿意接手：没有工程师想"背锅"运行时升级可能引发的故障；
机会成本：预估需要 3–6 个月的专职工程时间。

技术债由此引发连锁问题：难以招聘熟悉过时技术的工程师、无法享受现代性能与安全特性、维护负担持续加重、在快速现代化的医疗 IT 竞争中处于劣势。

为什么传统团队不敢动这块"硬骨头"

从工程角度看，.NET Framework 4.5 → .NET Core 9.0 是一次跨运行时的大版本跃迁，涉及AppDomain、WCF 服务等大量不兼容 API，改造需要系统性排查依赖、重写异步模式、替换遗留库，还要保证医疗系统的合规与回滚安全。正因如此，该项目被"延迟—恐惧—再延迟"的循环困住多年——直到团队引入 AI 编码 Agent。

解决方案：自定义 Claude Code Agent + 高级上下文工程

12 Agent 原则框架：企业级 Agent 部署的"方法论底座"

案例中，顾问团队引入了12 Agent 原则框架，作为在企业环境中有效部署编码 Agent 的结构化方法论，用以指导 Agent 设计、提示词工程与工作流集成。该框架不是单一脚本，而是一整套关于"如何拆分职责、如何编写上下文、如何验收产出"的纪律约束——这正是 HumanLayer 仓库所倡导的工程化思路：Agent 不是玄学，而是需要被设计、被约束、被管理的工程组件。

四类自定义 Agent 的分工矩阵

针对迁移目标，团队设计了四个专职 Agent：

Agent	职责	对应案例工作阶段
Migration Analysis Agent（迁移分析）	梳理框架特定依赖与破坏性变更	Day 1–2 发现与规划
Code Modernization Agent（代码现代化）	将遗留模式重构为 .NET Core 等价实现	Day 3–5 代码迁移
Testing & Validation Agent（测试验证）	为迁移代码生成全面测试覆盖	Day 6 测试与验证
Documentation Agent（文档维护）	全程维护"活文档"	Day 7 文档与交接

这种"按阶段专职分工"的 Agent 拓扑，与仓库中 HumanLayer 的"研究 / 规划 / 实施"三命令工作流高度同构（见下文），本质上是将一次巨型迁移拆解为多个可验证的原子环节，每个环节由专用 Agent 负责、由人类工程师把关。

上下文工程：比提示词更重要的"富上下文"

案例强调，团队没有使用通用提示词，而是精心构造了包含以下要素的丰富上下文：

医疗领域需求与合规约束；
历史架构决策及其理由；
遗留代码库模式与约定；
平台特定的测试协议；
回滚流程与安全要求。

这正是 HumanLayer 文档反复强调的"高级上下文工程（Advanced Context Engineering）"核心理念：Agent 的能力上限取决于它拿到的上下文质量。仓库的 docs/workshop.mdx 将其总结为"research, plan, and implement workflows"，并提供了完整操作指南（见下一节）。

一周实施路线：从发现到交接的 Day-by-Day 复盘

Day 1–2：发现与规划

工程师与Migration Analysis Agent协作完成：

全量测绘 .NET Framework 4.5 依赖；
识别 .NET Core 9.0 中存在破坏性变更的 API；
生成带风险评级的迁移路线图；
制定回滚计划。

这一阶段对应仓库工作流中的/research_codebase命令：先让 Agent 通读 issue 与代码库，产出"哪些文件、哪些行号与问题相关"的研究输出，明确禁止在此时给出实现方案（详见下文"魔咒词"）。

Day 3–5：代码迁移

使用Code Modernization Agent系统性执行：

更新项目文件与依赖；
重构不兼容代码模式（如AppDomain、WCF 服务）；
现代化async/await模式以提升性能；
以 .NET Core 等价库替换遗留库。

Day 6：测试与验证

Testing Agent辅助完成：

为被修改代码生成补充单元测试；
运行完整集成测试套件；
对比原平台做性能基准测试；
针对新漏洞做安全扫描。

Day 7：文档与交接

最终交付包括：变更的自动化文档、面向团队的知识转移材料、含监控流程的部署 Runbook。

成果量化：速度、质量与最意外的人力回报

速度与资源效率

⚡快 40 倍：6.5 天完成，对比 6 个月的保守预估；
👤少 75% 资源：1 名工程师 vs 预估 3–4 人团队；
💰节省约 20 万美元+的工程成本。

质量与风险控制

✅ 首次尝试即成功部署到生产环境；
🎯 迁移后 30 天内零严重缺陷；
🔒 现代化运行时带来更优安全姿态；
📈 关键工作流性能提升 15–20%。

人力影响：超出预期的"意外收获"

带领迁移的工程师事后精力充沛，主动寻找更多现代化项目——这与技术债工作常见的倦怠形成鲜明对比，其心理价值不亚于技术成就：

团队士气提升，"不可能"的项目变得可达成；
其他工程师主动报名此前避之不及的现代化任务；
知识分享增加，Agent 辅助工作流被更多人采纳；
招聘因现代技术栈定位而改善。

⚠️ 需要说明的是：以上量化数据（40 倍、75%、20 万美元、15–20% 等）均来自原案例文档的自我报告，属于单一案例的陈述，未在本仓库代码中得到验证，引用时应标注其来源为案例自述而非行业通用基准。

案例背后的工程化支撑：HumanLayer 仓库的 Agent 工作流实现

案例提到的"自定义 Claude Code Agent"并非空中楼阁——HumanLayer 仓库中即可找到可落地的对应实现。这一节从仓库源码与文档出发，还原案例方法论在真实工程环境中的样子。

"研究—规划—实施"三命令工作流

仓库 CONTRIBUTING.md 给出了命令速查表：

/research_codebase—— 让 Agent 研究代码库、定位相关文件与行号；
/create_plan—— 基于研究输出制定分阶段实施计划；
/implement_plan—— 按计划实施（可指定只做某一阶段）；
/commit—— 生成提交信息；
gh pr create --fill—— 创建 PR；
/describe_pr—— 生成 PR 描述。

完整的操作细节记录在 docs/workshop.mdx（工作坊指南），它与案例研究构成"方法论 + 操作手册"的互补关系：案例展示了这套工作流在大规模迁移中的威力，工作坊则教你如何在任意仓库中复现。

工作流中的"魔咒词"（Magic Words）

工作坊文档特别强调了两个看似平淡却至关重要的提示词片段：

研究阶段，在让 Agent 阅读 issue 并调研代码库后，务必追加：

Do not make an implementation plan or explain how to fix.

（不要制定实现计划，也不要解释如何修复。）

规划阶段，在让 Agent 制定计划时，务必追加：

Work back and forth with me, sharing your open questions and phases outline before writing the plan.

（先与我来回讨论，分享你的开放问题与阶段大纲，再写计划。）

文档指出，这些"魔咒词"已内置于基础提示词（base prompt）中，但在每次调用时重复仍有价值——如果 Claude 直接写出计划文件而没有先提问澄清，就用带魔咒词的方式重试。这背后正是案例强调的"结构化原则"：用纪律约束 Agent 的行为边界，防止它跳过人类确认直接动手。

分阶段实施：长计划的会话级拆分

对于复杂迁移（如本案例 7 天的大型改造），工作坊建议按阶段拆分会话：

/cl:implement_plan - PATH_TO_PLAN.md Please implement the plan. YOUR ADDITIONAL INSTRUCTIONS HERE Just do phase 1, then update the plan with your progress and await further instructions and confirmation of the manual verification steps.

阶段 1 完成后，可开新会话继续：

/cl:implement_plan PATH_TO_PLAN.md phase 1 is done, just do phase 2, then update the plan with your progress and await further instructions and confirmation of the manual verification steps

这与案例中"按天分阶段、每阶段由专职 Agent 负责"的节奏完全对应——长周期技术债项目被拆成可独立验证的短周期单元，每一步都有人类确认点。

CLI 一键初始化：`humanlayer claude init`

案例团队"开发定制 Agent 和命令"的过程，在本仓库 hlyr/src/commands/claude/init.ts 中实现了自动化：humanlayer claude init命令会把预置的.claude配置复制到目标项目，内容包括：

Commands（约 30 个文件）：规划、研究、CI、代码生成、测试等工作流命令；
Agents（6 个文件）：面向代码分析、调试、架构审查的专职子 Agent；
Settings（1 个文件）：项目权限配置（settings.local.json通过.gitignore排除，见 init.ts 中的ensureGitignoreEntry实现）。

常用用法：

# 交互式初始化 humanlayer claude init # 免交互全量复制（适合 CI/CD） humanlayer claude init --all # 强制覆盖已有 .claude 目录 humanlayer claude init --force

交互模式下支持方向键选择、空格切换、Enter 确认、Ctrl+C 取消；非 TTY 环境必须加--all，否则报错退出（源码第 59–63 行有显式校验）。初始化时还可配置默认模型（opus/sonnet/haiku）、是否启用 always-on thinking 以及最大思考 token 数（默认 32000），并自动向settings.json写入CLAUDE_BASH_MAINTAIN_WORKING_DIR=1——这些细节正是"把上下文工程固化成工程配置"的体现。

知识管理：thoughts 系统让上下文跨项目沉淀

案例强调"将领域知识、历史架构决策、测试协议等写入上下文"——这些知识从哪来？仓库给出了答案：thoughts 系统（见 hlyr/README.md 与 hlyr/src/thoughtsConfig.ts）。

thoughts 在本地维护一个独立的 git 仓库（默认~/thoughts），把研究输出、计划、笔记等放在工作仓库之外，实现跨项目、跨团队的共享复用。其目录结构由源码 createThoughtsDirectoryStructure 定义：

~/thoughts/ ├── repos/ # 按仓库隔离的笔记（含 <user>/ 个人笔记 与 shared/ 团队共享） └── global/ # 跨仓库通用笔记（同样含 <user>/ 与 shared/）

常用命令：

humanlayer thoughts init # 初始化 humanlayer thoughts sync -m "Updated architecture notes" # 同步并更新搜索索引 humanlayer thoughts status # 查看状态 humanlayer thoughts profile create personal --repo ~/thoughts-personal # 多 profile

源码 ensureThoughtsRepoExists 会在仓库不存在时自动git init并完成首次提交，随后通过符号链接把团队成员的笔记目录映射回工作仓库——这恰好实现了案例中"历史架构决策与领域知识可被 Agent 检索"的前提。

环境配置：上下文注入的"最后一公里"

如何把领域上下文真正喂给 Agent？仓库 docs/introduction.mdx 展示了通过~/.claude/settings.json的env块注入自定义环境变量（如连接 Bedrock、设置CLAUDE_BASE_MAINTAIN_WORKING_DIR=1）：

// ~/.claude/settings.json { "env": { "CLAUDE_BASE_MAINTAIN_WORKING_DIR": "1", "BEDROCK_REGION": "us-east-1", "BEDROCK_MODEL": "us.meta.llama3-2-11b-instruct" } }

此外，HumanLayer CLI 提供了完整的人工介入通道（hlyr/README.md）：humanlayer contact_human可在脚本中向人类发消息并等待回复，humanlayer mcp claude_approvals可为 Claude Code 提供审批 MCP 服务器，配合--permission-prompt-tool mcp__approvals__request_permission使用——这正是医疗场景"严格人工审查、合规检查"护栏的工程化落地：

claude --print "write hello world to a file" \ --mcp-config mcp-config.json \ --permission-prompt-tool mcp__approvals__request_permission

关键经验：给医疗 IT 领导者的五条启示

案例在文末给出了五条总结，可视为将本次成功复制到其他组织的最小行动清单：

技术债如今"可偿还"了：AI 编码 Agent 从根本上改变了技术债治理的经济模型，曾经"太贵或太险"的项目如今可以高效推进；
上下文工程是分水岭：通用 AI 工具只能带来有限价值，而结合领域上下文、组织知识与结构化原则定制的 Agent 才能产生变革性结果；
人的因素同样重要：工具选型应评估心理影响，能让团队"充满干劲"而非"被替代"的技术会带来复利式收益；
从高价值、高畏惧的项目入手：因复杂度而非不确定性被推迟的项目，是 Agent 辅助开发的最佳候选；成功会积累势能；
医疗专属护栏必不可少：整个实施过程中保持严格的审查流程、合规检查与测试协议，以适配医疗关键系统。

其中第 5 条在仓库中有直接呼应：HumanLayer 的审批 MCP 与contact_human通道（hlyr/README.md）正是"把人类放进关键决策回路"的工程保障，与医疗行业的合规要求天然契合。

下一步：从一次成功到文化转型

受到这次成功鼓舞，该公司已将 AI 编码 Agent 项目扩展到：

微服务拆分：将单体服务分解为现代架构；
API 现代化：将遗留 SOAP 服务升级为 REST/GraphQL；
数据库优化：治理查询性能与 schema 债务；
安全修复：系统性处理累积的安全债务。

更重要的是，团队文化发生了转变：技术债不再被视为不可避免的负担，而是"可借助 Agent 快速改善的机遇"。案例作者最后给出的建议是：从能同时证明业务价值与积极团队影响的清晰胜利开始。

企业官网建设流程全解析