采用 AI 编码智能体的六条经验¶

Ch09.018 采用 AI 编码智能体的六条经验¶

📊 Level ⭐⭐ | 16.8KB | entities/adopting-ai-coding-agents-six-lessons.md

背景¶

AI 编码智能体正在从"代码补全工具"演变为"能读仓库、改文件、调工具、跑测试、开 PR"的完整协作者。但软件工程过去几十年都建立在确定性机器上，如今第一次大规模面对一个非确定性协作者——这带来了根本性的工程挑战。

采用 AI 编码智能体不是简单地接一个 API，而是需要围绕"如何让非确定性变得可控"建立一整套工程实践。以下六条经验是从行业实践者（Martin Fowler、天猫营销技术团队、OpenAI Harness Engineering）中提炼出的核心教训。

经验一：先把任务切小——从可独立验证的小任务下手¶

问题¶

如果一上来就让 Agent 接手一个大功能，它很容易理解不完整、改错文件、漏掉依赖，最后产出一堆难以审查的代码。

解法¶

把任务切成可以独立验证的小块。每个子任务满足：

边界清晰：改什么文件、调什么接口、影响什么范围
完成标准明确：怎样算"完成"——通过测试？通过 lint？
可独立测试：不依赖其他未完成的模块

小切片不仅降低 Agent 的认知负担，还隐含承担了一件事：限制模型一次性发散的半径。

实践要点¶

一个有效任务的标准：能否独立验证、边界是否清晰、完成标准是否明确
大任务用 Harness Engineering 的 Explore-Plan-Act 循环：先探索、再规划、最后动手
切小后给 Agent 的指令要包含验证方式（"这个任务完成的标准是跑通 /test/api/users"）

经验二：把知识放回仓库——Agent 看不见就等于不存在¶

问题¶

Slack 里的决策、Google Docs 里的规范、人脑子里的经验——这些对 Agent 都是黑洞。它只能在当前上下文看到的信息里工作，超出这个范围就是"不存在"。

解法¶

知识进仓库的判断标准：Agent 看不见就等于不存在。

将隐性知识转化为 Agent 能读取的形式：

架构规则 → 写进 linter / CI 配置，而不是只在 wiki 里
调用规范 → 写成 MCP tools 或 Skills
决策记录 → 写成 ARCHITECTURE.md / DECISIONS.md
模板代码 → 封装成 npm package（天猫团队的创新做法）

实践要点¶

架构规则要交给 linter 和 CI 机械执行，不能只写在 wiki 里或只靠 prompt。wiki 是给人看的，linter 是给 Agent 看的
一个有效规则的标准：Agent 跑偏时，CI 能自动拦住，而不是靠人 Review 发现
规范每一行都对应一个历史失败案例——凭空设计的"最佳实践"不如真实踩坑后的约束

经验三：让验证先跑起来——测试、类型约束、lint、架构边界检查¶

问题¶

AI 生成代码越快，变更的风险扩散也越快。没有验证网络，AI 每次生成都是一次"盲盒"——不知道这次是不是把之前的功能改坏了。

解法¶

不要让 LLM 做可以确定性计算的事。具体来说：

能用类型检查的 → 不用 prompt 描述"这个应该是字符串"
能用单元测试验证的 → 不靠人肉 review
能用 lint 拦住 → 不靠"AI 注意一下"这种模糊提示
能用架构边界检查的 → 不靠"请遵守分层架构"这种空洞要求

实践要点¶

天猫团队将 AI 编码问题归纳为四类：写不对（意图对齐）、写不好（质量规范）、写不了（项目知识隐含）、改不动（长程迭代退化）。验证体系是解决前两类问题的核心工具
AI 自由发挥场景下准确率仅 70%；在规范约束下可达 95%——验证是让 AI 在约束区间内工作的关键机制
马丁·福勒的核心观点：测试和重构不是旧时代包袱，而是 AI 时代的价值锚——AI 生成越快，确定性反馈环越值钱

