我为什么把 AI 编程教程写成长文分章

我在教程站上放了两份中文长教程，一份讲 Claude Code，一份讲 Codex CLI，加起来二十二章。有人问我为什么不切成三十篇短文发出去——那样流量明显更好看。这篇文章就是回答。

中文 AI 编程内容的三种失败方式

过去一年我为了自己用好这两个工具，读了大量中文材料，失败模式高度集中在三类。

第一类是碎片化。一篇讲 /clear，一篇讲 CLAUDE.md，一篇讲权限模式，每篇都对，但读者拼不出一条完整的工作流。工具类知识的价值恰恰在结构里：知道 /clear 这个命令没用，知道”同一个问题纠正两次仍未解决就该清空重开”才有用，而后者必须建立在你已经理解上下文是怎么被消耗的之上。

第二类是翻译官方文档。把参数表照抄一遍，读者读完仍然不知道该选哪一档。文档回答”有哪些选项”，教程要回答”我这种情况该选什么，选错了会怎样”。这两件事的写法完全不同。

第三类是跑不通。截图是半年前的界面，命令是已经改名的参数，作者自己没有在真实仓库里从头走一遍。AI 编程工具的发版节奏很快，这个问题只会更严重——所以我在教程里刻意不写死版本号，也不抄价格数字，遇到对不上的命令，第一反应应该是在会话里敲 /help。

分章推进是为了让读者能停下来

长文分章不是把长文切开，是按课程编排。

每一章有一个明确的能力目标，章与章之间有依赖顺序。《Claude Code 上手指南》的前六章是一条不能打乱的链：先建立”它不是补全工具”的心智模型，再跑通环境，然后依次处理把话说清楚、划出权限边界、管住上下文、走完主循环这四件日常事。第七章之后才是按需取用的部分——团队规则、MCP、CI、成本、安全。

这个结构的好处是读者可以合法地停在任何一章。读完第四章就去用，是完整的；读完全部十二章再用，只是更完整。碎片化文章做不到这一点，因为你不知道自己缺的是哪一块。

每章的固定骨架：目标、正文、练习、检查点

我给每一章都套了同一副骨架，位置固定，读者第三章之后就不用再找了。

开头是本章目标，一句话说清读完能做什么。正文里每个抽象结论后面必须跟一个具体场景——讲权限模型不只列三档沙盒，而是给出四种真实场景各自该配什么组合。结尾是练习和检查点：练习让你在自己的仓库里动手，检查点让你合上页面用自己的话复述一遍。

检查点是我最看重的部分。技术阅读最大的错觉是”看懂了”，而看懂和能复述之间差着一整个理解。比如《上下文是唯一稀缺资源》那一章的检查点只有一句：/clear 和 /compact 在成本上有什么区别，什么情况下该选前者。答不上来，说明这一章白读了——压缩本身是一次很大的请求，清空几乎不花钱，所以任务真的结束时，清空优于压缩。

两篇教程分别适合谁

《Claude Code 上手指南》十二章，适合已经装了 Claude Code、但用了几天觉得”它在真实项目里不靠谱”的人。它的主线是把不可控感拆成可管理的变量：上下文和边界。全书最该慢读的是第 4 章权限模式和第 5 章上下文管理。

《把 Codex 用成队友》十章，适合刚接触 Codex、面对 CLI、IDE、网页、GitHub 等多个入口不知道从哪开始的人。它围绕三个没交代清楚的问题展开：它能动什么、这个项目的规矩是什么、做到什么程度算完成。第 4 章讲沙盒与审批是全篇最重要的一章，它解释了为什么权限要拆成两个正交的旋钮，而不是做成一个从”什么都问”到”什么都别问”的滑块。

两个工具都用的人，我建议先读任意一篇的前四章建立心智模型，另一篇的对应章节会读得非常快——差异主要在命令名和配置文件格式上，底层的约束是同一套。

怎么读，以及为什么不收费

三条具体建议。一，开着终端读，每章的练习当场做，不要攒到最后；二，前四章按顺序，不要跳；三，读到检查点合上页面，答不上来就退回去重读那一节，这比往下赶有用得多。

至于免费：这些内容的保质期本来就短，工具每次大改我都要回去修一遍，收费会让我在”该不该重写这一章”上产生本不该有的犹豫。而且我写它们的最初动机是给自己整理，公开只是顺手。如果它帮你省下了一个下午，那已经够了。

如果读完发现某处和你实际看到的行为对不上，直接告诉我，我改。教程页脚有联系方式。