编程 Agent 工程实践：从上下文到可靠交付
编程 Agent 的价值不在于代替工程判断，而在于把清晰意图、恰当上下文和快速反馈组成可重复的工程闭环；人负责目标、边界与风险，Agent 负责在可验证的循环中推进实现。
TL;DR：用好编程 Agent 的关键不是赋予它更大自主权，而是把软件工程中原本依赖资深工程师脑内完成的工作显式化：用任务契约定义意图，用分层上下文提供证据，用自动化反馈校验结果，用人类监督处理高影响判断。模型越强，越应投资于测试、架构边界、交付门禁和可恢复工作流；这些不是 Agent 的替代品，而是让 Agent 可靠放大团队能力的基础设施。
关联笔记：AI Coding 工程实践：成为「循环之上」的工程师 · 软件工程循环中的人类与 Agent【译】 · Context Engineering：为 Agent 构建高信噪比任务上下文 · ../01 SDD/03 AI 辅助编程实践指南——从工具使用到 Agent 协作
目录
| 章节 | 说明 |
|---|---|
| 结论与论证结构 | 先给出本文的核心主张与四层论据 |
| 方法论谱系：Agent 工程不是从零开始 | 将 Agile、TDD、CI/CD、SRE 与安全工程映射到 Agent |
| 论点一：Agent 是放大器，不是责任转移器 | 不把局部速度误当成交付能力 |
| 论点二：先选任务，再给自主权 | 用风险和可验证性决定协作方式 |
| 论点三：反馈系统比限制系统更可扩展 | 用传感器帮 Agent 发现和修复问题 |
| 论点四：人应在循环之上 | 人管理意图、风险和学习闭环 |
| 一轮可靠的 Agent 工作流 | 从任务契约到交接的操作闭环 |
| 上下文、规则与能力如何分工 | AGENTS.md、Skill、Hook、MCP 的边界 |
| 多 Agent：何时值得并行 | 先隔离任务，再增加协作复杂度 |
| 团队落地路线 | 从个人试用走向可度量的工程实践 |
| 如何衡量是否真的变好 | 用交付质量而非代码产量衡量收益 |
| 反模式与检查清单 | 避免把 Agent 当作魔法 |
结论与论证结构
本文的中心结论只有一句：编程 Agent 的上限由团队的工程闭环决定，而不是由模型是否能一次性写出更多代码决定。
这个结论建立在四个递进论点上：
- Agent 是放大器，不是责任转移器：它会同时放大高质量工程能力和既有混乱；最终的软件责任仍在人与团队。
- 自主权应随风险和可验证性变化：把权限授予可以回滚、可独立验证的工作，而不是根据对模型能力的印象一次性放开。
- 反馈系统比限制系统更能随能力增长：围栏保护高风险边界，测试、类型、lint 和架构检查则持续为更强的 Agent 提供有效反馈。
- 人的位置是“在循环之上”：人不应陷入逐 token、逐行的微观操控，而应管理目标、约束、验收、例外和反馈资产。
后续章节先分别论证这四点，再把它们落到一次任务、工具分工、多 Agent 与团队治理中。
方法论谱系：Agent 工程不是从零开始
讨论 Agent 时，容易把问题表述为“模型是否足够聪明”。但软件工程过去数十年真正反复解决的问题是：如何让一个高吞吐、会出错的执行系统，在复杂环境中持续产生可接受的结果。 这个执行系统过去是人和脚本，今天多了能自主规划和调用工具的 Agent。对象变了，核心约束没有变：需求会变化、局部正确不等于系统正确、错误检测总有延迟、生产影响需要控制。
因此，编程 Agent 不应另起一套脱离工程实践的“AI 方法论”。更准确的说法是：它把既有实践中隐含在资深工程师经验里的部分——任务澄清、代码导航、验证、交接、回滚和复盘——变成了需要显式交给机器和流程的接口。
一张映射表：旧问题如何变成 Agent 问题
| 方法论 | 原来要约束的对象 | 核心机制 | Agent 时代的等价做法 | 不能误解为 |
|---|---|---|---|---|
| Agile / Lean | 需求变化与大批量返工 | 小批量、短反馈、持续学习 | 任务拆成能独立验收的切片；每轮都保留可审阅产物 | “把需求切碎后让 Agent 同时乱改” |
| TDD / BDD | 实现偏离预期行为 | 先定义可执行行为，再实现 | 先给验收示例/测试，再让 Agent 实现与修复 | “有测试就不需要理解需求” |
| CI/CD | 集成不确定性与人工交付 | 可复现构建、自动测试、门禁、版本化 | Agent 的改动必须经过同一套 build/test/scan；结果可追溯 | “所有检查绿了就可无审查发布” |
| SRE | 生产风险与不可预测输入 | SLO、监控、渐进发布、回滚、复盘 | 让 Agent 在隔离环境、小影响半径、可回滚路径中运行 | “发生错误后再让 Agent 自己补救” |
| DevSecOps / 零信任 | 权限滥用、供应链与审计 | 最小权限、策略即代码、审批与证据 | 按读/写/执行/生产权限分级；敏感操作保留人工控制 | “模型足够聪明后就可以给管理员权限” |
| 架构治理 | 局部优化破坏长期演化 | 模块边界、契约、架构测试、ADR | 让 Agent 读取边界并由规则/测试检测越界 | “在规则文件写一句遵守架构即可” |
表中的共同结构是一个控制回路：先设定目标与边界（前馈），再执行，再从外部世界取得反馈，最后依据反馈调整下一步。 这正是 Harness Engineering 所说的 Guides 与 Sensors：前者包括任务契约、规则、示例和权限；后者包括编译器、测试、lint、架构检查、CI 和生产监控。
这里有一个重要推论：提示词只是前馈控制的一小部分。 如果系统只靠“请小心、请遵守规范”来避免错误，就等同于只在发布前提醒工程师“不要出事故”。成熟系统会把可以判定的要求编码为测试、策略和门禁，并让错误尽量在代价最低的阶段出现。
Agile / Lean：为什么 Agent 更需要小批量
Lean 的关键不是“快”，而是缩短“做出假设 → 获得反馈 → 修正假设”的周期。Agent 很擅长快速产出，因此特别容易制造一种错觉：一次让它处理更大任务似乎更有效率。实际上，任务越大，隐含假设越多，错误越晚暴露，修复成本也会非线性上升。
将其转成 Agent 实践，应采用垂直切片而不是按技术层堆任务：一个切片从一个用户可感知行为出发，包含必要的实现和测试，有独立验收结论。例如，与其给 Agent “完成整个退款模块重构”，不如先给“在不改变外部接口的前提下，令重复的取消请求只触发一次退款，并补足并发场景测试”。
| 大而模糊的委派 | 小而可学习的委派 |
|---|---|
| “重构订单模块，提升可维护性” | “识别重复退款路径；提出两种最小变更方案及其回滚方式；批准后只实现选定方案” |
| “把服务迁到新框架” | “迁移一个非关键端点，保留旧路径；比较延迟、错误率与部署回滚结果” |
| “修复所有 CI 问题” | “归类失败为环境、确定性测试、偶发测试；先修复一类并证明失败率下降” |
TDD / BDD：测试不是 Agent 的附属品，而是共同语言
TDD 的深层价值不只是提高覆盖率，而是把模糊意图转换成机器可执行的反馈。对 Agent 而言，测试同时扮演三种角色：
- 需求锚点：告诉它“正确”应表现为何种可观察行为；
- 搜索边界：失败测试和相邻测试往往比整库搜索更快指向相关代码；
- 停止条件：避免 Agent 在自认为完成后继续进行无关改动。
但测试也不是绝对真相。测试可能只覆盖当前实现、缺少并发/权限/性能场景，甚至把既有缺陷固化为“预期”。所以 TDD 在 Agent 时代的正确姿势是：先用测试收紧已知行为，再由人审查测试没有表达的领域取舍与非功能约束。 当 Agent 能轻易生成大量测试时，测试的价值更取决于场景选择和断言质量，而非数量。
CI/CD：把“能写”接入“能交付”
CI/CD 的原始洞见是，集成和发布不应依赖某位工程师记得执行一串步骤。构建、测试、扫描、制品版本、审批和发布策略应作为系统能力存在。Agent 修改代码后走同一条流水线，正是这一原则的自然延伸：它不能有一条“AI 生成代码的快速通道”。
Google SRE 的发布工程原则强调可复现构建、自动化测试、自动部署和小批量变更；这些原则的价值在于降低不一致性、让状态可见并降低回滚成本。映射到 Agent，意味着：
- Agent 使用项目定义的标准命令，而非临时拼接环境；
- 每个改动关联到可重复执行的验证证据；
- 合并、发布与生产写入是不同权限层级，不能因为代码检查通过就自动跨越；
- 提交越小、构建越可复现，失败后的定位和回滚越便宜。
SRE：自治必须与影响半径和回滚能力绑定
SRE 的思维提供了反驳“最大化自治”的最强类比：生产发布完全可以高度自动化，但绝不会因为自动化程度高就取消监控、金丝雀、错误预算或回滚。自动化扩大的是执行速度，因此更需要控制影响半径。
对 Agent 也一样。可以把其权限和任务范围设计成渐进式发布：
| 阶段 | Agent 可以做什么 | 需要什么反馈/护栏 | 扩大范围的依据 |
|---|---|---|---|
| 沙箱 | 分析、生成计划、运行只读查询 | 来源标识、执行日志 | 事实定位稳定，计划可审阅 |
| 隔离工作区 | 修改代码、跑本地定向测试 | worktree、测试、diff 审阅 | 连续任务质量稳定且可回滚 |
| 预合并 | 创建 PR、执行完整 CI、做独立审查 | 分支保护、CI 门禁、代码所有者 | 变更失败率和返工没有恶化 |
| 受控交付 | 触发预发或灰度流程 | 审批、监控、自动停止/回滚 | 服务风险策略明确，演练过回滚 |
金丝雀发布的本质是以更小的真实影响换取更早、更便宜的学习；它不仅适用于上线，也适用于 Agent 工作流设计。先在低风险仓库、明确任务类型或有限模块上验证 Harness，再推广到复杂核心系统。
DevSecOps：信任应拆成能力，而不是授予身份
安全工程不把“某个使用者可信”理解为“他可以做任何事”，而是把能力细分为读取、写入、执行、访问秘密、调用外部服务和触发生产变更，并为每项能力提供最小权限、审计和必要审批。对 Agent 更应如此，因为它可能在一次会话中组合大量工具调用。
因此，一个成熟的 Agent 权限模型应回答：它能读哪些数据？能改哪些路径？能否安装依赖、联网、调用云 API？能否接触密钥？哪些操作必须由人批准？日志是否足以还原它做过什么？这些问题的答案应由策略和工具强制，而不是期待模型每次都正确理解自然语言规则。
复盘文化：把“Agent 犯错”变成系统学习
SRE 的无责复盘不等于没有责任，而是把注意力从“谁犯错”转向“为什么当时的系统允许错误扩大”。同样地，面对 Agent 的错误，最无效的反应是只说“下次 prompt 写好一点”。更有价值的提问是：
- 哪个事实本应可获取却没有入口？
- 哪条约束本应可自动检查却仍依赖记忆？
- 错误为什么没有在本地或 CI 中被更早发现？
- 是否缺少隔离、审批或回滚，才让影响范围扩大？
- 这次改进应沉淀为测试、规则、工具、权限策略还是参考实现？
这使 Agent 的每一次失败都能改善 Harness，而不是只改善下一次对话。也正是在这个意义上，Agent 工程不是“提示工程升级版”，而是持续交付、可靠性工程和知识管理在新型执行者上的重新组合。
论点一：Agent 是放大器，不是责任转移器
编程 Agent 与自动补全或聊天机器人不同：它能读取代码、执行命令、修改文件并根据结果继续行动。能力的跃迁不意味着软件工程基本规律失效。Google DORA 2025 的结论很适合作为总原则：AI 是放大器，既会放大高绩效团队已有的清晰边界、测试和交付纪律，也会放大糟糕流程中的混乱与返工。
因此，评估 Agent 不应只问“生成了多少代码”或“多久完成”，而应问：
| 问题 | 有效答案应包含 |
|---|---|
| 是否做对了？ | 可执行验收条件、自动化测试、关键场景检查 |
| 是否改在正确位置？ | 代码与架构证据、影响范围、最小改动 |
| 是否可维护？ | 与现有模式一致、依赖边界清楚、文档/决策可追溯 |
| 是否可安全交付？ | 权限约束、变更审查、CI 与发布护栏 |
Martin Fowler 将这种模式称为 agentic programming：人仍对软件的行为和实现负责，只是从直接输入代码转为监督能产生代码的 Agent。它不同于“只要结果能跑就不看实现”的 Vibe Coding，也不同于传统代码补全。
把 Agent 当成一位速度很快、能读能写但不了解本地隐性规则的新同事：给它目标、证据入口和反馈，而不是把责任外包给它。
为什么“能跑”远远不够
软件的质量有多个时间尺度。编译和单测失败通常在分钟内暴露；跨模块耦合、错误的领域建模或重复实现可能要在下一次需求迭代才显现；安全、成本与运维风险则往往在上线后才暴露。Agent 可以极快地产生局部可运行的代码，却同样可以极快积累后两类债务。
这解释了为什么成熟团队在引入 Agent 后不应降低工程标准，反而应提高自动验证的覆盖率：生成代码的边际成本下降后，错误代码的流入速度也会上升。 人工审查吞吐不会等比例增长，唯有把可机械验证的规则固化为检查，才能让交付能力与 Agent 吞吐共同扩展。
对团队的实际含义
“让 Agent 写代码”不是一项孤立的个人效率技巧，而是组织能力问题。若仓库没有可运行的测试、依赖边界不清、开发环境难以复现、发布过程不可回滚，Agent 会暴露并放大这些问题。DORA 的“放大器”观点因此不是宣传语，而是采用策略：应先修复最阻碍反馈的工程摩擦，再扩展 Agent 的任务范围。
论点二：先选任务，再给自主权
自主程度应由影响半径、可逆性与验证成本决定，而非由模型“看起来很强”决定。先从边界清晰、测试充分、可回滚的任务开始，逐步扩大范围。
| 任务类型 | 适合的 Agent 权限 | 人的主要职责 | 例子 |
|---|---|---|---|
| 低风险、可验证 | 可自主实现并运行本地检查 | 定义验收、审阅 diff | 补测试、机械重构、文档同步 |
| 中风险、跨模块 | 先探索和产出计划，批准后实施 | 确认边界、方案和依赖 | 新增 API、迁移调用方 |
| 高风险或不可逆 | 分析/生成建议；敏感操作必须人工批准 | 决策、审批、上线把关 | 生产数据、权限、支付、删除与发布 |
SWE-bench 从真实 GitHub issue 与对应 PR 构建评测集，提醒我们：即使任务描述和修复答案都已给定，真实仓库中的定位、依赖理解与验证仍然困难。不要把基准成绩直接外推为生产环境的自治能力。
用“风险 × 可验证性”而非“模型能力”做决策
模型能力会不断变化，但任务风险的来源更稳定：数据是否不可逆、是否影响用户与合规、是否跨越系统边界、失败是否能够快速发现和回滚。可验证性也并非二元状态，而是看是否存在可信的测试、观测和验收者。把两个维度放在一起，能避免“低风险却难验证”的盲区，例如隐性性能退化或不完整的文档迁移。
| 风险 / 可验证性 | 高可验证性 | 低可验证性 |
|---|---|---|
| 低风险 | 可预授权 Agent 执行；用自动检查收尾 | Agent 先调研、生成草案或补齐验证，再实施 |
| 高风险 | Agent 可在隔离环境中实现与演示；人审批合并/发布 | Agent 保持建议者角色；优先澄清需求、补测试和风险分析 |
所谓“给自主权”，本质上是在预先约定：什么可以自动做、什么需要停下来请求判断、什么永远不能越过权限边界。这比让 Agent 在失败后“自己反思”更可靠，也便于审计。
一轮可靠的 Agent 工作流
一轮工作应有明确输入和终点，而非“帮我把这个做好”。先让 Agent 理解和规划，再授权改动；每个阶段都产生可审阅的中间产物。
1. 写任务契约，而非泛化提示词
任务契约至少写清目标、范围、不可违反的约束、证据入口和验收方式；未知事实明确标为待确认项。它让 Agent 少猜，也让审阅者知道应该检查什么。
目标：为订单取消接口补充幂等保护。
范围：只修改 order-service；不改支付服务与数据库表结构。
约束：相同 requestId 不得触发重复退款；保留现有错误码语义。
证据入口：订单状态机文档、CancelOrderService、现有集成测试。
验收：新增重复请求测试；运行 order-service 的定向测试与静态检查。
未知项：支付回调与取消请求并发时的状态优先级，实施前确认。
2. 要求“证据 → 计划 → 改动”
第一轮先探索：定位实现、测试、规范和依赖，输出已验证事实及仍不确定之处。第二轮给出最小改动计划和风险。只有计划符合预期再进入写入阶段。这个节奏对应 Thoughtworks 提倡的 design-first collaboration 与 context anchoring：先建立共同心智模型，减少“生成—纠错—再生成”的摩擦循环。
3. 小批量提交，形成可恢复状态
一次只推进一个可独立验证的垂直切片：例如先加失败测试，再实现最小代码，再重构。长任务应把计划、已验证事实、验证结果和未完成项写入提交说明、任务单或进度文件；不要依赖聊天记录作为唯一状态。
这里的“小”不是按文件数机械限制，而是按是否能独立判断正确性来划分。一次修改三个文件、但只完成一个明确行为，通常比一次只改一个文件却暗中改变多个业务语义更安全。好的切片有明确的前置条件、单一验收结论和可回滚的提交边界。
论点三：反馈系统比限制系统更可扩展
工具设计：围栏与传感器
文章《Claude Code没有“魔法”》提出的工具区分很有用：一类工具弥补当前智能不足，另一类工具随智能提升仍然有价值。
| 工具类型 | 作用 | 典型例子 | 随 Agent 变强后的命运 |
|---|---|---|---|
| 围栏（能力替代/限制） | 防止越权或高危错误 | 禁止访问密钥、限制生产写入、要求人工批准 | 权限可按风险逐步扩大，但高危边界仍应保留 |
| 传感器（反馈/轻推） | 在正确时机提供可解释的事实 | 类型错误、测试失败、架构违规、依赖风险 | 持续有用；强者也会犯错，但能判断例外 |
围栏不是“模型不可靠才需要”的临时措施；安全、合规和不可逆操作本就需要独立控制。真正应避免的是用大量静态限制替代反馈系统。对于日常工程质量，更有杠杆的是让 Agent 在改动之后立即得到精确反馈，并能根据反馈自行修复。
Thoughtworks 将这类 Harness 分为前馈与反馈：规则、示例和架构约定属于前馈；测试、lint、类型检查和质量传感器属于反馈。两者共同构成 Agent 的工作环境。
把工程反馈接进 Agent 循环
传统工程实践在 Agent 时代更重要，因为它们是独立于模型的“外部真相源”。测试驱动开发提供快速且精确的反馈；持续集成、代码审查和可观测性则覆盖更广的失败模式。
| 反馈层 | 发现什么 | 应如何接入 Agent |
|---|---|---|
| 编译、格式、类型 | 基础正确性与一致性 | 改动后自动运行；只回传相关诊断 |
| 单元与集成测试 | 行为是否满足场景 | 任务契约指定定向测试，提交前运行完整必要集 |
| 架构与安全检查 | 越层依赖、漏洞、许可证、密钥 | 在本地与 CI 双重执行；高风险结果阻断交付 |
| 代码审查 | 需求理解、权衡、可维护性 | 人审查目标、边界和关键 diff；Agent 可先做独立审查 |
| 生产可观测性 | 延迟、错误率、成本、真实行为 | 将回归信号转为缺陷、测试或规则，而非一次性聊天反馈 |
关键原则是把反馈左移：CI 才会发现的确定性问题，尽量让 Agent 在本地改完就发现。对高吞吐的 Agent 工作流，“已验证”不能仅意味着人读过代码；应由测试、类型系统、自动化门禁和必要的人类判断共同组成。
什么是“可修复的反馈”
并非所有失败输出都能帮助 Agent 进步。好的反馈应具备四个特征：及时（发生在错误刚引入时）、定位明确（指出文件、规则或用例）、与任务相关（不把无关日志塞回上下文）、可行动（Agent 知道下一步可读什么、运行什么、修改什么）。例如，“CI failed”几乎没有价值；“OrderMapperTest 的重复请求场景断言失败，期望一次退款、实际两次；参见测试用例第 42 行”则能直接进入修复循环。
这也是 Hook 的正确定位：并非用它堆砌会话开场提示，而是在 PreToolUse、PostToolUse 或停止等确定事件上拦截高危行为、运行窄检查、把相关诊断送回 Agent。确定性规则交给代码执行，比反复要求模型“请记得遵守”可靠得多。
论点四：人应在循环之上
人的角色不是在“完全放手”和“逐行盯防”之间二选一。Thoughtworks 提出的 on the loop 更准确：人设计并维护工作循环，让 Agent 在循环内部执行、验证和迭代；当循环无法判断价值、风险或例外时，人再介入。
人与 Agent 各自负责什么
| 责任 | 更适合由人主导 | 更适合由 Agent 主导 |
|---|---|---|
| 价值与优先级 | 用户问题、业务取舍、成功定义 | 将已经明确的目标分解为执行步骤 |
| 约束与风险 | 合规、数据边界、不可逆决策、例外批准 | 发现约束冲突、列出风险与待确认问题 |
| 证据收集 | 决定哪些来源可信、何时信息足够 | 搜索代码、运行命令、归纳事实并附来源 |
| 实现与验证 | 审批架构性取舍、评估不可自动化的质量 | 写代码、补测试、运行检查、尝试修复 |
| 学习与改进 | 选择要投资的工程能力 | 从失败记录中提出规则、测试或工具改进建议 |
这张表的核心不是固定分工，而是把人类注意力留给机器难以验证的判断。当人反复手工确认格式、类型错误或显而易见的测试失败时，说明反馈没有被工程化；当人跳过产品语义、架构权衡和异常风险时，说明监督被错误地自动化了。
“循环之上”的三个管理动作
- 管理输入质量：让需求有验收语言，让规则可执行，让知识有权威来源与所有者。
- 管理中途决策点：在跨边界、影响半径扩大或证据不足时要求 Agent 停下并呈现选项，而不是暗中继续猜测。
- 管理学习资产：把一次成功或失败变成测试、脚本、参考实现、规则或 Skill；否则下一次任务仍从零开始。
上下文、规则与能力如何分工
不要把所有知识写入一份越来越长的规则文件。Claude Code 和 Codex 等工具的名称不同，但可按以下职责划分：
| 载体 | 适合放什么 | 何时加载/触发 | 不宜放什么 |
|---|---|---|---|
AGENTS.md / 项目规则 | 高频不变量、项目地图、常用验证命令 | 会话或目录进入时 | 任务细节、长篇设计史 |
| 任务契约 / Spec | 本次目标、范围、验收、风险 | 任务开始 | 泛化团队规范 |
| Skill | 可复用但低频的流程 | 与任务匹配时按需加载 | 每个会话都必须知道的内容 |
| Hook | 可确定触发的检查、审批、日志、上下文注入 | 工具调用或生命周期节点 | 需要开放式推理的主流程 |
| MCP / CLI | 获取外部事实或执行特定能力 | 需要时调用 | 已有 CLI 的简单封装、过多重叠工具 |
Anthropic 的指导强调，这些机制的关键差异是加载时机、上下文成本和权威性。一个实用判断是：
- 每次都成立且很短：放项目级规则。
- 只对某类任务成立：放 Skill 或路径规则。
- 需要在事件发生时可靠执行：做 Hook 或 CI 检查。
- 需要查询外部真实状态：提供窄而可审计的工具接口。
尤其要克制 MCP 数量与工具描述的膨胀。工具越多并不必然越强；重叠且命名模糊的工具会耗尽上下文、降低选择正确工具的概率。优先复用已有 CLI，并给工具提供清晰动词、输入边界、返回结构、来源与权限说明。
关于更完整的分层策略，见 Context Engineering：为 Agent 构建高信噪比任务上下文。
多 Agent：何时值得并行
多 Agent 的收益来自独立任务的并行探索或验证，而不是把一项模糊任务拆成一群 Agent 同时猜。Thoughtworks 建议从小而刻意的角色团队开始：主 Agent 负责协调，其他 Agent 分别做代码勘察、方案质疑、测试设计或安全审查。
适合并行的前提：
- 每个子任务有明确产物和边界，例如“列出调用方并附路径证据”或“审查迁移的回滚风险”。
- 使用隔离分支或 worktree，避免多个 Agent 修改同一工作区。
- 由一个整合者处理冲突、选择方案并运行最终验证。
- 并行成本低于串行等待；否则单 Agent 的短循环更简单、更可靠。
多 Agent 不是把人从循环中移走，而是把人的工作从频繁输入代码转为设计任务边界、分配注意力和处理高影响决策。
团队落地路线
先把可重复任务工程化，再追求自治。每一阶段都要用质量、交付和返工数据验证，而不只统计生成代码量。
| 阶段 | 目标 | 最小实践 | 退出标准 |
|---|---|---|---|
| 1. 个人可用 | 在低风险任务稳定受益 | 小任务契约、定向测试、人工审阅 | 能复现成功流程，失败能说明原因 |
| 2. 项目可用 | 让新成员与 Agent 都能快速上手 | 精简 AGENTS.md、路径规则、标准命令、参考实现 | 常见任务不再反复解释规范 |
| 3. 团队可用 | 让质量反馈自动回流 | CI 门禁、Hook、失败归因表、审查模板 | 重复错误转化为测试、规则或工具 |
| 4. 受控并行 | 提升独立工作吞吐 | worktree、角色化子任务、汇总看板 | 并行任务不互相踩踏，质量指标不恶化 |
建议每两到四周做一次轻量复盘：哪些约束总被违反？是知识缺失、任务边界不清、工具反馈太晚，还是自动检查没覆盖？针对根因修改最合适的层，而不是不断往提示词末尾追加规则。
失败归因要落在正确层
重复失败不是“再写一条 Prompt”的证据，而是 Harness 有缺口的信号。对每个高频失败做一次归因：
| 观察到的失败 | 常见根因 | 优先改进 |
|---|---|---|
| Agent 修改了错误模块 | 缺少项目地图或任务范围 | 任务契约、目录规则、代码导航 |
| Agent 不断重试同一命令 | 环境前置条件未说明，错误输出不清楚 | 一键环境检查、失败诊断、Skill |
| Agent 漏掉必跑验证 | 验收未写入任务，检查依赖人的记忆 | 标准命令、Hook、CI 门禁 |
| 代码通过测试却破坏架构 | 测试只覆盖行为，缺少结构约束 | 架构测试、依赖规则、审查清单 |
| Agent 给出看似合理但错误的结论 | 事实来源不权威或上下文陈旧 | 为工具返回来源/时间戳，建立文档所有权 |
改进完成后要用同类任务复测，确认失败频率下降。否则规则文件只是在增长，团队并不知道它是否提升了可靠性。
如何衡量是否真的变好
Agent 采用的常见误区是把提交数、代码行数或一次任务耗时当作主指标。这些指标能反映局部速度，却可能掩盖返工、缺陷和维护成本。建议同时观察流动、质量、认知负担和学习速度四组信号。
| 维度 | 应观察的信号 | 反例：不应单独追求 |
|---|---|---|
| 流动效率 | 从任务澄清到合并的周期、等待时间、可并行任务数 | Agent 生成的总代码行数 |
| 质量 | 变更失败率、回滚、缺陷逃逸、架构违规、测试稳定性 | “测试数量”本身 |
| 认知负担 | 人工审阅的有效时间、反复解释次数、上下文切换次数 | Agent 连续运行时长 |
| 学习速度 | 重复失败被转化为自动检查的比例、规则/工具的复用率 | 规则文件的字数 |
评估应比较“有 Agent 的完整交付闭环”与“没有 Agent 的完整交付闭环”，而不是只比较编码阶段。若实现更快但 review、CI 排队、返工和线上排障显著增加，团队并没有获得真实的研发效能。相反，哪怕首轮速度略慢，只要任务契约、测试和反馈资产逐步复用，后续同类任务会出现复利。
反模式与检查清单
| 反模式 | 为什么无效 | 改法 |
|---|---|---|
| “帮我实现 X”后直接接受结果 | 目标、约束和验收均缺失 | 先写任务契约，要求计划与证据 |
| 巨型规则文件 | 稀释高优先级信息且易陈旧 | 分层、按路径和按任务加载 |
| 只靠人工逐行审查 | Agent 吞吐越高，人成为瓶颈 | 用自动检查覆盖确定性问题，人聚焦判断 |
| 只追求更多工具/MCP | 工具选择与上下文成本会反噬 | 合并重叠能力，提供窄接口和清晰名称 |
| 多 Agent 共用工作区 | 竞争写入，难以归因和回滚 | 隔离 worktree，由整合者合并 |
| 把每次失败留在聊天里 | 学习不会积累 | 写入测试、规则、Skill、Hook 或参考实现 |
开始一个 Agent 任务前，可以快速检查：
- [ ] 目标、非目标、验收方式和风险等级是否明确？
- [ ] Agent 是否知道从哪里读取权威事实与项目约定？
- [ ] 是否先探索和计划，再进行高影响写入？
- [ ] 改动后是否有快速、独立、可重复的验证？
- [ ] 敏感操作是否有最小权限、审计与人工批准？
- [ ] 人是否在审阅真正需要判断的事项，而不是重复机器能检查的内容？
- [ ] 重复失败是否会沉淀为工程资产？
参考资料
- Claude Code没有“魔法”｜InfoQ
- Steering Claude Code: skills, hooks, rules, subagents and more｜Anthropic
- Automate workflows with hooks｜Claude Code Docs
- How Claude Code works in large codebases｜Anthropic
- AGENTS.md｜OpenAI Codex Docs
- Agentic Programming｜Martin Fowler
- Patterns for Reducing Friction in AI-Assisted Development｜Thoughtworks Insights
- Context Engineering for Coding Agents｜Martin Fowler
- Humans and Agents in Software Engineering Loops｜Thoughtworks Insights
- Harness engineering and agent feedback｜Thoughtworks
- Team of coding agents｜Thoughtworks Technology Radar
- DORA 2025 State of AI-assisted Software Development Report｜Google Research
- SWE-bench: Can Language Models Resolve Real-World GitHub Issues?｜arXiv
- Release Engineering｜Google SRE Book
- Canarying Releases｜Google SRE Workbook
- Postmortem Culture: Learning from Failure｜Google SRE Book
- Software engineering agents｜Thoughtworks Technology Radar
评论 (0)