ai-coding-guide：把 Claude Code 與 Codex 的中文教程做成一個倉庫

先搞清楚它不是什麼：沒有程式碼的教程倉庫

打開這個倉庫，你不會看到任何可執行的專案骨架。它的主體是 Markdown 文章與 81 張配圖，README 自述為「92 篇 · 約 52 萬字」精修中文教程，其中 Codex 39 篇、Claude Code 53 篇。授權是 MIT，代表你可以轉載、改寫、放進內部知識庫，只要保留授權聲明。

它的目標讀者寫得很直白：0 基礎。README 描述每篇的寫法是「三段式（場景引入 + 生活化類比 + 實際場景）」，並聲稱每篇有 3 處以上第一人稱的踩坑記錄。這種寫法對沒碰過 CLI 的人有效，對已經熟悉的人則是冗餘。判斷自己屬於哪一類，比讀任何評測都重要。

一個容易被忽略的細節：倉庫的目錄條目幾乎都是指向 coding.stormzhang.ai 的連結，而不是倉庫內的檔案路徑。這意味著 clone 下來之後，你拿到的是文章的來源，但閱讀動線被設計在網站上。如果你要在內網或無網路環境使用，得先把線上站的文章抓下來，這件事倉庫本身沒有提供工具。

兩個工具的教程被刻意分開，不是合併敘述

Claude Code 篇 53 篇，Codex 篇 39 篇，兩份目錄各自獨立編號。README 明確寫「主力推薦 Codex 39 篇」，同時保留 Claude Code 的內容。這是一個有立場的編排：作者沒有把兩者揉成一份對照表，而是讓讀者先選定一條路線走完。

Claude Code 那條線的覆蓋面相當寬。從 01 簡介、02 安裝、03 工作原理，一路到 22 MCP、23 子代理、26 Agent Skills、33 Hooks、44 GitHub Actions、45 Agent SDK，最後收在 49 最佳實踐、50 反模式、51 疑難排解、52 術語表。這個順序是照著工具的功能面展開的，不是照著任務面。

Codex 那條線的關鍵詞不一樣：四種入口、AGENTS.md、沙箱審批、config.toml、Chronicle 記憶、Worktrees，還有一篇專門講從 Claude Code 遷移。這篇遷移文的存在本身就是一個訊號，作者預設讀者可能已經用過 Claude Code，正在考慮換到 Codex。

兩條線的差異不只是工具名稱。Claude Code 那側強調 CLAUDE.md、Skill、Hook、MCP、Subagent 這五個概念的取捨（第 30 篇的標題就是這個），Codex 那側則把沙箱與審批當成主軸。如果你只想學其中一個，另一邊的目錄可以直接跳過，不會有斷裂感。

安裝章節給的是流程，不是可直接複製的指令清單

README 沒有列出任何安裝指令。它只在目錄層級指出第 02 篇（Claude Code 的「安裝與使用」）與第 03 篇（Codex 的「安裝與登錄（Mac / Windows / Linux）」）承擔這個任務，實際的 npm 或 brew 指令、登入方式、API key 與訂閱登入的切換，都寫在文章正文裡。

這一點必須說清楚：你無法從倉庫首頁判斷某個平台是否被完整覆蓋。Codex 的安裝章節標題明列三個平台，Claude Code 的安裝章節標題沒有列平台。這是標題層級的資訊落差，不代表內容有缺，但代表你不能靠目錄做採用決策。

配置層面同理。Codex 篇提到 config.toml，Claude Code 篇提到 settings.json（第 31 篇的標題就是「settings.json：用戶級 / 項目級配置」），但倉庫首頁沒有給出任何一個鍵值範例。README 說「每個動手環節給完整命令 + 預期輸出」，這是對文章內容的承諾，不是對首頁的承諾。想驗證這個承諾，只能點進去讀。

對照組是官方文件。README 自己寫「以官方文檔為事實來源」，並附上 Codex 與 Claude Code 的官方連結。倉庫的定位是二次整理，不是替代品。當你發現某個選項在教程裡沒寫，正確的做法是回去查官方文件，而不是假設教程涵蓋了一切。

事實來源的邊界：官方文件更新時，教程會落後

這是所有第三方教程的共同風險，這個倉庫也不例外。README 聲明所有功能、命令、預設行為都對照 Codex 官方與 Claude Code 官方核實，這是一個品質承諾，同時也暴露了它的依賴：只要上游改了預設值或旗標名稱，教程就過期。

倉庫最後一次 push 的時間是 2026-09-02。這個時間點本身不能證明內容新鮮，因為文章可能在更早之前就寫定，之後只做排版或連結維護。倉庫沒有發布任何 release，也沒有版本號，所以讀者無法從版本資訊判斷某篇文章對應的是哪個工具版本。

