棕地系统中的隐形约束与测试信心

在长期存在的“棕地”（Brownfield）代码库中进行智能体工程，核心在于使隐形约束显性化并确保变更的可信度。这类系统的仓库已无法完整描述实际行为，因为制度知识、临时补丁和遗留服务往往存在于代码树之外。作者指出，必须先在编写新代码前了解这些约束，并证明变更未破坏它们。盲目将智能体投入旧系统可能导致设计错误且脆弱的测试。即便在AI介入前，现代化改造也需依赖严格的测试层和用户旅程验证。如今，随着对变更安全性、可观测性和可恢复性的重视增加，若引入自主工作的软件工厂模式而缺乏足够的审慎思维，极易导致技术债务累积。因此，优化目标应定为以低成本安全地执行变更。在深入具体模式前，需确立一个前提：代码应是唯一真理来源，额外添加的信息仅用于补充那些无法从代码中轻易推断的内容。

区域划分：将操作程序化而非隐喻化

进入旧代码库时，首要任务是识别不应触碰的代码区域。作者建议将系统划分为不同“区域”以指导智能体的行为：绿色区域代表测试覆盖良好、使用现代约定且隔离性强的代码，智能体可在此进行紧密循环的自主工作；黄色区域质量参差不齐，需在编写特征测试（characterization tests）后由智能体修改；红色区域涉及认证、计费或权限等敏感逻辑，理解者寥寥，严禁无监督重写。这一划分并非比喻，而是基于三条硬性规则：人类绘制地图而非智能体；若由智能体自主选择起点，它会因文件名有趣而选择最危险的模块；区域升级需“ earned ”——黄色变为绿色需具备特征测试且所有者审查通过。这些规则设定了动词：绿色区域允许紧密循环，黄色区域要求测试先行，红色区域则需人类每一步结对编程或停止工作。

记录代码无法表达的知识与持久化研究

智能体的自主性应遵循爆炸半径、可观测性和可恢复性原则，而非模型自信度。虽然智能体能从代码中推断大量系统地图信息（如调用链、结构），但应提供那些无法从代码中明显看出内容。这包括业务特定细微差别、解释系统结构的设计权衡、未被静态分析工具强制执行的指南，以及反直觉实现背后的历史背景。“写下代码无法说出的内容，除此之外什么都不写”。对于黄色和红色区域的工作，建议进行独立的只读研究阶段，产出简短的理解备忘录（comprehension memo）。该文档需包含入口点、所有者、调用者、现有抽象层、测试情况、生产信号及开放性问题，且每项声明必须引用具体文件、Issue或仪表盘。默认循环往往浪费研究过程——智能体完成任务后，其探索成果随会话结束而丢失。“如果智能体的探索没有产生持久性产物，下一个智能体将再次为同样的考古工作买单”。因此，研究后应使用干净上下文开始规划，由人类选择路径，若发现地图错误则停止实现。

指令即测试夹具：纠正中的模式沉淀

在智能体工程实践中，每一次重复的纠正常常暗示着测试夹具（harness）中缺失的部分。当智能体反复犯同类错误时，不应仅视为单次失误，而应将其转化为系统性的约束或文档。这要求建立一种机制，将反复出现的纠正措施固化为可复用的指令或测试用例。通过这种方式，智能体的行为逐渐被约束在更安全的边界内。同时，审查过程应从验收标准反向工作，确保测试证明的是实现而非需求。“每一次重复的纠正都是夹具中缺失的一块”。这种思维转变有助于将智能体的探索成果转化为团队资产，避免重复劳动和技术债务的无限累积。通过这种方式，棕地系统的现代化不再是零散的修补，而是基于持久化知识和严格区域控制的系统性工程。

组件职责与容错机制的精确界定

在 Brownfield（遗留系统）中引入 Agentic Engineering，首要任务是精确划分各组件的职责边界。指令（Instructions）用于记录仓库中的非典型事实，技能包（Skills）封装可复用的程序逻辑如检查爆炸半径或验证模式变更，而插件（Plugins）则提供对所有权目录、事故档案或仪表盘的受控访问。这些组件共同构建了一个围绕 Agent 的工作环境，即“Harness”，它包含上下文、工具、权限、测试、日志和恢复机制。工厂（Factory）负责调度多个可靠的循环，保持持久状态，并将新颖案例交还人类处理。

