ai-coding-guide：把 Claude Code 和 Codex 的官方文档翻成中文，值不值得照着跑
「可能是全网最全的」📘 面向小白的 AI 编程 CLI 中文教程：Claude Code + Codex 92 篇精修
秒懂
- 它是什么？
- 这是一套 92 篇、约 52 万字的中文教程仓库，主力是 Codex 39 篇，另留 Claude Code 53 篇。它的价值不在观点，而在于把官方文档里的命令、配置和默认行为整理成中文可照抄的形式，代价是教程本身不提供任何代码或可运行工具。
- 适合谁用？
- 适合两类人：英文官方文档读起来吃力的中文开发者，以及刚接触 CLI 型编程助手、需要一份能照着敲的入门路径的人。不适合已经在用 Claude Code 或 Codex 做日常开发的人，因为教程覆盖的是文档里已写明的功能，不会给出官方之外的工程结论，也不提供任何可复用的代码或脚手架。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 13 天前。
- 用什么语言写的？
- GitHub 没有给出这个仓库的主要语言。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
它解决的是阅读成本，不是技术问题
Claude Code 和 Codex 的官方文档都是英文优先，命令、配置键、默认行为散落在多个页面里。对一个刚开始用命令行的中文开发者来说，真正的门槛不是理解 agent 循环是什么，而是搞清楚装完之后第一条命令该敲什么、配置文件放在哪个路径、报错时该去哪个页面查。这个仓库针对的就是这段距离。README 写明它的定位是「面向小白的 AI 编程 CLI 中文教程」，并且给出了明确的篇幅：92 篇、约 52 万字，其中 Codex 39 篇、Claude Code 53 篇。
它的读者画像是清楚的：0 基础、不熟悉命令行、但愿意跟着步骤动手的人。README 里对写作方式有一句自述，说每个新概念采用「场景引入 + 生活化类比 + 实际场景」的三段式。这个结构对没有编程背景的读者是友好的，代价是信息密度被摊薄，有经验的开发者读起来会觉得绕。
需要说清楚的是，这个仓库不产出任何工具。没有 CLI，没有脚手架，没有可 import 的库。它是一堆 Markdown 加 81 张 SVG/PNG 配图，真正的阅读入口是 coding.stormzhang.ai 这个站点。把仓库 clone 下来直接看文件，得到的体验和看网页版并不一样。
92 篇是怎么排的：两条线，一条主线一条备用线
目录分成两块。Codex 篇 39 篇被 README 标为「主力推荐」，Claude Code 篇 53 篇保留但退到次要位置。这个排序本身透露了一个判断：作者认为新读者应该从 Codex 入手。
两条线的结构大体平行。Claude Code 篇从「是什么 / 安装」起步，依次经过 API 配置、第三方模型接入、订阅计费、第一次跑通，然后进入 IDE 集成、项目初始化、上下文管理、权限配置、MCP、子代理、Skill、Hooks、Agent SDK、GitHub Actions，最后收在最佳实践、反模式、FAQ 和术语表。Codex 篇的目录里能看到四种入口、AGENTS.md、沙箱审批、config.toml、Chronicle 记忆、Worktrees，以及一篇专门讲「从 Claude Code 迁移」。
这个排法有一个实际好处：两边的概念可以对照着看。同一个功能，Claude Code 叫 Skill，Codex 那边对应的是什么，迁移篇应该会讲。对同时评估两个工具的人来说，这种平行目录比单看一边的官方文档更容易建立整体印象。
但目录里也有明显的选读和边角内容。比如 Claude Code 第 53 篇是「制作视频（Remotion）」，README 直接标了〔选读〕。这类篇目对多数读者是噪音，翻目录时要自己筛。
没有 releases，也没有安装命令
这个仓库没有发布过任何 release。它是文档仓库，这一点决定了「怎么用」的答案很朴素：没有 npm install，没有 pip，没有二进制包。README 给出的唯一入口是网址 https://coding.stormzhang.ai，以及仓库里的 Markdown 文件。
如果你确实想离线看，做法是 clone 仓库然后读 Markdown。README 里提到仓库包含 81 张 SVG/PNG 配图，统一暗色风格。这意味着纯 Markdown 阅读器里图片路径能否正确解析，取决于你的工具怎么处理相对路径，这一点材料里没有说明，需要自己试。
教程正文里出现的命令和配置键，是这个仓库唯一带有技术细节的部分。从目录标题能确认会涉及的具体对象包括：Claude Code 的 /init 命令、CLAUDE.md、settings.json、Hooks、Slash Commands、Checkpoints、环境变量；Codex 的 AGENTS.md、config.toml、沙箱审批机制、Worktrees。这些都是各自官方文档里真实存在的概念，教程的作用是给它们配上中文说明和操作顺序，而不是发明新的用法。
所以评估这个仓库的正确姿势，不是问「它能不能帮我装好 Codex」，而是问「它把官方文档里哪几段话翻译并重排了，重排之后是不是更好读」。
「以官方文档为事实来源」这句话的分量
README 在差异说明里写得很直接：所有功能、命令、默认行为都对照 Codex 官方和 Claude Code 官方核实，不抄第三方猜测、不靠传言。它还提到每篇有 3 处以上第一人称的踩坑或判断，带具体细节和数字。
这两条放在一起看，是这份教程最值得肯定也最需要警惕的地方。值得肯定，是因为 AI 编程工具迭代快，第三方博客里的命令经常过时，把官方文档作为唯一事实来源能减少错误传播。需要警惕，是因为「对照官方核实」这句话本身无法从仓库材料里验证。我手里只有 README 和目录，看不到正文，也就无法判断某篇的具体命令是否和当前版本的官方文档一致。
同样无法验证的是「第一人称踩坑」的密度。这是一个写作承诺，不是可检查的属性。读者能做的实际检查是：挑一篇你最关心的，比如 Codex 篇第 03 篇「安装与登录（Mac / Windows / Linux）」，打开读一遍，看里面的命令和官方文档当前版本是否对得上。这一步花不了几分钟，但能决定你还要不要继续读剩下的 91 篇。
另外要注意版本时效。仓库最后一次 push 是 2026-09-02，这个时间点之后 Claude Code 和 Codex 如果发布了破坏性变更，教程不会自动跟进。文档仓库的维护成本主要就体现在这里。
它教不会你的东西：真实项目里的判断
教程能覆盖的是「这个功能是什么、怎么开、命令怎么写」。覆盖不了的是「这个功能在你的项目里该不该开」。
举个具体的例子。Claude Code 篇里有「权限配置：放多松、收多紧，你说了算」和「安全与风险边界」，Codex 篇里有「沙箱审批」。这几篇会告诉你怎么配置，但放多松是工程判断，取决于你的代码库敏感程度、团队规范、以及你愿意让 agent 直接改文件到什么程度。教程给不出这个答案，也不该指望它给。
再比如上下文管理。Claude Code 篇第 19 篇讲「别让它失忆也别烧爆 token」，这类内容通常是讲机制和常见操作，比如什么时候该清上下文、什么时候该开新会话。但具体到你的项目，一个会话能装下多少文件、什么时候该拆成子代理，只有实际跑过才知道。
还有一类情况是教程结构本身造成的：目录里同时有「最佳实践」和「反模式」两篇，位置在很靠后。对小白读者来说，先读完几十篇功能说明再看到反模式，成本偏高。更合理的读法也许是先看反模式和 FAQ，再回头按需查功能篇。这个顺序教程没有提供，需要读者自己调整。
和官方文档、通用 AI 编程书比，差在哪
最直接的替代品就是官方文档本身，也就是 README 里引用的 developers.openai.com/codex 和 code.claude.com/docs/zh-CN。差别在语言和编排。官方文档按功能模块组织，适合查；这份教程按学习顺序组织，适合从头读。值得注意的是 Claude Code 官方文档已经有中文版本，路径里带 /zh-CN，所以对 Claude Code 这一半来说，教程的「中文」优势要打折扣，真正的差异只剩改写方式和阅读节奏。Codex 官方文档的语种情况材料里没有说明，不做判断。
另一类替代品是通用的 AI 编程书或视频课。这类内容通常覆盖面更广，会讲提示词技巧、模型选型、团队协作流程，但具体到某个 CLI 的命令和配置键，往往不如官方文档准确，更新也更慢。这个仓库的定位介于两者之间：只讲这两个工具，只讲文档里有的东西，但用中文重讲一遍。
如果只想要一份速查表，官方文档的搜索框比 92 篇文章更快。如果想理解 agent 循环、子代理、MCP 这些概念之间的关系，教程的顺序编排有优势，尤其是 Codex 篇里那篇「从 Claude Code 迁移」，这种对照视角官方文档不会提供。
MIT 许可证意味着什么，以及维护成本怎么算
仓库采用 MIT 许可证，LICENSE 文件在根目录。按 MIT 的通常条款，你可以复制、修改、分发这些内容，包括商用，条件是保留版权声明和许可声明。具体到把教程内容搬进公司内部知识库、或者改写成培训材料，MIT 本身不禁止，但要注意仓库里的 81 张配图是否全部由作者原创，材料里没有逐一说明图片来源，这部分需要自行确认。以上是许可证文本层面的描述，不构成法律意见。
维护成本方面，这个仓库的形态决定了它不会给你带来依赖负担。没有包管理器，没有需要定期升级的依赖，不会有安全公告。你 clone 下来之后，唯一的「升级」动作是 git pull 拉取新的 Markdown。
真正的成本在时效。教程内容绑定 Claude Code 和 Codex 的当前行为，这两个工具都在快速迭代。仓库最后一次 push 是 2026-09-02，从那时起官方文档如果改了默认行为、换了配置键、或者调整了订阅方案，教程里的对应段落就会变成误导。对读者来说，这意味着不能把教程当成长期参考手册，只能当成某个时间点的入门材料。用之前扫一眼 commit 记录，比读完再发现命令跑不通要省事。
编辑结论
适合两类人：英文官方文档读起来吃力的中文开发者，以及刚接触 CLI 型编程助手、需要一份能照着敲的入门路径的人。不适合已经在用 Claude Code 或 Codex 做日常开发的人，因为教程覆盖的是文档里已写明的功能，不会给出官方之外的工程结论，也不提供任何可复用的代码或脚手架。上手前先做三件事：打开 coding.stormzhang.ai 确认站点可访问，因为仓库本身只有 Markdown 和图片；对照 README 里声称的 92 篇目录，检查你关心的那几篇是否真的存在；最后，凡涉及订阅计费、第三方模型接入和权限配置的篇目，以 Codex 官方和 Claude Code 官方文档为准，教程只作为中文索引和阅读顺序的参考。
社区笔记