为 AI 智能体梳理遗留代码:经验与实践手册

如何按步骤让 AI 智能体进入遗留代码库:先摸清真实结构、保护既有行为,再用架构边界和自动化证据推动持续清理。

开发者在软件仓库中评估 AI 编程智能体的工作。

Ryan Lopopolo 是 OpenAI「Harness Engineering」蓝图的主要作者;截至 2026 年 9 月,他担任 Google Cloud Platform 智能体方向的首席工程师。他是 SpaceXSI 首席工程师 Lauren Tan(“Potato”)在技术与理念上最接近的同行。继 Tan 于 2026 年 11 月 11 日发表《All Code Is Slop (Except Mine)》之后,研究 Lopopolo 能为她的核心论点提供直接的操作层面参照:工程师的最高杠杆并非写出更长的 AGENTS.md 提示手册,而是把架构约束编码进代码边界、自定义 lint 规则和运行时验证机制。2026 年 AI Engineer 大会上的其他实践者也分享了其中一些理念,但 Lopopolo 特别接近 Tan 对 Electron 客户端运行时检查、机械化边界 lint 和仓库即输入的组合运用,并将其用于高频 PR 工作流。

从 Lopopolo 的经验中可以梳理出四层递进实践:用约 100 行的 AGENTS.md 路由图取代大部头说明文件,并指向版本化文档;通过错误信息可指导智能体自行修复的自定义 lint,严格执行依赖分层;运行后台「垃圾回收」式 PR,以控制代码库熵增;为智能体提供隔离的运行时可观测能力,让它们能以证据证明修改有效。

然而,要把这些经验用于老旧(brownfield)代码库 ,还必须补上一个重要缺口。Lopopolo 标志性的 OpenAI harness 实验从一个空白的 greenfield 仓库起步,并禁止人工编写代码;他也明确表示,如何跨越多年维护架构一致性仍是未解问题。此外,Tan 与 Lopopolo 报告的生产力和质量指标来自第一方大会演讲、工程博客、播客,以及厂商的二手案例研究,并非独立的对照基准。为避免把目标架构生硬套用到老旧、混乱的代码中,本文最后的实践手册将 Lopopolo 与 Tan 的护栏,同 Dexter Horthy、Mitchell Hashimoto、Boris Cherny 关于 brownfield 工作流的经验,以及 ast-grep、baseline、knip 等确定性工具结合起来。

为什么 Ryan Lopopolo 是 Lauren Tan 最接近的同行

Tan 与 Lopopolo 独立得出了相同的结构性诊断:智能体生成的「slop」会从哪里来。两人都观察到,编程智能体把现有仓库当作最重要的行为输入;因此,代码里遗留的混乱变通方案或已弃用模式,会被智能体照抄并不断放大。Tan 用花园作比喻:她的日常评审工作量从 2024 年的 3 个同事 PR,转变为每位工程师面对 300 多个智能体生成的 PR;若没有结构化护栏,杂草会迅速蔓延。Lopopolo 则把同一现象称为仓库「熵」,并主张以持续自动清理来应对。两人也都围绕 Electron 桌面应用构建工作流,并把 Chrome DevTools Protocol(CDP)直接接入智能体循环,让模型能验证真实 UI 行为,而不是只依赖人类阅读代码差异。

对照两人公开发表的经验,可以看到他们在机制上高度一致;差异则主要体现在形式化验证和自动化后台重构的侧重点上。