The practical test is what happens when the agent gets something wrong.

实践中的关键测试在于 Agent 犯错时的反应。如果悄悄修复差异，下一次会话可能会重复该错误；当相同的审查评论再次出现时，应将其转化为 lint 规则、钩子、类型检查或技能。随着时间推移，Harness 成为团队决定不再为同一错误支付两次成本的失败记录。拒绝规则、作用域凭证或 CI 检查无需记忆，它们构成了机械执行的约束。

从零风险工作开始锁定行为

引入 Agent 进入现有代码库时，应遵循“先锁定今日行为，再允许改进”的原则。这类似于其他现代化努力，但切忌直接重写单体应用（如改为 Rust），而应从解释现有工作原理开始。核心步骤是生成特征化测试（Characterization tests）以锁定当前行为，包括那些丑陋的部分。因为旧系统的某些糟糕行为正是业务运行的基础，Agent 可能会在测试通过的情况下“修复”掉这些关键逻辑。

Characterization tests are automated tests used to document a system’s actual current behavior so you can safely refactor or change legacy code

Netflix 在 GraphQL 切换中采用了类似的大规模生产级思路：回放和影子流量对比新旧路径，仅在负载匹配时才进行推广。对于没有真实单元测试的主页级表面，不要猜测，而是运行两者并比较。当 Agent 使测试通过时，不要让同一会话成为唯一的作者。必须先由人或单独阶段锁定行为，再让 Agent 工作，否则会得到一个编码了刚刚发明实现的绿色测试套件。随后才能进行机械转换，如清理死代码和未使用的导出。

复杂系统中的用户测试与风险管控

在大型多部门代码库中，生产流量是唯一真正理解系统复杂性的实体。作者回忆在 AOL 工作时，因 JavaScript 专家短缺，不得不在休假期间修复完全崩溃的主页。由于涉及数十个部门、不同组件和 A/B 测试，且缺乏全面的单元测试覆盖，最终必须通过用户测试（User-testing）来确保没有破坏其他功能。这揭示了 Agent 时代的现实：Agent 并未消除多部门协作的复杂性，只是降低了尝试变更的成本。只要没有建立生产流量的替身（Stand-in），用户测试依然是必要的闸门。

A surface that only production traffic really understands is a red zone by definition, and until you’ve built a stand-in for that traffic, the user-testing I did on my day off is still the gate.

完整迁移单元与“盲目性”陷阱

迁移必须以完整的单位进行，即新路径工作且旧依赖被证明已移除。半途而废的迁移会让 Agent 困惑，因为搜索会返回旧方法和新方法的混合体，导致矛盾的先例。SWE Refactor Bench 的基准测试揭示了迁移中的“盲目性”问题：在 520 次 Agent 运行中，仅有 28 次通过了迁移审计、行为测试和独立验证。如果替换代码仍调用遗留实现，即使测试保持绿色，迁移也不完整。

If a codemod can make the routine change, use the agent to help write and check it. Give agents the exception queue.

Stripe 的迁移案例表明， durable artifact（持久工件）应是迁移机器本身而非 Agent。Anthropic 在广泛运行前，会在可丢弃的微型迁移上压力测试其规则书。这些案例强调，原子性变更随代码库规模增长而缩小是普遍规律。

大规模迁移的结构化启示与成本真相

从 Bun（Zig-to-Rust）和 Asana 的案例中，可提取出适用于公司的 Agent 周围结构。Bun 在 11 天内运行了约 50 个工作流，处理 535,000 行代码，关键在于迁移前投入数小时将 Zig 习语映射到 Rust。Asana 在 两周 内清除了多年的 Enzyme 积压，成本约 $12,000（模型和基础设施）。然而，这仅是代币账单，并非受控的节省研究，不能替代五年的 staffing estimate（人员配置估算）。可转移的经验是：狭窄的机械迁移、现有的测试套件以及人类对每项变更的审查。Agent 改变了尝试多种可行实现的价格，但未改变选择一种实现所需的证据要求。

What transfers between companies is the structure around the agents.

代理驱动的重构与多方案验证