经验四：权限按风险分层——读/写/执行/删除/合并分级管理¶

问题¶

如果让 Agent 什么都能做，风险极高——它可能误删文件、强制推送主分支、执行危险的 shell 命令；但如果每一步都让用户确认，很快就会点到麻木。

解法¶

渐进式工具扩展 + 命令风险分类：

渐进式工具扩展：先给一小部分常用工具（读文件、搜索），其他工具按需再打开
命令风险分类：执行前做一层"风险判断"——低风险自动放行，高风险才需要人工确认

风险等级	示例操作	处理方式
低风险	`git status`、`grep`、读文件	自动放行
中风险	创建文件、修改已存在文件	提示确认
高风险	`git push -f`、删除文件、执行 `rm -rf`	人工授权
极高风险	直接操作线上数据库、修改 CI/CD 配置	禁止自动执行

实践要点¶

Claude Code 源码分析显示其权限控制细到很具体的粒度，远比大多数 Agent 框架更严格
权限分层还意味着不同阶段的 Agent 有不同权限：调研 Agent 只读不写，执行 Agent 才有完整工具权限

经验五：错误要分类——分清参数错误、环境错误、权限错误、供应商错误等¶

问题¶

如果分不清错误类型，就没法往 Harness 里写对应的处理规则。每次失败都是随机应变，团队无法积累有效的防御机制。

解法¶

先把团队内 AI 翻车案例做一次系统性分类：

错误类型	典型表现	对应处理
参数错误	传给工具的参数格式/类型不对	补充工具 schema 或增加校验
环境错误	依赖缺失、路径错误、版本不兼容	固化环境配置到 Harness
权限错误	读写权限不足、API key 问题	完善权限配置和降级策略
超时错误	工具调用超时、大文件处理超时	增加超时控制和分片处理
供应商错误	模型 API 限流、服务端异常	实现 fallback 机制和重试策略

实践要点¶

分类是定向的前提——分不清类型就没法往 Harness 里写对应的处理规则
每次失败后，往系统里多塞一点确定性（经验六的核心）
用错误分类驱动 Harness Engineering 的迭代：Guides（事前防御）+ Sensors（事中检测）+ Garbage Collection（事后清理）

经验六：把经验写回 Harness——每次失败后往系统里多塞一点确定性¶

问题¶

AI 的错误会重复——如果每次失败都只靠人"这次小心点"，同样的错误会在不同人、不同时间点反复出现。

解法¶

这是六条经验的核心闭环：把人的判断不断替换为系统确定性。

每次失败后问：这个错误以后怎么防止？把这个答案编码进系统：

如果是 prompt 不清楚 → 补充
如果是工具行为不对 → 修复工具 schema 或增加约束
如果是环境问题 → 补充环境检查或 Docker 配置
如果是权限问题 → 完善权限边界配置

实践要点¶

Martin Fowler 和 OpenAI Harness Engineering 的共识：技术债用持续小 PR 清，不做专项治理
大坑等不来专项治理，只能靠持续小动作消化
把这一条写成团队规范，比一次技术债清理大会更有效
六件小事形成一个循环：任务切小→知识进仓库→验证先跑→权限分层→错误分类→经验写回 Harness
长期积累下来，Harness 的容量决定了 Agent 能稳定承担多少工作

六条经验的内在逻辑¶

这六条经验不是零散建议，而是一个不断把"人判断"替换为"系统确定性"的循环：

任务切小 → 知识进仓库 → 验证先跑 → 权限分层 → 错误分类 → 经验写回 Harness
    ↑                                                                      ↓
    └────────────────────── 持续迭代 ←──────────────────────────────────┘

