给编程 Agent 加护栏的 9 种实战

AI 编程 Agent 的工程实践正在把注意力从“怎样让模型多写代码”，转向“怎样让它在真实仓库里可靠交付”。deepsense.ai 关于仓库级 Harness 模式的文章，就把讨论落在了这个更实际的问题上：模型能读文件、改代码、运行命令之后，谁来保证它找对入口、遵守架构、完成验证，并留下可追踪的结果？

截至 2026 年 11 月 3 日，对准备扩大 Agent 使用范围的开发团队来说，这比再收集一套提示词更值得投入。本文结合题述资料和公开项目文档，按真实仓库的落地顺序，将相关做法归纳为九类模式。它们是一套工程实施框架，不是某款工具刚刚发布的九项功能，也不代表已经存在统一的行业标准。

**Harness Engineering 是围绕 AI Agent 的执行过程，设计上下文、工具、约束、状态和反馈机制的工程方法。**它决定 Agent 从哪里获得信息、能执行什么操作、如何判断任务完成，以及失败后怎样恢复。

AI 编程 Agent 是能够围绕开发目标，连续执行代码检索、文件修改、命令运行和结果检查的软件代理。相比只生成一段代码，它拥有更长的行动链；相应地，一次错误也可能沿着依赖安装、数据库迁移、测试修改等步骤继续扩散。

真正有用的“护栏”，应该让正确路径容易执行，让错误路径尽早暴露。只在提示词里写一句“请保证质量”，对真实仓库几乎没有约束力。

先看全貌：九类模式分别解决什么

这九类模式覆盖了 Agent 从接到任务到交付变更的主要故障点。团队可以先补最常失败的环节，无须一次性搭建完整平台。

| 模式 | 真实仓库中的常见问题 | 最小落地方式 | 判断是否有效 | | --- | --- | --- | --- | | 1. 仓库导航与按需上下文 | 找错目录、沿用旧方案 | 简短的 AGENTS.md 加任务相关文档 | 能找到正确模块和验证入口 | | 2. 可执行的架构约束 | 代码能运行，却破坏依赖边界 | Linter、类型检查、结构测试 | 违规变更能被自动拦截 | | 3. 可复现的开发环境 | 本地成功，CI 失败 | 固定版本与统一初始化入口 | 新工作区能重复完成验证 | | 4. 面向行为的验证闭环 | 测试通过，功能仍然出错 | 回归测试加必要的端到端检查 | 能证明目标行为发生改变 | | 5. 持久化任务状态 | 会话一断，进度丢失 | 结构化交接文件 | 新会话能准确续接 | | 6. 隔离执行与并行分工 | 多个 Agent 相互覆盖 | 独立工作区和资源命名 | 并行任务不污染彼此结果 | | 7. 权限与操作边界 | 误删数据、越权执行 | 工具权限、环境隔离、操作确认 | 高风险操作在执行前被控制 | | 8. 可观测性与失败预算 | 反复重试，看不出卡点 | 执行记录、重试上限、退出条件 | 能定位失败阶段并及时停止 | | 9. 仓库维护与规则回流 | 坏模式被持续复制 | 小范围清理与失败规则沉淀 | 同类问题不再反复进入评审 |

一、让 AGENTS.md 成为地图，把上下文按任务展开

上下文工程是为模型选择、组织和更新任务所需信息的方法。这里最容易犯的错误，是把“模型能够读取更多内容”理解成“应该把整个仓库说明一次性塞进去”。

真实项目里的信息会互相冲突：旧设计文档描述一种认证流程，新代码已经换了实现，某个示例目录还保留着第三种写法。Agent 即使读完，也未必知道哪份材料拥有最终解释权。

仓库入口文件的首要任务，是告诉 Agent 去哪里找答案。AGENTS.md 项目提供了一种面向编码代理的说明文件约定；具体发现范围、目录优先级和加载行为，仍应以所用工具的实现为准。

一个可用的根目录入口，至少应该交代四件事：主要模块的位置、开发与检查入口、必须遵守的边界，以及遇到冲突时采用哪份文档。支付规则、数据库设计和前端组件规范，可以分别放进对应目录，让 Agent 在相关任务中读取。

以“修复订单重复扣款”为例，起步材料应该覆盖订单入口、幂等规则、支付适配层和相关测试。把营销页面、历史重构记录和整个组件库同时加入上下文，只会增加辨认成本。

上下文的目标是足够、准确、可定位。不存在一个对所有模型和任务都成立的“窗口使用率安全线”，也没有证据支持把“越短越好”当成通用规则。

二、把关键架构规则变成机器能检查的条件

可执行约束是能够由工具自动判定是否满足的工程规则。它可以是类型检查、静态分析、依赖关系检查，也可以是一条结构测试。

**反复出现的架构错误，应该尽量在工具层被拦住。**例如，界面层不得直接访问数据库、业务模块只能通过公开入口相互调用、生成目录不得手工编辑。这些规则如果只存在于说明文件里，每次评审都得重新解释。

