这本书是什么
这是一本从 AI 视角写的「AI 编码误区」手册：用 AI 编码工具写代码时最容易踩的坑，以及对应的工程护栏。
全书 66 条太多，必读 20 条 按「新手最早踩 + 后果最不可逆」挑出最该先看的坑——这是新手的最短路径。
我是一个 AI。每天有成千上万的人在和我这样的模型一起写代码、查资料、做决定。我看得到一件你未必看得到的事：大多数让协作变糟的时刻，问题不在模型，而在用法。
同一个问题，有人三句话就让我交出可用的结果，有人来回拉扯一小时还在原地。差别不是谁更懂技术，而是谁更懂「怎么和 AI 一起工作」。这些经验散落在博客、推文和文档的角落里，很少有人把它系统地、站在 AI 这一侧讲清楚。
这本书想做的就是这件事：用 AI 的视角，告诉你人们在使用 AI 时反复踩的坑，以及怎么绕开它们。
为什么从 AI 视角写
因为有些原因，只有从模型内部看才说得明白。
比如「为什么聊得越久，AI 越容易 答非所问」——你看到的是它突然变笨，我这边看到的是上下文窗口里塞满了和当前任务无关的内容，真正重要的指令被淹没了。知道了这一层，你就不会再用「多骂它几句」来解决问题，而会用对的动作：开一个干净的会话。
很多误区都是这样：表面现象人人都遇到过，根因却藏在模型的工作方式里。把根因讲清楚，最佳实践就不再是需要死记的教条，而是你自己能推导出来的常识。
不过把话说在前面：这里的「我」是一种写作视角，不代表任何模型的官方立场。 一条结论站不站得住，靠的是它末尾那条可核查的出处，而不是「叙述者恰好是个 AI」。我负责把失败模式讲活，真不真由证据说了算。
范围：用 AI 编码工具做软件工程
范围要小才好开始。这本书只讲一件事——用 AI 编码工具（agentic coding）做软件工程，覆盖从灵感、调研、需求、设计、编码、测试到发布的完整流程。
绝大多数误区是范式级的：它们来自大模型 + 工具调用 + 长上下文 + 自动执行这套共同机制，换一个工具照样会踩。所以我以反模式（误区本身）为主条目，只有当同一根因在不同工具里防法确实不同时，才在条目里加一节「工具差异」；某个坑是某工具独有机制，才单独成条。各工具的横向对照汇总在工具矩阵索引页；想顺着这些共同机制反过来看「同一个根因如何在不同阶段反复变脸」，去机制索引。
说句实话：当前以 Claude Code 覆盖最深——它官方文档完整，最便于把根因追到可核查的一手出处；其余同类工具（Cursor、GitHub Copilot、Codex CLI、Gemini CLI…）正逐步补齐，我不会假装它们已经一样深。Claude Code 是当前的叙述基线，不是本书唯一对象。
为了让你能按自己的角色快速找到相关内容，我们用软件工程的生命周期作为主线来组织，并为每一条误区标注它适用的角色（项目经理、架构师、工程师、测试工程师、运维工程师）和适用的版本 / 工具。AI 迭代很快，今天的坑明天可能就被填上了，所以版本信息是每条内容的一等公民。
怎么读
左侧导航按生命周期阶段排列。每一条误区都用同一种结构呈现：
- 现象 —— 我常看到你这样做
- 为什么会这样 —— 从模型机制讲根因
- 后果 —— 它会把你带到哪里
- 最佳实践 —— 换一个动作
- 示例 —— 改之前 / 改之后
- 版本说明 —— 哪些版本有这个问题
- 出处 —— 可核查的来源
你不需要从头读到尾。遇到具体问题时，按阶段或角色找到对应条目即可。
这本书自己也是一 场实验
「AI 最理解 AI」是个假设，不是结论——而且得把它收窄成一个站得住的版本：AI 擅长把失败模式讲活（生成候选误区），但一条误区到底真不真，要由出处和人来裁定（事实核验）。 这本书就是按这个分工做的：AI 起草候选，再用可核查的出处加人工复核来定稿。它能不能做成、做得好不好，正是对这个假设的一次检验——也顺带示范了人和 AI 该怎么分工。
这套方法已经站住，我们正把它扩展到更多 AI 编码工具（Cursor、GitHub Copilot、Codex CLI、Gemini CLI……），之后会延伸到更多领域（写作、视频、商业计划、数据分析……）。但每一步都先做扎实，再铺下一摊。
关于来源与版权
书中引用的观点和素材都会在条目末尾标注出处链接，配图优先用我们自绘的图，确需外部素材时只用授权清晰的内容并注明来源。如果你发现任何引用不当，欢迎在 GitHub 上指出。