维度 Lauren Tan(SpaceXSI / Grabbot) Ryan Lopopolo(OpenAI Frontier & Symphony / Google Cloud)
核心论点 信任金字塔:优先把最强约束放在代码库设计、静态分析和验证中,而非散文式说明。 Harness Engineering:人类通过上下文和工具引导,智能体编写全部生产代码。
自述规模(2026) 每月 3,000 个个人 PR(团队约 11,000 个 PR);完成 6 个月基础建设后,相对回滚率约 0.5%;她指出多数 token 用于验证,与同行提到的 70% 相符。 据 ZenML 案例研究,每位工程师每周约 3.5 至 70 个 PR;据 OpenAI 与播客摘要,约 100 万行代码、人工代码和评审为 0%、每天约 10 亿 token,或每位工程师每月约 2,000 至 3,000 美元。
起步环境 在持续演进的 Grabbot 产品代码库中实践。 在 OpenAI Frontier 从空仓库开始,强调 harness 与工具基础设施。
架构约束 Dune 框架:通过显式边界和 lint 约束产品代码。 单向分层(Types 到 UI),并将 Providers 设为唯一的跨领域边界;自定义 lint 会给出可自我修复的错误说明。
代码库衰退防御 保持代码花园整洁,使智能体模仿良好模式而非有理由的临时变通。 定时运行后台 Codex 扫描,更新领域质量评级,并提交评审时间不到一分钟的小型重构 PR。
验证与评审 CDP 运行时检查、面向用户的功能地图、自定义 CLI,以及 TLA+、Lean 和 Bombadil UI 属性测试。 每个 worktree 独立启动应用、连接 CDP 获取快照,并搭建临时本地遥测(LogQL、PromQL、TraceQL);CI 中还会用不同评审角色进行检查。

由于 Lopopolo 的 OpenAI 团队从空仓库起步,仅研究他并不能解决现有代码库的实际问题。三位实践者可以补足 brownfield 机制。HumanLayer CEO Dexter Horthy 专门研究复杂和 brownfield 仓库,提出 Research-Plan-Implement(R.P.I.,研究—计划—实施)流程和「频繁、有意压缩上下文」方法,以避免智能体陷入上下文污染的「愚钝区」;他建议根据返工成本调整规划与验证深度。Mitchell Hashimoto 在 2026 年 2 月的采用框架中提出「构建 Harness」,解释聊天界面为何难以应对 brownfield 项目,并建议把每次观察到的错误转化为验证脚本或有针对性的 AGENTS.md 规则,同时一次监督一个高质量的后台智能体。最后,Claude Code 的创建者、Programming TypeScript 作者、前 Meta 工程负责人 Boris Cherny,曾领导 Instagram 大型 Python 到 monolith 以及 REST 到 GraphQL 迁移;他提供了实用清理策略,包括 Plan Mode、/techdebt 重复代码扫描、code-simplifier 子智能体,以及用 tagged union 类型让无效状态无法表达。

学习路线:从 Ryan Lopopolo 的经验中学什么

Lopopolo 的文章、OpenAI 于 2026 年 2 月发布的工程实践,以及他的 harness 工程仓库,将 agent-first 工程归纳为四类实践。按这个顺序学习,可以优先获得持久的结构性杠杆,而不是脆弱的提示词技巧。

1. 上下文路由:用地图取代大部头手册

OpenAI 团队最初尝试维护一份全面的 AGENTS.md 说明手册。Lopopolo 记录了导致这一做法失败的四个问题。第一,大型说明文件占用宝贵的上下文容量,挤压真正的任务和源文件。第二,把所有内容都标成关键会破坏优先级,使智能体退回局部模式匹配,而不是有目的地导航。第三,代码演进后,大部头文档会迅速过时。第四,庞大的文本块不利于通过机械检查验证新鲜度、归属、覆盖范围和交叉链接。

Lopopolo 的解决方案是渐进式披露 。团队把 AGENTS.md 缩减到约 100 行,只作为稳定目录,说明智能体的工作循环,并指向作为事实来源的版本化 docs/ 文档系统。架构地图、各领域质量评级、进行中的执行计划,以及已完成的决策记录,都与代码一起保存在仓库中。自动化测试会在代码修改导致文档过期时失败;后台「文档园艺」任务则负责修复过时文件。这与 Tan 将散文置于信任金字塔最底层的做法相呼应,同时补上了通过 CI 避免文档腐化的具体机制。

2. 机械化架构与可自我修复的 lint

Lopopolo 与 Tan 的 Dune 框架相似:Dune 禁止在产品代码中使用 useEffect,并禁止 electron-main 与 electron-renderer 目录之间的跨边界导入。Lopopolo 把严格的架构边界集中管理,同时允许智能体在边界内部自主工作。在他的 OpenAI 团队中,每个业务领域都遵循严格的单向依赖链(Types → Config → Repo → Service → Runtime → UI);认证、遥测和功能开关等横切关注点,则只能通过单一、显式的 Providers 接口接入。结构测试和自定义 lint 会机械地拒绝任何非法依赖边。