核心洞察： 1. Agentic Engineering 的重点不是把人从工程里抽走，而是把人的工作往目标、边界、验证、治理和经验沉淀这边挪 2. Harness 不只是个新包装词——把它当成"非确定性适配层"更顺手：上下文、工具、权限、测试、观测、垃圾回收都在这层承重 3. Vibe Coding 解决"怎么做出"，Agentic Engineering 解决"怎么拥有"——拥有意味着知道它为什么这样设计、怎么验证、出事了怎么回滚

深度分析¶

Insight 1: AI 编码的核心工程挑战是"非确定性协作"而非"代码生成"

Martin Fowler 指出软件工程过去几十年都建立在一台确定性机器上，如今 AI 的出现第一次将非确定性协作引入研发链路。这不是简单的工具升级，而是根本范式的转变——从"人写代码、机器执行"到"人定目标、AI 自主执行"。

Insight 2: Harness Engineering 是非确定性进入工程系统的必然产物

围绕 AI 编码的各个新词——Vibe Coding、Agentic Engineering、Context Engineering、Harness Engineering——其实都在回答同一个问题：当 AI 开始读仓库、改文件、调工具时，研发系统如何消化这种非确定性。Harness 作为适配层，需要承载上下文、工具、权限、测试、观测和垃圾回收等功能，而不是简单的包装词。

Insight 3: 验证体系是缩小 AI 准确率差距的关键机制

AI 在自由发挥场景下准确率仅 70%，但在规范约束下可达 95%。这个差距说明验证机制不是限制 AI 的枷锁，而是引导 AI 在约束区间内工作的关键工具。传统工程中的测试、类型检查和 lint 在 AI 时代反而获得了新的价值，因为它们为 AI 的每次变更提供了确定性反馈。

Insight 4: 六条经验构成一个持续迭代的确定性增强循环

这六条经验形成一个循环：任务切小降低认知负担，知识进仓保证上下文可见，验证先行提供快速反馈，权限分层管控风险，错误分类定向修复，最后将经验固化到 Harness 使系统持续自我改进。每一次循环都减少了"人判断"，增加了"系统确定性"。

实践启示¶

先用小任务验证团队 AI 编码流程：从可独立验证的小任务入手，不要一开始就尝试完整功能。用小任务的成功建立对 AI 编码的信任，再逐步扩大应用范围。
知识沉淀要落地到可执行载体：wiki 和文档是给人看的，给 AI 用的应该转化为 linter 规则、CI 配置、工具 schema 等机器可执行的载体。判断标准是"Agent 看不见就等于不存在"。
把错误案例分类后写入系统：每次 AI 翻车后，问"这个错误以后怎么防止"，然后把答案编码进 Harness——补充 prompt 规则、修复工具约束、完善环境配置或补充权限边界。
技术债靠持续小 PR 清理：不要等大坑、等专项治理——用持续小动作消化技术债，比一次技术债清理大会更有效。
渐进式开放工具权限：先给读文件、搜索等低风险工具，高风险操作（push -f、rm -rf、线上数据库）默认禁止，通过人工确认才放行。

采用 AI 编码智能体的六条经验¶

Ch09.018 采用 AI 编码智能体的六条经验¶

背景¶

经验一：先把任务切小——从可独立验证的小任务下手¶

问题¶

解法¶

实践要点¶

经验二：把知识放回仓库——Agent 看不见就等于不存在¶

问题¶

解法¶

实践要点¶

经验三：让验证先跑起来——测试、类型约束、lint、架构边界检查¶

问题¶

解法¶

实践要点¶

经验四：权限按风险分层——读/写/执行/删除/合并分级管理¶

问题¶

解法¶

实践要点¶

经验五：错误要分类——分清参数错误、环境错误、权限错误、供应商错误等¶

问题¶

解法¶

实践要点¶

经验六：把经验写回 Harness——每次失败后往系统里多塞一点确定性¶

问题¶

解法¶

实践要点¶

六条经验的内在逻辑¶

深度分析¶

实践启示¶

相关实体¶

参考来源¶