今年，越来越多的成熟企业开始利用智能体（Agents）执行大规模代码重写。许多 CTO 允许团队让代理尝试多种不同语言或框架的重写方案，因为现在以更低成本进行可行性评估和权衡变得切实可行。代理使得并行探索技术栈成为可能，从而改变了传统的决策模式。例如，Shopify 在十二周内使用一个小团队和代理门控的屏幕级检查点，将 Shop 消费者应用从 React Native 重构为原生 Swift 和 Kotlin。相比之下，规模更大的商户应用仍面临“棕地”难题：数百个屏幕、深度的平台集成以及更长的时间周期。

"I’ve talked to CTOs who are allowing teams to have agents try multiple rewrites in different languages or frameworks because its now feasible to do so more cheaply and evaluate the trade-offs."

如今，只要有足够的 Token 预算，代理就可以尝试跨越不同技术栈或语言完成迁移。团队不再需要让一个小组孤注一掷地选择单一方案，而是可以让代理实现多个竞争选项。所有版本均可通过单元测试验证、性能剖析，从而做出更优决策。这种多方案并行实现与评估的方式，在某些情况下比传统单一选择便宜得多，为团队带来了完全不同的游戏局面。除了框架级迁移和 Rust 重写案例外，许多原本需要更长时间完成的迁移工作，现在借助代理得以加速推进。

并行化的陷阱与审查策略

生成的代码增多并不意味着人类审查的减少，反而应提高人类审查的选择性。在思考循环、目标或并行化之前，必须先确保棕地项目具备成功的基础。软件工厂可以同时运行许多更改，但这应在单个单元拥有可靠的判断标准、恢复路径和可吸收的审查格式之后才进行。并行化会放大现有的瓶颈：自动化验证可能处理五个已检查的更改，但一位高级开发人员阅读每一行代码会导致队列积压、注意力碎片化，最终流于形式化的批准。

"Parallelism multiplies the bottleneck you already have. Automated verification can handle five checked changes. One senior reading every line gets a queue, fragmented attention, and eventually ceremonial approval."

我倾向于让自动化审查首先展示意图、变更的不变量（invariants）、测试结果、奇偶校验不匹配以及回滚路径，完整的差异文件仍可供查阅。人类注意力应首先集中在影响范围最大和验证最弱的环节。工作树（Worktrees）隔离的是更改而非行为，它们可能共享 Git 元数据、凭据和本地服务。受信任的工作可以接受这种权衡，但未由人工监督的代理处理不受信内容时，需要更强的沙箱和受限凭据。

量化模糊性的成本与遗产管理

生成的代码行数并不能反映代码库是否真正改善。应追踪前置时间、审查分钟数、人类干预次数、逃逸缺陷、回滚率以及遗留的奇偶校验不匹配和抑制项。代理为模糊性标上了可见的价格，使原本隐性的技术债务变得可计算。部落式的惯例变成了反复出现的审查评论。这种成本一直存在，体现在入职培训、审查和事故恢复中；代理使其更具可量化性，从而为团队早已认可其价值的维护工作提供了更有力的论证。

"Agents put a visible price on ambiguity. Tribal conventions become recurring review comments."

对于迁移工作，需追踪剩余的旧导入、由新路径服务的流量比例以及已移除的遗留依赖。如果测试套件全绿但所有流量仍走旧路径，这只是无用功。代理在类似主页的模块上工作时，应留下合成用户旅程、所有权记录和回归测试，而不仅仅是修复。下一位工程师和代理继承的内容同样重要。留下的不仅是代码的修补，更是可追溯的责任与测试保障，这决定了后续开发的效率与维护成本。

结论

棕地智能体工程的核心在于通过区域划分、持久化研究和测试夹具固化，将隐形约束显性化并锁定行为。其优势在于降低并行探索技术栈的成本及量化模糊性的债务，但短板明显：SWE Refactor Bench数据显示迁移成功率极低（520次中仅28次通过），且并行化会放大人类审查瓶颈。适用条件严格：需以完整迁移单元进行，依赖生产流量或用户测试作为最终验证闸门。智能体未改变选择实现所需的证据要求，仅改变了尝试成本；成功依赖于人类对敏感区域的严格控制和将纠正措施转化为机械约束的机制，而非单纯依赖模型自信度。