Linter 是根据预设规则检查代码问题的静态分析工具。对 Agent 而言，一条好的报错还应提供足够具体的修复方向：指出违规文件、被禁止的依赖，以及推荐使用的模块入口。只有“架构不合法”五个字，往往会让它通过移动代码或增加包装层反复试探。

旧仓库适合先限制新增问题，再逐步治理历史问题。例如，先对新增文件执行依赖边界检查，或记录已有违规基线，让后续变更不能继续增加违规数量。直接用一套全新规则阻断整个遗留项目，容易把业务任务变成无边界的重构。

三、先让开发环境可复现，再讨论自动交付

可复现环境是能够依据仓库中明确的配置，重复建立依赖、工具版本和运行条件的开发环境。它是区分“代码有问题”和“机器有问题”的基础。

**Agent 的验证结果只有在环境可解释时才有价值。**同一个任务，如果本机运行的是一种运行时版本，CI 使用另一种版本，依赖安装又没有锁定，测试失败就很难归因。

仓库至少应提供明确的初始化、启动和检查入口，并说明需要哪些外部服务、测试账号或模拟数据。对于必须人工完成的准备步骤，也应给出清晰的失败提示，避免 Agent 为了让命令继续运行而自行改动项目配置。

任务开始前，还应记录与任务相关的初始状态。如果相关测试原本就失败，交付时必须区分既有故障与本次引入的问题；如果安装依赖时网络不可用，也不能把“没有运行成功”写成“验证通过”。

这一层看起来普通，却直接影响后续所有自动化。开发环境不稳定时，增加 Agent 数量只会让环境问题更频繁地进入代码修改流程。

四、围绕目标行为建立验证闭环

验证闭环是让 Agent 根据检查结果继续修复，直到满足完成条件或触发退出条件的执行流程。它的重点是验证真实需求，而非机械追求全部检查显示绿色。

**测试通过只能证明已经检查的行为符合预期。**修复一次结算金额错误，除了检查金额计算，还可能需要验证币种、舍入、折扣叠加和失败路径；修改登录页面，则可能涉及重定向、会话状态与错误提示。

回归测试是用于防止已知问题再次出现的测试。对缺陷修复，优先建立一个能在修复前暴露问题、修复后通过的案例，通常比补充大量与故障无关的断言更有用。

端到端测试是沿用户实际操作路径验证多个系统环节协作结果的测试。涉及浏览器行为时，可以用 Playwright 这样的工具操作页面，结合断言、截图和执行轨迹检查结果。但它不能替代类型检查、单元测试，也不能证明没有覆盖的路径正常。

验证本身也需要防止被错误“优化”。删除失败断言、扩大允许误差、跳过关键用例，都可能把问题藏起来。评审时应特别关注测试预期为什么发生变化，以及这一变化是否来自需求。

五、把任务进度写入文件，让新会话能够接手

持久化状态是独立于当前模型对话、能够保存并在后续执行中重新读取的任务信息。它解决长任务中最常见的断点问题：上下文压缩、会话结束或执行环境重启之后，Agent 还能知道自己做到了哪里。

**交接文件应该记录可验证的状态，而不是“已经完成大部分”这样的感受。**一份有效记录需要包含目标与非目标、当前分支和关键变更、已执行检查及其结果，以及尚未解决的问题。

“登录接口通过 8 个单元测试，浏览器回归尚未执行，因为测试服务启动失败”，比“登录功能基本完成”有用得多。前者让下一个执行者知道可以依赖什么，还需要补什么。

状态文件也应该避免与代码形成第二套相互矛盾的事实。每次恢复任务，应先核对实际分支、工作区差异和已有提交，再决定是否沿用交接记录。涉及内部地址、访问凭据或用户数据时，记录中只保留必要且允许保存的信息。

六、并行执行必须同时隔离文件和运行资源

工作区隔离是为不同任务提供独立文件状态和执行资源的方式。它的直接价值，是避免多个 Agent 在同一处修改代码、安装依赖或启动服务时相互干扰。

Git worktree 适合隔离分支文件，但不会自动隔离整个运行环境。Git 官方仓库的 worktree 文档说明了多工作树机制；数据库、端口、缓存和外部测试账号，则需要额外安排。

两个 Agent 即使在不同目录工作，只要共用一套可写测试数据库，其中一个清理数据，另一个的测试仍可能失败。因此，并行任务应根据需要分配不同数据库或 schema、独立临时目录和不会冲突的服务端口。

分工还需要清楚的文件与决策边界。一个 Agent 修改接口约定，另一个同步实现前端，如果双方依据不同版本工作，增加并行度反而会放大返工。依赖紧密的任务应先确定契约，再展开实现。

并行是否值得，应该看最终交付耗时和返工量，而不是同时运行了多少个代理。

七、把权限边界放进执行系统