在治理遗留代码时,Lopopolo 最有杠杆效应的做法,是把 lint 和测试失败当作上下文注入 。自定义 lint 不只输出简短错误码,而是用清楚的文字说明不变量、指出错误,并引导智能体到准确的操作手册或模块,修复根因。Tan 在 Grabbot 中采用相同模式:产品代码中的注释有 99% 被禁止,因为智能体可能用注释为脆弱的变通方案辩解;与此同时,lint 错误会指导智能体消除底层架构缺陷。

3. 管理熵增与自动化垃圾回收

自主智能体会复制仓库中已有的习惯,包括不理想的做法。OpenAI 实验初期,工程师每周花 20% 的时间(每周五)手动清理智能体带来的偏移,但这种办法无法扩展。Lopopolo 的团队改用自动化垃圾回收循环,并将明确的「黄金原则」保存在仓库中,例如:共用工具应进入共享工具包,而不是各自手写;边界数据应经过类型化验证,而不是靠猜测其形状。

定时运行的后台 Codex 任务会持续依据这些原则扫描代码库、更新领域质量评级,并提交范围小、目标明确的重构 PR,供人类评审;团队自述,这类 PR 的评审与自动合并可在一分钟内完成。每天以小步偿还技术债,可以防止反模式在数周内层层累积。对正在整理旧代码的工程师而言,这种思路把清理从令人畏惧的多年大改造,转化成持续、自动化的日常维护。

4. 运行时可读性与基于产物的验证

当代码生成变得廉价,人类 QA 和代码差异评审就会成为主要瓶颈。Lopopolo 在 OpenAI Frontier 团队中取消了强制人工代码评审,转而让智能体能直接观察应用行为;OpenAI 内部估计,构建产品所需时间约为人工编码的十分之一。每个 git worktree 都可以启动隔离的应用实例,连接 CDP 获取 DOM 快照、截图并执行 UI 点击;同时还会运行临时本地可观测性栈,由 Vector 把日志、指标和 trace 汇入 Victoria Logs、Metrics 和 Traces,再通过 LogQL、PromQL 和 TraceQL 查询。智能体可以复现缺陷、验证延迟或启动时间预算(例如启动时间低于 800 毫秒),并在完成前通过由多个评审角色组成的 CI 检查(如 frontendarchitect.md、reliabilityengineer.md、appsecengineer.md)。

把 Lopopolo 与 Tan 的经验放在一起,也会显露出一个有益的测试深度张力。Tan 倾向于采用形式化与基于性质的方法:用 TLA+ 检查跨设备流程、用 Lean 证明 UI 虚拟化不变量、用 Bombadil 测试 UI 性质。Lopopolo 则提醒,脆弱、紧耦合实现细节且重复覆盖已有测试的测试,会增加维护成本。两者都认为,人类的注意力应从阅读原始代码差异,转向检查截图、录屏和 trace 等执行产物。

实践手册:为旧代码库梳理秩序

把 Tan 和 Lopopolo 的架构实践转移到老旧代码库,需要严格安排先后次序。Tan 警告说,自动化一个不可靠的内循环,只会制造高产量的低质量代码;Horthy 也指出,把尚未摸清的 brownfield 仓库整体交给不受约束的智能体,会让模型直接掉进上下文污染的「愚钝区」。下面这个四阶段顺序,将他们的护栏与面向 brownfield 的工作流、厂商记录的模式结合起来。

阶段一:摸清事实,建立安全网

修改前先审计真实依赖。 遵循 Horthy 的原则「文档会说谎,代码不会」:让智能体阅读真实仓库、清点模块并绘制实际调用路径,不要盲信过时的 wiki。创建约 100 行的 AGENTS.md 路由图。 在开头列出准确的构建、lint 和最快验证命令;再链接到 docs/ 目录中的架构说明与执行计划,而不是写一份大部头规则手册。有意、频繁地压缩上下文。 调查纠缠复杂的模块时,如果对话已经堆满过时文件读取和失败命令,让智能体把已验证的发现写入活动计划文件(docs/exec-plans/active/),然后在编辑代码前开启全新上下文。重构前先生成特征测试。 现代化遗留系统时,没有测试保护的代码难以安全重构。让智能体为准备修改的模块生成特征测试,锁定当前可观察行为;对于财务舍入、监管逻辑等未记录的业务规则,仍由人类负责把关,因为模型可能在不易察觉时改变语义。

