claude-code-from-scratch：用五千行讀懂 coding agent 的骨架
Build your own Claude Code from scratch. 🔍 Claude Code 开源了 50 万行代码，读不动？用 ~5000 行 TypeScript / Python 从零复现核心架构，11 章分步教程带你理解 coding agent 精髓
秒懂
- 它是什麼？
- 這個專案不是拿來用的工具，而是一份分步教程：用約 5000 行 TypeScript 與 Python 重寫 Claude Code 的核心架構，13 章逐層拆解 Agent Loop、工具系統與上下文壓縮。判斷重點在於它是教材而非產品，讀者要的是機制理解，不是拿它上線。
- 適合誰用？
- 這個專案適合已經會寫 TypeScript 或 Python、想搞清楚 coding agent 內部怎麼運作、又不願啃幾十萬行原始碼的工程師；也適合要把 agent 機制講給團隊聽的人。它不適合想找一個能直接投入生產的 coding agent 的讀者，README 自己也把它定位成學習專案，並聲明不保證與 Claude Code 真實內部實作一致。
- 可以商用嗎？
- 可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 69 天前。
- 用什麼語言寫的？
- 主要是 Python（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
它解決的是讀不動原始碼，不是缺一個 agent
專案開頭直接把痛點寫出來：Claude Code 有幾十萬行，讀不動。它給的答案是另一條路徑，用約 5000 行、TypeScript 與 Python 各寫一份，從零重現核心，再配上 13 章分步教程。所以它的產出物是理解，不是可交付的執行檔。
目標讀者相當明確。一種是想知道 agent loop 到底怎麼轉、工具怎麼被呼叫、上下文滿了怎麼辦的工程師。另一種是要向別人解釋這套機制的人。README 反覆強調這不是 demo，是分步教程，兩者差別在於 demo 只要能跑，教程必須每一步都說清楚為什麼這樣寫、和 Claude Code 的差異在哪。
這裡有個容易誤解的地方。專案名稱裡有 Claude Code，但它和 Anthropic 沒有關聯，README 的聲明段落寫得很直白：照著公開可觀察行為與通用 Agent 寫法來做，不保證和真實內部實作一致。把它當成逆向工程結果來讀，會失望；當成一份有對照視角的架構教材來讀，才對得上。
Agent Loop 是骨架，其餘十二章都是掛上去的
第 1 章的核心循環只有三步：呼叫 LLM、執行工具、重複。整個專案的其餘部分都建立在這個循環之上，這也是為什麼章節順序不能跳。工具系統決定循環裡能執行什麼，System Prompt 決定模型怎麼被引導，上下文管理決定循環能撐多久。
從 README 的架構對照表可以看出設計者的組織方式：每一章都標明自己的檔案對應 Claude Code 的哪個模組。比如 agent.ts 對 query.ts，tools.ts 對 Tool.ts 加上 66 個工具，prompt.ts 對 prompts.ts。這種對照不是裝飾，它讓讀者知道真實專案把同一件事拆成了多大的規模，也讓「為什麼這裡只有 13 個工具」這類問題有答案。
工具層有幾個具體機制值得注意。mtime 防護用來避免檔案在讀取後被外部改動卻仍照舊寫回，延遲載入則處理工具數量增長後的初始化成本。第 5 章提到流式工具執行與並行執行，這兩件事在真實 agent 裡直接影響體感延遲。第 7 章把上下文壓縮拆成 4 層，並把過大的工具結果持久化到磁碟而非留在對話裡。這些都是實際會撞到的問題，不是為了章節完整而湊的題目。
不用 API key 就能跑，是這份教程最實用的設計
讀原始碼最常見的失敗模式是讀不懂又跑不起來，改一行也不知道對不對。專案對此的處理方式是每個程式碼章節都附一份可單獨執行的最小實作，由本地 mock 模型驅動，不連網。
指令集中在一個入口：
node steps/run.mjs --list node steps/run.mjs 7 node steps/run.mjs 7 --diff node steps/run.mjs 7 --py
--list 列出所有能跑的章節，數字參數指定章節，--diff 只顯示這一章比上一章新增的那幾行，--py 切換到 Python 版本。以第 7 章為例，README 描述它跑出來的現象是對話變長後把舊訊息壓成摘要。要接真模型時加 --live。
README 特別說明，每章的程式碼、文件裡貼的程式碼區塊、以及執行輸出，全部由同一份原始碼生成。這一點比功能本身更重要：教材最怕的就是文件與程式碼不同步，一旦出現，讀者會開始懷疑每一個範例。用生成方式綁定三者，等於從流程上排除了這種漂移。
完整安裝走另一條路。TypeScript 版是 git clone 之後 npm install && npm run build，Python 版需要 Python 3.11+，進到 python 目錄後 pip install -e .，命令列入口是 mini-claude-py，也可用 python -m mini_claude。
雙後端與環境變數：接真模型時要決定的幾件事
專案支援兩種後端，靠環境變數自動辨識。Anthropic 格式用 ANTHROPIC_API_KEY，可選 ANTHROPIC_BASE_URL 指向代理。OpenAI 相容格式用 OPENAI_API_KEY 與 OPENAI_BASE_URL。README 標注兩種都支援自訂 base url。
模型預設是 claude-opus-4-6，有兩條覆寫路徑：環境變數 MINI_CLAUDE_MODEL，或命令列參數，後者優先級更高。
執行模式用旗標控制，兩個語言版本選項一致：--resume 恢復上次會話，--yolo 跳過安全確認，--plan 只分析不修改，--accept-edits 自動批准檔案編輯，--dont-ask 是 CI 模式、需確認的操作自動拒絕，--max-cost 設費用上限，--max-turns 設輪次上限。
這裡有個值得留意的設計取向：--yolo 讓危險命令自動執行，README 直接把它標為危險。在教學專案裡這合理，因為讀者要觀察未經打斷的完整循環。但同一組旗標也出現在可安裝的命令列工具上，如果你把它 npm link 或 pip install -e . 之後帶進真實專案目錄，這些旗標的風險就跟教材無關了。
REPL 內建幾個指令：/clear 清空歷史，/cost 顯示累計 token 與費用估算，/compact 手動觸發壓縮，/memory 列出已保存的記憶，/skills 列出可用技能，/<skill> 呼叫已註冊技能例如 /commit。
五千行是刻意的上限，也是它的天花板
限制要從規模本身看。約 5000 行要覆蓋 Agent Loop、13 個工具、4 層壓縮、語意記憶召回、技能系統、多 Agent、MCP 整合，每一塊分到的行數必然很薄。README 的對照表其實自己說明了落差：tools.ts 對應的是 Tool.ts 加上 66 個工具，permissions 那一欄對應 Claude Code 的 permissions 目錄 52KB。教學實作在權限這一塊的深度，和真實專案不在同一個量級。
第 6 章列出 5 種權限模式、宣告式規則與危險檢測。對理解機制足夠，對真實防護不足。宣告式規則的表達力、規則衝突時的優先順序、以及繞過路徑的處理，這些在 52KB 的實作裡才展開得開。
另一個要自己判斷的點是驗證方式。第 14 章標題是功能測試，README 寫的是 22 項手動測試覆蓋全部功能。手動測試對教材合理，因為讀者要親眼看到行為；但它不構成回歸保護，你改動程式碼之後，沒有任何自動機制會告訴你哪裡壞了。
還有一個結構性限制：教程照的是 Claude Code 的公開可觀察行為。凡是無法從外部觀察到的內部決策，這裡只能給出通用寫法。README 的聲明把這一點講明白了，讀的時候要記得區分「這是 Claude Code 的做法」和「這是一個合理的做法」。
和直接讀原始碼或直接使用 agent 的差別
第一種替代做法是直接讀 Claude Code 的原始碼。差別在於入口：讀原始碼從真實複雜度開始，先撞上模組邊界、抽象層與歷史包袱，好處是看到的是真的。這個專案反過來，先給一個能完整運轉的最小模型，再逐章指出真實專案在哪裡變複雜。對還沒建立心智模型的人，後者起步成本低得多。
第二種替代做法是直接用現成的 coding agent，把它當黑盒。這條路對交付最有效率，但你無法判斷它為什麼在某些情境下失敗，也無法在它的行為不符預期時給出有依據的調整。
還有一個姊妹專案值得一起看：how-claude-code-works。README 描述它是 12 篇專題、33 萬字，從原始碼級別解析 Claude Code 架構。兩者的分工很清楚，一個從零往上寫出最小實作，一個從原始碼往下拆解真實系統。想同時拿到兩側視角的人，這個組合比單看任一個完整。
至於和其他教學專案的比較，我手上沒有可驗證的資料，不做評斷。
維護成本、授權與版本狀態
授權是 MIT，README 與 badge 都標明，LICENSE 檔案在倉庫根目錄。MIT 允許商用與修改，實務上要注意的是名稱：README 聲明 Claude Code 是 Anthropic 的商標，本專案與 Anthropic 無關聯。把衍生作品對外發布時，名稱與商標的處理需要自己判斷，這不是授權條款能回答的問題，也不是本文能給的法律意見。
版本方面，最近的 release 是 v1.0.0，時間為 2026-03-31；倉庫最後一次推送是 2026-07-09，未歸檔。這意味著 v1.0.0 之後仍有持續提交，但沒有對應的新版本標籤。要跟進變動，看提交歷史比看 release 頁面可靠。
維護成本的結構值得說清楚。教程類專案的成本主要在內容同步：一旦上游 Claude Code 的架構有明顯變化，對照表與章節說明就會過時。這個專案用同一份原始碼生成程式碼、文件區塊與執行輸出，降低了內部不一致的風險，但無法解決與外部真實專案之間的落差。
如果你打算把它的程式碼當自己專案的起點，要接受的是：它的價值在於結構清晰，不在於功能完整。13 個工具與 5 種權限模式覆蓋的是常見路徑，你要補的部分，README 並沒有假裝已經做完。
編輯結論
這個專案適合已經會寫 TypeScript 或 Python、想搞清楚 coding agent 內部怎麼運作、又不願啃幾十萬行原始碼的工程師；也適合要把 agent 機制講給團隊聽的人。它不適合想找一個能直接投入生產的 coding agent 的讀者，README 自己也把它定位成學習專案，並聲明不保證與 Claude Code 真實內部實作一致。動手之前先確認三件事：本機是否具備 Node 與 Python 3.11+ 環境、你打算用 Anthropic 格式還是 OpenAI 相容格式的後端、以及你能否接受 13 章內容對應的是教學用的最小實作而非完整功能。先跑 node steps/run.mjs --list 看有哪些章節能離線執行，再決定要不要接上自己的 API key。
社群筆記