目录法则一划分“红黄绿”安全区域不要让 Agent 决定修改哪里 (Zone Your Codebase)法则二只记录“代码无法表达的知识”与沉淀持久化研究产物 (Write Down What Code Cant Say)法则三警惕“迁移盲区”必须按完整单元一次性迁移 (Migrate in Complete Units)法则四重构前先用“特征化测试”锁定丑陋的现状 (Lock Behavior with Characterization Tests)法则五把重复出现的 Review 意见转化为防护网 (Turn Instructions into a Harness)法则六Agent 改变了方案尝试的成本而非评估的标准 (Try Multiple Rewrites in Parallel)法则七Agent 让团队的“模糊性”有了明确的真金白银代价 (Agents Put a Price on Ambiguity)结语从编写代码到构建验证机制的演进在存量代码库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 Cant 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 个文件使用新模式再加上若干兼容层ShimsAgent 会在搜索中看到互不兼容的前例从而做出违背新架构决策的修改。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 在重构你的核心业务模块时你是否已经准备好能够让它安全运行的工程防护网了作者道一云低代码作者想说喜欢本文请点点关注~
