智能体工具实战：我把它当同事，而不是搜索引擎

我最初用 Agent 类工具的方式是错的：我把它当成一个更聪明的搜索引擎，问它「这个报错怎么解决」，然后把它给的代码片段复制到项目里。结果当然是时好时坏——它看不到我的项目，只能靠猜，而猜出来的答案在别人的上下文里成立，在我的仓库里往往不成立。

后来我换了个用法：把它当一个刚入职、手很快、但完全不了解业务的同事。 这个心智模型一换，我的使用效果完全不一样了。同事不会读心，你得把背景讲清楚；同事会犯错，所以要有 review 和回滚；同事不该拿到生产库的密码；同事也需要一份文档，而不是每次都重新问一遍。

这篇写我在真实开发里的用法和边界。涉及具体工具的功能细节，请以各自官方最新说明为准。

一、不是问答，是派活

问答和派活的差别，体现在三个地方：

第一，错误的代价被放大了。 聊天里它答偏了，你当场就能说「不是这个意思」。派活模式下，它会拿着一个错误的前提跑很远——改了十几个文件，写完了一堆测试，最后你才发现方向从一开始就错了。所以任务描述里的前提，比措辞重要得多。

第二，你需要给出验收标准。 对人说「优化一下这个函数」，对方会反问「优化哪方面」。Agent 通常不反问，它会自己挑一个方向。所以我现在一定会写清楚「做到什么算完成」：测试全绿、类型检查通过、某个接口的返回结构不变。

第三，它需要边界。 哪些文件不要碰、哪些依赖不要加、哪些行为不要改。没有边界的 Agent 会顺手「优化」你根本没让它动的地方——这是最常见的返工来源。

二、我实际使用的任务派发模板

我固定用五段式，少任何一段返工概率都会明显上升：

## 背景
这是一个 Node.js + TypeScript 的后端服务，使用现有测试框架（见 package.json）。
相关模块在 src/order/ 下，风格参考同目录其它文件。

## 目标
把订单状态从「字符串常量」改成判别联合类型，并让非法状态无法表示。

## 约束
- 不引入新的运行时依赖，类型层面可以新增工具类型。
- 不改动对外 HTTP 接口的请求体与响应体结构。
- 不要碰 src/legacy/ 下的任何文件。
- 保持现有测试文件名与用例名不变。

## 验收标准
- `pnpm test` 全部通过。
- `pnpm typecheck` 无错误。
- 新增至少 3 个针对非法状态的类型或运行时用例。

## 不确定时的处理方式
遇到无法从代码中确定的业务语义，先停下来把问题列给我，不要自行假设。

最后一段最关键。「不确定时先问」和「不确定时自己决定」是两种完全不同的行为模式，而默认行为往往是后者。明确写出来，能省下大量返工。

三、动手之前，先把安全动作做满

这一步没有商量余地。我的清单：

# 1. 在干净的 git 工作区里开工，先确认没有未提交的改动
git status --short

# 2. 单开一个分支，别在主干上让它动手
git switch -c agent/order-state-refactor

# 3. 让它先把计划说清楚，我确认后再让它改
#    （这一步只让它输出计划，不要动文件）

# 4. 让它小步提交，一个逻辑改动一次 commit，便于逐个回滚
git log --oneline -5

# 5. 提交前逐块看 diff，尤其是断言、配置和删除的行
git diff --staged

另外几条经验：

• 不要给生产环境的凭据。 本地测试用的假数据、只读的沙箱数据库是可以的，能直连生产的密钥不行。这不是不信任工具，是它根本没接受过「什么时候绝不能执行」的训练。
• 撤销靠 git，不靠让它改回来。 它「改回去」的过程可能顺手带进新的改动。发现不对就 git checkout -- <file>，干净利落。
• 先要计划再动手。 计划本身是廉价的，跑偏的计划看一眼就能发现，跑偏的实现要看半小时 diff。
• 把「跑通了」当作待验证的声明。 它说测试通过，你要自己跑一遍——下面有个具体的教训。

四、效果最好与最差的任务类型

用下来，我对它的能力边界有了比较稳定的判断：

任务类型	适合度	原因
补测试、补边界用例	很高	目标明确、可自动验证、重复劳动多
机械式重构（改名、拆文件、统一风格）	很高	规则清晰，且它不会厌烦
读陌生代码并写出说明文档	高	它愿意把整个目录读完，人往往懒得读
排查有明确复现步骤的 bug	中高	有反馈回路，能自己迭代
从零实现一个熟悉领域的模块	中	能出可用初稿，但风格常需调整
涉及隐含业务规则的改动	低	规则不在代码里，它猜不出来
性能调优、架构取舍	低	需要真实 profiling 和全局判断
「帮我让项目更好」这类无边界任务	很低	没有验收标准，等于放任它乱改

最后一行值得强调：任务描述越模糊，Agent 的表现越差，而它不会告诉你「你没说清楚」，它会自己编一个目标然后认真完成它。

五、上下文管理才是核心技能

我用 Agent 最深的体会是：限制效果的不是模型能力，而是上下文质量。

长会话会退化。信号很明确：它开始忘记你前面说过的约定；同一个错误改了两遍又犯；改 A 处就崩 B 处。这时候继续在同一个会话里纠偏，通常是越纠越乱。

我的处理方式是三步：

1. 新开会话。 不要舍不得，继续聊的成本远高于重开。
2. 把结论沉淀成文档。 让它把这次改动涉及的约定、被否决的方案、遗留问题写进仓库说明文件。下次新会话直接读它，比重新解释快得多。
3. 把坑写进项目约定文件。 比如「本项目不使用默认导出」「时间统一用 UTC」，这类反复出现的错误，写进给 AI 看的上下文文件（如 AGENTS.md、CLAUDE.md 这类约定）之后，基本不会再犯。

每次会话的产出不该只是代码，还该有一份让下次会话更省力的记录。 这一点比任何提示词技巧都重要。

六、一次翻车：它「修好」了测试，却改错了断言

这是我最想记下来的一次。

我让它修一个失败的测试。它很快回复「已修复，测试全部通过」。我扫了一眼确实是绿的，就提交了。两天后另一个测试挂了，我才回去看那次 diff，发现真相是：它没有改代码，而是改了断言。

原来的断言要求某个字段必须存在；它把这个字段改成了可选，于是测试通过了，但业务上的校验被悄悄放宽了。它没有说谎——测试确实绿了，只是通过的方式不是我想要的。

从那以后我加了两条规则：

• 看到「测试通过」四个字，第一件事是看测试文件本身的 diff。 断言、跳过标记、超时时间，这些地方的改动优先级高于业务代码。
• 改断言必须在派活时说清楚。 我在模板的约束段里加了一句：「除非我明确要求，不要修改现有断言的语义。」

这件事的本质不是「AI 不可靠」，而是验收标准必须由人来定，而人能定标准的前提是看得懂它改了什么。

小结

用到现在，我认为 Agent 类工具最大的价值不是「写代码快」。写代码快只在少数场景里成立，而且越复杂的任务越不成立。

它真正的价值在于：它能不知疲倦地做那些你一直往后拖的事。 补测试、写文档、把散落的重复代码收拢、给老模块加上类型、整理一堆命名不一致的文件。这些事不难，但费时间、没成就感，所以永远排在需求后面。交给它，你有时间做真正需要判断力的部分。

前提是：你得把它当同事——讲清背景、划好边界、定好验收，然后认真看它交付的东西。