第 0 章：心智模型，与你的第一个 agent

草稿章节。跑通格式用的第一版，正式索引前会再打磨。

本章目标

读完这章，你会装好一个编码 agent，在一个真实的仓库里给它派一个小而真实的活，看它跑完整个过程：读代码、提改动、交给你审。这个活就是全书要做的那个项目的起点：一个 PR 审查 agent，它读一段 diff，挑出 bug 和风险。这章还不动手搭这个 agent。你先用一个通用的编码 agent，手动做一遍审查里的一小步，把要解决的问题摸清楚，再谈后面的抽象。

更重要的是，你会完成这本书最关键的转变：从自己逐行敲代码，变成指挥和审查。微软那篇《AI agents 入门》把 agent 定义成一个能感知环境、做推理、用工具去达成目标的系统。这个定义没错，但对每天写代码的人来说，真正要变的地方更简单：你不再亲手写代码，而是负责审。代码由 agent 来敲，对不对由你来判断。

这是第 0 部，目的就是让你快点跑出第一个结果。深入的内容放在后面。

前置准备

• 一个你用得顺手的终端，和一个代码编辑器。
• 一个能安全折腾的 git 仓库（新开一个 scratch 分支，或者克隆一份用完就删）。绝对不要让一个刚装好的 agent 去动你没法回滚的、还没提交的改动。
• 一个编码 agent 的使用权限。本书主要用 Claude Code，第 7 章会拿 Codex 做对照。账号订阅或 API 都行。
• 会基本的命令行操作。你现在还不用懂 agent 内部是怎么运作的，那是第 2 章的事。

动手做

1. 装好 agent，并搞清楚去哪查官方信息

照官方安装指南装，别照抄这里的命令。安装步骤和参数经常变，真正有用的是知道去哪查官方文档，而不是记住某条命令（见“来源”）。现在值得养成一个习惯：安装命令报错时，认真读报错本身、去翻文档，而不是把报错复制进搜索引擎、点开第一个答案就试。以后 agent 自己出问题时，你要用的也是这个习惯。

2. 完成认证，挑最省的那条路

按指南用账号或 API key 登录。如果你订阅和 API key 都有，交互使用时先用官方指南推荐的那个。接下来只跑一个很小的任务，成本现在不重要，重要的是完整跑通一次：你发指令、它干活、它回报。

3. 在项目里打开它，且开在一个能扔掉的分支上

在你那个 scratch 仓库的根目录启动 agent，这样它能看到文件。动手之前，先把下面这个安全网搭好：

git switch -c agent-scratch          # 一个随时能删的分支
git status                           # 开工前必须是干净的
# ... 让 agent 干活 ...
git diff                             # 读完它改的每一处
git restore .                        # 或：git switch main && git branch -D agent-scratch

为什么这么做：agent 改得快、看着也对，这种东西最容易没人细看就被合并进去。一个用完就删的分支，能把“我得特别小心”变成“反正随时能重置”。这样你审起来会踏实很多。

4. 交给它一个小而真实的任务：单文件审查

别拿玩具任务练手。就用我们这个项目的第一步：在仓库里挑一个你最近改过的文件，让 agent 像一个细心的同事那样审一遍：

读 src/payments/refund.py。用 5 条要点，列出这个文件里最可能的
bug 或风险。每一条都点名具体的行或函数，说清为什么有风险，
并标注 高 / 中 / 低。不要重写代码。不要客气含糊；如果没有风险，
就直说没有。

注意这段 prompt 干了三件事：把范围限定在一个文件；规定死输出格式（五条、点出行号、标严重度）；不许 agent 跑偏去重写代码。这几条约束不是摆设。有了它们，这份结果你两分钟就能看完，而不是二十分钟。第 1 章会讲到，这种随手写的要求，可以变成一份能重复用的契约。

5. 盯着这个回路，别走开

看清楚它干活的节奏：读上下文 → 提方案 → 有时跑条命令 → 回报结果。你也在这个循环里：批准、纠正方向，或者否决。agent 说某处有 bug 时，别全盘照收。打开它指的那一行，自己核对。你通常会碰到三种情况之一，每种都能学到点东西：

• 一个你自己漏掉的真问题。很好，留着。
• 一个它编出来的问题（它描述的代码压根不在那）。这种错你得练到一眼就能看出来。
• 一个被说成“风险”、其实只是风格问题的小毛病。降一档处理。

习得「指挥，而非动手」你把第一个真实任务从头跑到尾，第一次坐到指挥的位置：它提议，你审查。

如何验证

做到下面几点就算完成：

• agent 给出了你能读的具体结果（那五条审查意见），而不是一句聊天式的回复。
• 你自己审了一遍，对每一条都明确地接受或否决。如果你没打开文件就把整张清单收下了，这一步重做。能不能做到这点，就是“工具”和“坑”的区别。
• 你能用一句话说出：它标出的最严重的风险是什么，你同不同意。
• git status 显示没有任何改动（这是一个只读加审查的任务）；如果有改动，那也是你逐行看过的。

习得「认出幻觉」你学会逐行核对它说的话，分得清真 bug、它编出来的问题、和被当成风险的小毛病。

原理

编码 agent 不是魔法，也不是搜索引擎。它就是一个循环：读一些上下文，猜一个有用的下一步，然后由你（或某个工具）把结果喂回给它，这样一圈圈转，直到完成目标。第 2 章会让你亲手写出这个循环。现在你只要记住一件不对称的事：agent 生成代码比你打字快得多，但它生成得再快，你也只能按自己审查的速度去信任它。所以你作为操作 agent 的人，整体能出多少活，是审查速度说了算，不是 agent 的生成速度。后面每一章（契约、评估、护栏）要做的，都是帮你把“能放心审查的量”提上去。

小结

你跑通了第一个 agent；更重要的是，你坐到了指挥的位置：agent 提出一份审查，你拿着源码一条条核对。“它提议、你审查”这层关系，是后面所有内容的基础。而这次单文件审查，就是那个 PR 审查 agent 的起点，你会在全书里一点点把它做大。

本书剩下的部分，就是带你从“它能跑”走到“我敢信”：第 1 部让 agent 听话，第 2 部把重复的活做成 Claude Code / Codex skills，第 3 部用评估、可观测性、护栏让它变得可靠，第 4 部把它发上生产。下一章：Prompt 即契约。

常见坑

• 在脏状态下跑。 永远从一个干净、已提交、能 git reset 退回去的检出开始。
• 没读就接受改动。 agent 很快，正因为快，“没看就收下”才危险。一份听着挺有道理的 bug 报告，你就信了，而这是这里最容易养成、代价也最高的坏习惯。
• 一上来就丢个大任务。 又大又模糊的要求（比如“审查我整个仓库”），最容易让 agent 跑偏、开始瞎编。先做一个文件、问一个清楚的问题。
• 把它说的当成事实，而不是说法。 它标出的每一条风险，都只是一个等你去对应行核实的假设，不是定论。

它第一次开口，只会把你的话原样还给你。你给这团回声起了个名字：小满。它「记住」了自己的名字（其实只是 system prompt 多了一行，可你心里还是咯噔了一下）。初醒之隅，亮了。

0123456789101112131415

刚点亮 初醒之隅 · 地图已点亮 1 / 16

可它连「该听谁的」都还不懂。下一站：契约厅。

来源

1. Claude Code 官方文档 · official
2. microsoft/ai-agents-for-beginners · official