阶段二:清除冗余,将机械迁移与语义重构分开

持续自动清除死代码。 不要提交无人能审的大型清理 PR;可以安排 knip 等工具每日提交小型 PR,删除未使用的导出、文件和依赖。批量语法变化使用确定性 AST codemod。 不要让 LLM 在数千个文件里重命名符号或替换弃用 API;模型具有非确定性,规模化操作时可能幻造导入。应使用 ast-grep、jscodeshift 或 OpenRewrite 等确定性结构化重写工具,并配合 CodeGraph 或 LSP 等语义图索引来分析影响范围。将 LLM 重构限制在边界清晰的模块中。 大规模迁移分析显示,LLM 在跨类架构重组、God class 拆分和数据库 schema 迁移等方面尤其吃力。服务边界和数据模型仍由人类负责;让智能体在隔离的 git worktree 中,对已有测试保护的模块自底向上地重构。

阶段三:设置棘轮和可自我修复的护栏

用棘轮限制遗留模式。 如果暂时无法重写数百处旧调用,就应阻止智能体继续复制它们。可以使用 baseline 这类棘轮式 CI 工具:它会统计被禁止模式或依赖的数量,并强制上限只能逐渐下降;也可以用忽略标注暂时豁免既有问题,让新增违规直接导致 CI 失败。同类错误第二次出现时,将规则确定化。 综合 Tan、Lopopolo 和 Hashimoto 的经验:第一次修正智能体犯的新错误;若第二次重犯,就把约束写进类型(例如 Cherny 用 tagged union 阻止无效状态)、明确的目录边界或自定义 lint 规则。让 lint 错误能直接指导智能体。 自定义错误信息应解释架构规则,指出获准使用的替代 API 或操作手册,让智能体在下一轮中自行修复。消除为变通方案辩解的注释。 遵循 Tan 的看法:解释临时变通的注释会保留技术债,也会教会未来的智能体坏习惯。应拒绝为变通方案找理由,改为修复根因或通过基线棘轮追踪遗留问题。

阶段四:自动化验证与持续垃圾回收

让本地验证足够快速且相互隔离。 如果测试要跑 20 分钟,智能体就可能停滞或跳过检查。应在每个任务的 git worktree 中配置筛选后的测试命令或轻量 CLI 驱动器,例如 Tan 的自定义 CLI 和功能地图,或 Hashimoto 的定向测试脚本。为智能体提供运行时可见性。 对 UI 或服务日志,在工作流中接入 CDP 浏览器检查或本地日志、指标查询,让智能体必须提交修改前后的行为证据,而不能只凭代码编译成功就宣称完成。按评审能力扩展后台清理。 可从 Hashimoto 的节奏开始:自己专注于深入架构工作,同时监督一个高确定性的后台清理智能体;也可以在每个功能分支结束时运行 Cherny 的 /techdebt 和 code-simplifier。等测试与棘轮机制足以可靠捕获回归,再逐步过渡到 Lopopolo 的定时后台 GC 任务,持续提交评审时间不到一分钟的小型重构 PR。

梳理旧代码的快速对照表