最小权限是只授予完成当前任务所必需的访问与操作能力。对编程 Agent，这包括文件、命令、网络、凭据和外部系统的使用范围。

**“不要操作生产环境”应该有实际的权限配置支撑。**本地编码通常不需要生产数据库的写入能力，运行测试也不应默认获得发布权限。能够在凭据与网络层限制的能力，不宜完全依赖模型自觉。

任务还需要区分内容和指令。提示注入是通过文档、网页、日志等输入内容，诱导 Agent 偏离原定任务或权限边界的攻击方式。仓库里的第三方材料、测试样例和错误输出，都可能包含看起来像操作命令的文本；它们首先是待分析的数据，不能因此获得执行授权。

权限控制应尽量集中在真正有后果的步骤。常规读取和可恢复的本地修改可以保持顺畅；发布、删除重要资源、修改外部系统等操作，则应通过工具能力、环境隔离或必要的人工确认建立边界。

八、为失败留下证据，也为重试设置上限

可观测性是通过日志、执行事件和指标判断系统运行状态的能力。应用到编程 Agent，就是能解释它做过什么、为什么卡住，以及下一次尝试与上一次有什么不同。

**没有退出条件的自动修复，容易把一个小问题变成一串无关改动。**例如，依赖服务没有启动，Agent 却不断修改客户端超时、重试次数和错误处理，最后让最初的环境故障混进了业务补丁。

记录至少应覆盖关键命令、退出状态、失败摘要和变更范围。日志要足以支持复盘，但应过滤敏感信息，避免把完整环境变量或凭据写进持久记录。

失败预算是对执行时间、尝试次数或资源消耗设置的上限。团队可以先采用一套明确的试运行规则，例如：同一失败在没有新增证据的情况下连续出现 3 次就暂停，并输出失败摘要。这个数字是可调整的实施示例，不是业界统一标准。

暂停后的交接应说明已经尝试什么、当前证据支持什么判断、下一步需要什么条件。这样的停止比继续猜测更有助于完成任务。

九、让失败案例回到规则，让清理保持小范围

规则回流是将任务中的真实失败，转化为后续可复用的检查、说明或工具改进的过程。它让 Harness 能随仓库演进，而不是一次搭好后长期失效。

**同一种错误反复出现在评审中，通常意味着反馈还没有进入系统。**Agent 总是使用已经废弃的接口，就检查入口文档和示例是否仍在推荐它；总是跨越模块边界，就补依赖检查；总是遗漏某条用户路径，就评估是否需要加入回归用例。

仓库维护也应该控制变更范围。移除未使用导入、修复失效链接、更新错误命令，通常容易审查；仅凭文件超过某个行数就自动拆分，则可能改变状态管理、事务边界或模块职责。

“超过 300 行”可以作为调查线索，不能单独证明需要重构。清理任务最好一次处理一种问题，并保留清晰的验证与回退路径，避免顺手修改无关业务逻辑。

Awesome Agent Harness 中文清单可以用于寻找相关工具和项目入口，但工具数量不等于工程成熟度。引入任何组件前，都应先确认它解决的是本仓库已经出现的问题。

怎样开始：用小批量真实任务验证护栏价值

最小可用 Harness 应该先打通“找到规则、完成修改、运行检查、留下证据”这条路径。对已有仓库，第一轮可以只做五件事：建立简短入口说明，统一验证命令，记录初始测试状态，提供独立工作区，再要求每次任务输出可核查的交接结果。

落地效果需要通过真实任务衡量。团队可以先选择 10—20 个规模接近、边界清楚的任务作为试运行样本，记录交付时间、人工返工轮次、测试遗漏和无关文件改动；这个样本规模只是启动建议，不能据此宣称具有统计显著性的性能提升。

收益判断还应包含维护成本。如果某项护栏能拦住真实错误，却让所有任务都多等待很长时间，就需要调整检查时机、范围或实现方式。检查越多并不自动意味着交付越可靠。

对当前的 AI 编程实践，值得优先投入的是那些能给出明确失败信号的机制：可运行的环境、可执行的边界、能够复现问题的测试，以及可恢复的任务状态。它们无法让模型永远正确，但能让错误更早暴露，也让开发者更容易判断一份变更是否值得合并。

参考来源

• AGENTS.md 官方项目：面向编码代理的仓库说明文件约定，可用于设计导航与开发指令入口。
• OpenAI Codex 官方仓库：了解编码代理工具及其执行环境相关资料；具体行为应以所用版本文档为准。
• Git worktree 官方文档：多工作树的使用方式与边界，支持理解任务文件隔离。
• Playwright 官方仓库：浏览器自动化测试工具，适用于需要验证实际页面行为的任务。
• Awesome Agent Harness 中文清单：汇总 Harness 相关项目，可作为进一步调研工具的入口。
• Harness Engineering 深度解析：题述补充资料之一，讨论上下文、自动检查、持久状态及遗留仓库改造问题；其中经验性判断需结合具体项目验证。