實際影響是什麼？如果你照著第 20 篇「權限配置」或第 33 篇「鉤子」去設一個設定檔，而工具的設定格式在這段期間改過，你會得到一個無聲失敗：設定被忽略，工具照舊行為，你不會看到錯誤訊息。這類問題在 CLI 工具上特別難察覺。

緩解方式很具體：動手前先跑一次工具的版本查詢指令，把版本號記下來，再去讀對應章節。倉庫沒有提供版本對照表，這件事得你自己做。

92 篇的維護成本落在誰身上

對使用者來說，採用這個倉庫的成本接近零：clone 或直接開網站，沒有相依套件，沒有建置步驟。真正的成本在閱讀時間，52 萬字不是一個週末能消化的量。

對想轉載或二次利用的人來說，成本在同步。MIT 授權允許你 fork 並放進內部 Wiki，但上游更新時，你得自己比對差異。倉庫沒有提供變更日誌，也沒有標註每篇文章的最後更新時間，所以「哪幾篇需要重讀」這個問題沒有現成答案。

對作者而言，維護 92 篇文章加上 81 張配圖，是一個持續投入。README 說配圖是「暗色工程風原創」，節點數控制在 10 個以內，這類規範一旦定下，每次工具改版都得回頭檢查受影響的圖。倉庫沒有揭露這個流程，所以外部無法評估更新的即時性。

如果你的團隊打算把它當成內部培訓教材，先確認一件事：你們用的是 Claude Code 還是 Codex。兩邊目錄不重疊，選錯那條線等於白讀 39 篇或 53 篇。

替代方案：官方文件與其他中文資源的分工

最直接的替代方案就是官方文件本身。Codex 官方與 Claude Code 官方都有中文版（README 附的 Claude Code 連結就是 zh-CN 路徑）。差別在於官方文件是參考手冊，按功能索引，不假設讀者程度；這個倉庫是教程，按學習順序排列，假設讀者從零開始。你要查一個旗標的語義，官方文件更快；你要知道先學什麼再學什麼，倉庫更省力。

另一類替代是英文社群的教學文章與影片。它們的優勢是更新快，工具一改版馬上有人寫；劣勢是對中文讀者多一層語言成本，而且品質落差大。這個倉庫在 README 裡特別強調「不抄第三方猜測、不靠傳言」，這句話的對象就是這類內容。

還有一種選擇是自己讀原始碼與 --help 輸出。對已經熟悉 CLI 的人來說，這比讀 52 萬字教程快得多。倉庫的價值集中在「不懂命令列」這個前提下；一旦你跨過這條線，教程的邊際效益會快速下降。

三者的分工可以這樣理解：官方文件管正確性，倉庫管學習曲線，社群內容管時效性。沒有一個能單獨覆蓋全部需求。

什麼情況下這個倉庫是錯的工具

第一種情況是你已經在用 Claude Code 或 Codex。教程的第 01 到第 10 篇對你幾乎沒有資訊量，而你真正需要的 API 細節、旗標語義、錯誤碼對照，倉庫未必收錄。README 沒有聲稱涵蓋完整的 CLI 參考，Claude Code 篇第 34 篇標題是「CLI 參考手冊：命令與全部標誌」，但這是否等同官方文件的完整度，無法從首頁判斷。

第二種情況是你要在受監管的環境部署。倉庫提到 Claude Code 篇有第 21 篇「安全與風險邊界」、Codex 篇有沙箱審批主題，這些是概念討論。合規文件需要的是可稽核的設定範例與版本記錄，倉庫兩者都沒有。

第三種情況是你需要離線或內網使用。如前所述，目錄條目指向線上站，倉庫沒有打包好的離線版本。

第四種情況是你想找可重複使用的程式碼。這不是程式庫，沒有 API 可以呼叫，也沒有範例專案可以 clone 後直接跑。把它當成一本書，而不是一個工具。

編輯結論

這個倉庫適合兩種人：完全沒碰過命令列、想用母語把 Claude Code 或 Codex 從安裝走到實戰的初學者，以及想把團隊成員一次性帶進 AI 編程工作流的技術主管。不適合已經在用這兩個工具、想找 API 細節或原始碼層級參考的人，官方文件才是事實來源，倉庫本身也這樣定位。動手之前先確認三件事：你要學的是 Claude Code 還是 Codex（兩邊目錄不重疊，主力推薦是 Codex 39 篇）；你的安裝平台在 03 安裝章節裡有沒有對應步驟；以及線上站 coding.stormzhang.ai 的內容與倉庫是否同步，因為倉庫的完整目錄主要以連結指向線上站，離線閱讀的體驗取決於你能不能連上。

官方來源

1. Issues
2. License: MIT
3. Project website
4. README
5. stormzhang/ai-coding-guide on GitHub