它不是补全，是一个会自己动手的同事

1.1 从一个被改坏的下午说起

设想这个场景：你在一个五年历史的服务里修一个空指针异常。你打开熟悉的 AI 补全插件，把光标放在可疑那行，它给你补出一个 if (user != null)。你接受，提交，收工。整个过程里，工具只看见了光标周围几十行。

现在换成 Claude Code。你在项目根目录敲一句”用户在未登录状态下访问订单页会崩，定位并修复”。接下来发生的事完全不同：它先用搜索工具在仓库里找订单页的路由，读了三个文件，发现崩溃其实来自一个中间件里没有处理的空 session，然后修改中间件、跑测试、把测试输出贴给你。

同一个问题，两种工具的差别不在”谁的代码写得更好”，而在谁在做决策。补全工具的决策权在你手上，它只负责填空；Claude Code 会自己决定读哪些文件、跑哪些命令、改哪里。

这就是”agentic（能动的）“这个词的实际含义，也是所有后续麻烦和所有后续收益的共同源头。

1.2 三步循环：收集上下文、采取行动、验证结果

官方文档把 Claude Code 的工作方式描述为一个反复运转的循环。用最朴素的话讲，它每一轮都在做三件事：

1. 收集上下文：读文件、搜索代码、看你贴进来的报错、必要时抓一个网页。
2. 采取行动：编辑文件、创建文件、执行 shell 命令、调用外部工具。
3. 验证结果：跑测试、看构建是否通过、读命令的返回，然后判断是继续、修正，还是收工。

它可用的工具大致分几类：文件操作（读、改、写）、搜索（按文件名匹配、按内容正则搜）、执行（跑 shell 命令）、联网（取网页、搜索），以及派生子任务的能力。

1.3 唯一真正稀缺的东西：上下文窗口

如果这本书只能留下一句话，那就是这句：

Claude 的上下文窗口会很快被填满，而填得越满，表现越差。

这是官方最佳实践页开篇给出的统一约束，后面几乎所有技巧都是它的推论。Anthropic 的工程博客把上下文称作一份”注意力预算”——目标不是塞进去尽可能多的信息，而是用尽可能少的高信号 token 达成目标。

理解这一点，前面那三个恼人现象就都有解释了：

第 5 章会专门讲怎么管这份预算。这里只需要先接受一个反直觉的结论：一个干净的新会话加一句更好的提示，几乎总是胜过一个积累了十轮纠正的老会话。

1.4 现实一点：它能帮你多少，取决于你怎么用

网上关于 AI 编程工具的说法两极分化，有必要在开始之前把已知的证据摆清楚。

METR 在 2025 年 7 月发布过一项随机对照实验：16 位资深开源开发者，在他们自己平均维护了约五年的仓库里完成 246 个真实任务。结果是，允许使用 AI 工具时，他们平均慢了 19%。更值得注意的是感知偏差——他们事前预期会加速 24%，事后仍然认为自己加速了 20%。

这个结果需要如实地看待它的边界：样本只有 16 人，全部是成熟仓库上的资深维护者，用的是 2025 年初的工具（Cursor 配 Claude 3.5/3.7 Sonnet），并不是 Claude Code。研究作者本人明确说过，这不能推广成”AI 对多数开发者无效”。

另一侧的证据方向相反但同样有保留。2025 年 DORA 报告调查了约 5000 名从业者，发现 AI 使用与交付吞吐量、产品表现正相关，却与交付稳定性负相关；同时有 30% 的人对 AI 生成的代码信任度很低。这是相关性而非因果。2025 年 Stack Overflow 开发者调查则量化了日常痛点：66% 的受访者抱怨”几乎对但不完全对”的方案，45% 说调试 AI 生成的代码比预期更久。

把三份证据放在一起，能读出的不是”有用还是没用”，而是一个更有操作性的结论：

• 它在你不熟悉的代码里做探索和定位时，收益最大；
• 它在你极其熟悉的代码里做小改动时，管理成本可能高于收益；
• 它最大的风险不是写出明显错误的代码，而是写出局部正确、整体不一致的代码——这正是”几乎对但不完全对”的来源；
• 因此，验证机制不是可选项。

有一个流传很广的比喻很贴切：把它的产出当成一位过度自信的初级开发者交上来的 PR。你不会不看就合并，但你也不会因为对方是初级就不让他干活。

1.5 什么时候该用，什么时候不该用

官方文档里有一条很实用的判断：如果你能用一句话说清楚这个 diff 长什么样，那就别走复杂流程，直接说、直接改。

1.6 本章练习与检查点

你现在的成果：你有了一个判断标准——不是”这个任务难不难”，而是”这个任务有没有可验证的完成标志”。这个标准会贯穿全书。