在存量代码库（Brownfield Codebases）中开发是一场对工程纪律的严峻考验：老旧系统往往早已无法仅凭代码树完全反映其真实运行行为。大量隐性业务知识、临时补丁、跨团队依赖与历史约定游离于代码之外。
将 AI Agent 在无监督状态下直接扔进这类老旧代码库，极易引发架构灾难——它可能会产出表面上能“运行”的代码，却在无意中破坏了系统原有的架构原则，并留下一堆极其脆弱的测试。
正如 AI 工程专家 Addy Osmani 所言：存量代码库中的 Agentic Engineering（智能体工程化），其核心宗旨不在于让 AI 随意重写一切，而在于将隐藏的约束条件显性化，并让低成本的代码变更变得安全可信。
为了帮助工程团队在现代 AI 开发范式下规避技术债务，本文梳理了 7 个最违背直觉却最具影响力的核心法则。
法则一：划分“红黄绿”安全区域，不要让 Agent 决定修改哪里 (Zone Your Codebase)
面对历史悠久的代码库，首要任务是明确哪些代码可以动，哪些绝对不能盲目触碰。工程团队应当建立“安全区域（Zones）”机制：
-
绿色区域（Green Zone）： 模块隔离性好、拥有高质量测试且符合现代化规范。Agent 可以在此区域内自主闭环并快速迭代。
-
黄色区域（Yellow Zone）： 代码质量参差不齐。Agent 必须在编写并锁定“特征化测试”后方可修改。
-
红色区域（Red Zone）： 涉及身份验证（Auth）、计费（Billing）、权限（Permissions）或支付等极度敏感的业务。该区域仅限人类工程师主导，禁止 Agent 进行无监督的重构。
划定区域的关键在于建立明确的操作规程：必须由人类来绘制地图，而不是让 Agent 自由选择。 如果放任 Agent 自主挑选，它通常会直接奔向最危险的文件，因为最危险的文件往往有着最吸引人的名称。
同时，区域的晋级必须遵循严格的区域流转规则：区域级别的提升只能靠“赚取”——只有当黄色区域补充了完备的特征化测试，且模块 Owner 亲自审查并批准了 Agent 的首次变更后，该黄色区域才能晋级为绿色区域。
区域划分直接决定了 Agent 的操作动词：绿色区域对应“自主闭环迭代”，黄色区域对应“测试先行”，而红色区域则意味着“全程人类结对（Human Pairing）”或“禁止触碰”。
"A person draws the map, not the agent; left to choose, the agent starts in the scariest file, because the scariest file has the most interesting names."
法则二：只记录“代码无法表达的知识”与沉淀持久化研究产物 (Write Down What Code Can't Say)
许多团队在引入 Agent 时，习惯于编写大量通用 Markdown 文档塞满上下文窗口。然而， LLM 本身非常擅长从代码中推断系统的结构与拓扑关系，盲目堆砌代码本身的描述只会白白浪费宝贵的上下文资源。
Agent 真正需要的，是代码本身无法表达的隐性知识：
-
特定业务或团队的微妙规则（Business Nuances）。
-
解释“系统为何如此设计”的权衡过程（Trade-offs）。
-
未被静态分析工具或 Lint 显式强制的规范指南。
-
复杂/反直觉实现背后的历史上下文与外部约束。
此外，为了防止 Agent 在每次会话中重复进行高昂的代码考古，团队必须要求 Agent 在探索阶段输出持久化研究产物（Durable Research Artifact）。在处理黄色或红色区域时，应先执行一个只读的探索 Pass，生成一份简短的“系统理解备忘录”——明确入口点、所有者、调用方、现有抽象、测试、生产信号及未决问题，并附带具体的文件或 Dashboard 引用。
在完成研究后，清空 上下文窗口 ，基于这份持久化产物开启全新的 Plan 与 Implementation 会话。管理上下文窗口的硬原则应当极其精炼：只写下代码无法表达的知识，其余一概不写。
法则三：警惕“迁移盲区”，必须按完整单元一次性迁移 (Migrate in Complete Units)
半途而废的架构迁移对 Agent 具有极强的误导性。如果 项目 中 40 个文件使用老旧模式，12 个文件使用新模式，再加上若干兼容层（Shims），Agent 会在搜索中看到互不兼容的前例，从而做出违背新架构决策的修改。
SWE Refactor Bench 的权威测试数据验证了这一危险：在 520 次 Agent 运行实验中，仅有 28 次成功通过了迁移审计、行为测试与独立验证。导致大规模失败的主要原因正是“迁移盲区（Migration Blindness）”——即新路径表面上运行正常，底层代码却依然在暗中调用老旧依赖。
团队必须坚持“端到端完成单一路由/模块”的策略，包括彻底清理和删除旧路径代码。如果把清理旧代码当作“以后的 Ticket”，那么这个迁移单元就没有真正完成。
"A migration is complete when the new path works and the old dependency is demonstrably gone."
法则四：重构前，先用“特征化测试”锁定丑陋的现状 (Lock Behavior with Characterization Tests)
在旧系统中，许多看起来“丑陋”的代码行为，实际上是业务长期依赖的既成事实。特征化测试（Characterization Tests）的目的是用自动化测试记录系统当前的实际行为（包括那些奇特的边缘 Case），防止 Agent 在重构时将这些关键逻辑作为“Bug”顺手修复。
在实施时必须遵守一项硬性规定：负责修改代码的 Agent Session，绝不能是该测试套件的唯一作者。 如果让同一个 Agent 会话既写测试又改代码，你只会得到一个为你刚刚发明的实现打绿灯的伪测试套件。必须先由人类或在独立会话中锁定行为，再交给 Agent 实施重构。
对于缺少单体单元测试的大型生产环境，可以参考 Netflix 在 GraphQL 切换中的策略：通过重放（Replay）和影子流量（Shadow Traffic）对比新旧路径的 Payload 响应，只有在完全一致时才予以推进。
法则五：把重复出现的 Review 意见转化为防护网 (Turn Instructions into a Harness)
在 Code Review 过程中，如果人类开发者只是悄悄修复了 Agent 提交的 Diff，下一次会话 Agent 依然会犯同样的错误。
团队应当将被动自然语言文档升级为硬性的防护网（Harness）：
-
将反复出现的自然语言修改意见，转化为 Lint 规则、Git 钩子（Hooks）、类型系统（Types）、自动化测试、自定义技能（Skills）或专属插件。
-
自然语言仅用于保留无法通过机械化工具强制约束的业务边界。
防护网是围绕 Agent 构建的工程运行环境。随着时间推移，这套 Harness 将成为团队决定“不再支付第二次成本”的失败经验沉淀。
"Every repeated correction is a missing piece of the harness... Over time the harness becomes a record of failures the team has decided not to pay for twice."
法则六：Agent 改变了方案尝试的成本，而非评估的标准 (Try Multiple Rewrites in Parallel)
生成式 Token 成本的骤降改变了架构决策的经济学。如今，技术 Leader 可以让 Agent 并行尝试多种不同的重构路径（例如不同的语言或框架），在真实运行并对比单元测试与性能 Profiling 后，再做出最终决策。
需要明确区分多路径并行探索与确定性机械迁移的不同场景：
-
多路径并行探索： Shopify 团队在短短 12 周内，利用 Agent 屏级检查点（Screen-sized Checkpoints），成功将 Shop App 消费端从 React Native 迁移至 Swift 和 Kotlin 原生语言。Agent 让同时尝试多种重构路径成为可能。
-
确定性机械迁移：
-
Bun 在将 53.5 万行代码从 Zig 移植到 Rust（运行了约 50 个工作流）前，投入数小时编写了映射指南，将 Zig 惯用法精准映射至 Rust；并在执行中设立了每个生成单元由两个对抗性审查员（Adversarial Reviewers）审核以及预先存在的全量测试套件作为合并门控。
-
Asana 仅花费了约 12,000 美元的 Token 与基础设施成本，就在两周内清空了积压多年的 Enzyme 迁移任务。但必须注意 Addy Osmani 给出的关键澄清：这 12,000 美元仅仅是厂商报告的生成Token账单，绝不能替代原本五年预算的人力成本估计，也不能直接等同于严谨对照下的 ROI 节省额度。 其可复用的本质依然是窄范围的机械迁移与强测试门控。
-
这一改变的核心在于：Agent 降低的是“尝试各种实现方案”的成本，但评估与选择方案的工程标准（验证证据）依然牢牢掌握在人类手中。
警告：谨慎使用并行化！ 盲目并行化 Agent 会成倍放大团队现有的审核瓶颈。自动化验证可以轻松处理 5 个已检查的变更；但如果让一名资深工程师去逐行阅读数十个并发 PR，只会导致注意力碎片化，最终演变为极度危险的形式主义审批（Ceremonial Approval）。
法则七：Agent 让团队的“模糊性”有了明确的真金白银代价 (Agents Put a Price on Ambiguity)
过去，团队中未书面化的隐性知识（Tribal Knowledge）和模糊约定，其成本隐匿在新人 Onboarding、代码审查和线上故障响应中。而在 Agent 深度参与的开发模式下，这些模糊性直接转化为重复的 Review 循环、暴涨的 Token 账单与逃逸缺陷（Escaped Defects）。
为了量化重构与 Agentic 工程的效果，团队应当建立清晰的指标跟踪体系：
-
过程与质量指标 (Process & Quality Metrics)： 交付前置时间（Lead time）、Review 分钟数、人工干预次数、逃逸缺陷数（Escaped defects）、回滚率（Rollbacks）、Oracle 不匹配数。
-
迁移进度指标 (Migration Progress Metrics)： 剩余旧导入数量（Remaining old imports）、新路径承载的真实流量比例、已经被彻底移除的历史依赖项数量。
这种财务与效率维度的透明度，为技术 Leader 提供了有史以来最强有力的依据，去推动那些拖延已久的技术债治理项目。
结语：从编写代码到构建验证机制的演进
在存量代码库中，单纯盲目地并行化 Agent 运行，只会加速人类 Code Review 的瓶颈。Agent 并没有消除复杂业务部门与 Legacy 依赖带来的难题，它只是降低了尝试变更的门槛。
未来软件工程师的核心职责正在发生转移：从直接编写每一行代码，演变为设计防护网（Harness）、划定安全边界并构建强大的验证引擎（如合成用户旅程 Synthetic User Journeys、所有权记录与回归测试套件）。
当 AI Agent 成为团队中的永久成员，下一次 Agent 在重构你的核心业务模块时，你是否已经准备好能够让它安全运行的工程防护网了？
作者：道一云低代码
作者想说：喜欢本文请点点关注~