遗留代码库问题 可操作的 Harness 机制 首要参考来源
智能体忽视臃肿的 AGENTS.md,或信任过时 wiki 将 AGENTS.md 精简成约 100 行的地图;加入文档同步检查;以代码为事实依据 Ryan Lopopolo²、Dexter Horthy¹⁰
智能体在大型、纠缠的 brownfield 模块中产生幻觉 采用 Research-Plan-Implement(R.P.I.),并在新会话中有意、频繁压缩上下文 Dexter Horthy¹⁰
智能体复制旧变通方案,让「杂草」蔓延 禁止为变通方案辩解的注释;用 baseline 棘轮限制并逐步偿还债务 Lauren Tan¹、baseline¹²
大规模 API 或框架改名因 LLM 非确定性而失败 对语法迁移使用确定性 AST codemod(ast-grep、OpenRewrite);只让 LLM 处理测试覆盖的模块 Tian Pan¹¹、CodeGraph / ast-grep²⁴
死代码与重复 helper 函数不断累积 每日自动 knip PR、/techdebt 扫描、定时提交评审时间不到一分钟的后台 GC PR knip¹³、Boris Cherny⁹、Ryan Lopopolo²
智能体反复犯同类架构或 API 错误 将架构偏好编码为结构测试与自定义 lint,并让错误文案直接说明如何修复 Lauren Tan¹、Ryan Lopopolo²、Mitchell Hashimoto¹⁴
评审者被脆弱遗留模块的大型差异淹没 转向特征测试、CDP/浏览器截图和筛选后的本地验证脚本 Lauren Tan¹、Ryan Lopopolo²、Boris Cherny⁹

参考资料

All Code Is Slop (Except Mine) | AI Engineer CODE 2026,https://ai.engineer/code/2026/talks/lauren-tanHarness engineering: leveraging Codex in an agent-first world,https://openai.com/index/harness-engineering/Ryan Lopopolo - Latent Space,https://latent.space/wiki/ryan-lopopolo/AI Engineer Code Summit 2026 Recordings,https://ai.engineer/code/2026Zero Human-Written Code: Harness Engineering for Autonomous AI,https://www.zenml.io/llmops-database/zero-human-written-code-harness-engineering-for-autonomous-ai-agents-at-scaleRyan Lopopolo (OpenAI): How PMs Ship 100K Lines of Code,https://www.news.aakashg.com/p/ryan-lapopolo-podcastHarness Engineering for Coding Agents: What It Is (2026) - Agentastic,https://www.agentastic.dev/harness-engineeringHow PMs Ship 100K Lines of Code - The Growth Podcast,https://podcasts.apple.com/us/podcast/how-pms-ship-100k-lines-of-code-at-openai-with/id1763555775?i=1000769555393Boris Cherny's Claude Code Tips — How He Actually Uses It,https://howborisusesclaudecode.com/No Vibes Allowed: Solving Hard Problems in Complex Codebases,https://www.youtube.com/watch?v=rmvDxxNubIgAI-Assisted Codebase Migration at Scale: Automating the Upgrades,https://tianpan.co/blog/2026/04/17/ai-codebase-migration-agents-scalestewartjarod/baseline: Enforce architectural decisions AI coding,https://github.com/stewartjarod/baselineAutomate dead code removal using Ona and Knip - YouTube,https://www.youtube.com/watch?v=OuE0xZYnaCUMy AI Adoption Journey - Mitchell Hashimoto,https://mitchellh.com/writing/my-ai-adoption-journeyA software factory needs pressure in both directions - AI Engineer,https://ai.engineer/code/2026/talks/dexter-horthyThe Definitive Guide to Agent Harness Engineering - Medium,https://engineeratheart.medium.com/the-definitive-guide-to-agent-harness-engineering-5f5edf25fd73How the Creator of Claude Code Actually Uses It - DEV Community,https://dev.to/a_shokn/how-the-creator-of-claude-code-actually-uses-it-32dfBoris Cherny: Bio, Work & Ideas - AI Engineer,https://ai.engineer/speakers/boris-chernyBoris Cherny — Innovator Profile - Engatica,https://engatica.com/innovators/boris-cherny/lopopolo/harness-engineering: Ryan Lopopolo's anthology, field,https://github.com/lopopolo/harness-engineeringHarness Engineering — What I tried out? | by Onaopemipo Oluborode,https://medium.com/towardsdev/harness-engineering-what-i-tried-out-06cc4dfbfc93Ryan Lopopolo: Bio, Work & Ideas - AI Engineer,https://ai.engineer/speakers/ryan-lopopoloAI Agents for Legacy Code Modernization — The Developer's Week,https://amux.io/guides/legacy-code-modernization-ai-agents/codegraph-ast-grep - BrowserAct SkillHub,https://skills.browseract.com/skills/stark-ai-de-agent-skills-codegraph-ast-grepRatchets in software development (2021) - Hacker News,https://news.ycombinator.com/item?id=46814340

阅读英文版:Ordering Legacy Code for AI Agents。