how-claude-code-works：把 50 萬行 TypeScript 拆成 21 章閱讀路線
Deep dive into Claude Code internals — architecture, agent loop, context engineering, and more. / 深入解析 Claude Code 源码：架构、Agent 循环、上下文工程、工具系统等
秒懂
- 它是什麼？
- 這是一份針對 Claude Code 內部架構的第三方逆向分析筆記，不是可安裝的函式庫。它的價值在於把一個生產級 Coding Agent 的設計決策寫成可讀的專題文件，而它的風險在於所有結論都來自作者自行推理，專案本身也明確聲明不代表 Anthropic 官方設計。
- 適合誰用？
- 如果你要自己寫一個 Coding Agent，或需要向團隊解釋 Claude Code 為什麼在長對話、危險命令、多工具並發這幾件事上表現得像個系統而不是 demo，這份文件集值得從第 2 章「系統主迴圈」與第 11 章「權限與安全」開始讀。如果你要的是可 import 的函式庫、可重現的效能基準，或想拿它當 Anthropic 官方文件的替代品，那它不適合，README 自己就寫明內容是獨立研究與推理。
- 可以商用嗎？
- 可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 30 天前。
- 用什麼語言寫的？
- GitHub 沒有提供這個儲存庫的主要語言。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
一份沒有安裝步驟的專案，要先搞清楚它在賣什麼
這個 repo 沒有 package.json 之外的執行入口可以談，因為它本質上不是軟體，而是一組文件。README 開頭就把它定位成「Claude Code 架構學習筆記」，並在免責聲明裡寫明：所有內容均為獨立研究與推理，不代表 Anthropic 官方設計，也不保證與真實內部實現一致。它同時聲明不對外分發任何來自 Anthropic 的原始碼。
它要解決的問題很具體。作者說這份 50 萬行 TypeScript 的原始碼以快照形式在社群流出，問題是「從哪裡開始讀」。他們的解法是邊讀邊讓 Claude Code 幫忙產出文件，再把過程文件化。所以這份專案的產出物是閱讀路線，不是程式。
適用對象因此被切得很窄。想自建 AI Agent 的開發者、想理解 Claude Code 行為邊界的重度使用者、需要向同事解釋 agentic coding 系統如何運作的人，是主要讀者。想找現成框架來接進自己產品的人，這裡沒有東西可以裝。README 另外指向一個配套專案 claude-code-from-scratch，約 4300 行 TypeScript 與 Python 兩個版本、13 章分步教學，並自稱是 clean-room 教育實作。那才是可以動手改的東西。
主迴圈、工具預執行與 Continue Sites：第 2 章到底在講什麼
README 的架構圖把資料流畫得很清楚。使用者輸入先進 QueryEngine 做會話管理，接著進入 query 主迴圈，呼叫 Claude API，解析回應。解析結果分兩條路：純文字走串流輸出，工具呼叫則進到工具執行引擎，由讀檔、編輯、Shell、搜尋、MCP 等工具處理，結果再回注主迴圈。上下文工程與權限系統是兩條橫向切進主迴圈的力量。
文件目錄把這一塊拆成第 2 章「系統主迴圈」，列出四個主題：Agent 迴圈的雙層架構、7 種 Continue Sites 故障恢復、工具預執行、StreamingToolExecutor 並發機制。README 對工具預執行的描述是：模型還在輸出時，系統就開始解析並執行工具呼叫，利用模型生成的那段時間把工具延遲藏起來。這是一個設計取捨，代價是系統必須處理「工具已經跑了但模型後來改變主意」的情況，而這類補償邏輯通常就是 Continue Sites 存在的原因。
Continue Sites 這個詞值得留意。README 說整個 Agent 迴圈有 7 種不同的「繼續」策略，每種對應一種故障恢復路徑，並舉了兩個例子：對話超過上下文窗口時悄悄壓縮後重試，token 輸出達到上限時從 8K 升級到 64K 再重試。這種做法的結果是使用者很少看到錯誤，因為大部分錯誤被內部消化掉了。反面則是除錯困難：當行為不如預期時，你沒有錯誤訊息可以追。
四級壓縮流水線：上下文工程裡最細的一處設計
第 3 章「上下文工程」處理的是長對話問題。README 描述的機制是四級漸進式壓縮，每一級都可能釋放出足夠空間，讓後面的級別不需要執行。順序是：先裁剪歷史訊息中的大塊內容，也就是舊的工具輸出；再去重，作者稱這一步幾乎零成本；接著折疊不活躍的對話段落，但不修改原始內容，因此可以展開恢復；最後才是摘要，啟動一個子 Agent 對整段對話做摘要。
摘要被放在最後一級是有道理的。前三個層級都是可逆或低成本的結構操作，摘要則會產生不可逆的資訊損失。把最貴、最不可逆的手段留到最後，是壓縮設計裡少見的克制。
壓縮之後還有一個補救動作：系統會自動恢復最近編輯的 5 個檔案內容，防止模型忘記自己剛剛在改什麼。README 在第 3 章的條目裡把這個機制寫成「5 檔案 + 技能重激活」，並提到提示詞快取策略與快取斷裂檢測。快取斷裂檢測這部分在 README 中只有標題層級的資訊，沒有展開，如果你要靠它估算成本，得自己進文件看。
七層防禦與 tree-sitter：安全章節的技術含量集中在哪裡
第 11 章「權限與安全」是整份文件裡最具體的一章。README 列出七層：工作區信任、權限模式、規則匹配、Bash 命令深度分析、工具級安全、沙箱與隔離、使用者確認。任何一層攔住就不執行。
其中第四層是重點。README 說它用語法樹分析而不是正則匹配來拆解 Shell 命令的真實意圖，包含 23 項靜態安全檢查，覆蓋命令注入、環境變數洩露、特殊字元攻擊。文件目錄則把工具鏈指名為 tree-sitter AST 分析。這個選擇的差別在於：正則比對命令字串很容易被引號、變數展開、管道組合繞過，而解析成語法樹之後，比對的是命令的結構意圖。代價是要維護一份 Shell 語法的解析器，並且在遇到不支援的語法時需要保守處理。
第一層工作區信任也值得單獨看。README 說首次進入一個目錄要先確認信任，不信任就禁用該專案的所有自訂 Hook，理由是擋住惡意倉庫預埋腳本。這是一個明確的攻擊面判斷：真正的風險不在命令本身，而在 repo 帶進來的自動化設定。第七層使用者確認則提到與 Hook、LLM 分類器競速，並有 200ms 防抖保護，使用者一旦操作則人類意圖優先。
工具介面統一與 100K 落盤：並發控制怎麼被藏起來
README 對工具系統的說法是：所有工具，包含第三方 MCP 工具，都遵循同一套介面規範。這句話的實際後果有三個。第一，第三方工具和內建工具走完全相同的執行流水線，因此享受同樣的安全檢查與權限控制，不會出現繞過路徑。第二，唯讀工具自動並行執行，寫操作自動串行，開發者不需要手動管理並發。第三，工具輸出超過 100K 字元時自動落盤，模型只拿到摘要與檔案路徑，需要時再讀全文。
第三點是上下文預算的直接手段。工具輸出是上下文膨脹最快的來源，把大輸出擋在模型之外，等於把壓縮流水線的壓力往前移了一層。
第 4 章另外涵蓋 MCP 的六種傳輸、連接狀態機，以及 OAuth 2.0 加 PKCE 認證流程。這部分在 README 裡只有條目層級的資訊，沒有展開細節。如果你的工作涉及接 MCP server，這章是唯一提到認證流程的地方，但別期待 README 能回答實作問題。
多 Agent 的三種模式與 Worktree 隔離的實際代價
第 7 章描述三種多 Agent 模式。子 Agent 是主 Agent 分派任務後等結果。協調器是純指揮官模式，README 特別強調協調器只能分配任務，不能自己讀檔或寫程式，用能力限制強制分工。Swarm 則是多個具名 Agent 之間點對點通訊，各自獨立工作。
檔案衝突的解法是 Git Worktree，每個 Agent 拿到一份獨立的程式副本。這個方案乾淨，但代價明確：每個 Agent 一份工作區意味著磁碟佔用與環境初始化成本隨 Agent 數量線性成長。文件目錄提到 Swarm 有三種執行後端與信箱通訊，但 README 沒有說明這三種後端的差異，也沒有說明信箱的訊息排序或投遞保證。
第 15 章「任務管理系統」補上了另一塊：檔案級儲存與並發鎖、三層變更檢測、依賴追蹤與原子認領。這些機制在單 Agent 情境下幾乎不會被注意到，但一旦多個 Agent 同時認領任務，原子性就是能不能用的分界線。
快照之後的章節，與那些不能當成事實的段落
README 有一段標註日期的說明：2026.7.4，距離三月底的原始碼洩露事件，Claude Code 又更新了許多功能，尤其是 /goal 與 /loop 組成的 loop engineering，以及以 dynamic workflow 為代表的新編排、觀測與干預方法。作者說他們近期在持續逆向解析這些新功能。
這造成文件內部的證據等級不一致。第 1 到 16 章建立在原始碼快照之上，第 17 章之後標記為「快照之後·黑盒逆向」。第 17 章講 /goal 與 /loop，描述兩種自治範式：守門評估器與自排程鬧鐘，並提到 /goal 評估器的完整系統提示詞、impossible 死迴圈的剎車機制、/loop 的解析規則與 cron、ScheduleWakeup 三條執行路徑。第 18 章「Auto Mode」則標記為「快照之後·源碼+抓包」，講權限從規則加確認框進化到 ML 分類器逐動作裁決、四個自然語言規則桶、兩段式粗篩到細判。
第 17 章文末附了可複現的逆向方法：靜態字串與明文反代抓包。這是整份文件裡少見的、把方法論一起交出來的地方，也是判斷可信度的依據。凡是没有附上這類驗證路徑的章節，讀的時候就該把它當成假設而不是結論。
另一個限制在 README 開頭就寫死了：專案與 Anthropic 無關，內容不代表官方設計，也不保證與真實內部實現一致。這不是免責樣板，而是使用這份文件時必須一直放在心上的前提。
授權、維護成本，以及該不該把它放進你的閱讀清單
授權是 MIT，repo 內有 LICENSE 檔案。對文件型專案來說，MIT 意味著你可以摘錄、改寫、放進內部教材，只要保留授權聲明。但要注意兩件事：授權只覆蓋這個 repo 自己產出的文字與圖表，不覆蓋它描述的 Claude Code 本身，也不覆蓋 Anthropic 的商標。README 明確寫了 Claude Code 是 Anthropic 的商標。
維護成本要看你追得多深。最後推送時間是 2026-08-17，沒有發布任何 release，也就是沒有版本號可以鎖定。作者說會持續更新，這對讀者是好事，卻也意味著你無法引用「v1.2 的第 3 章」來固定說法，只能引用 commit 或日期。如果你的團隊要把這份文件當成內部訓練教材，得自己決定多久同步一次，以及要如何處理章節內容被改寫的情況。
替代方案不是另一個 repo，而是直接讀原始碼或讀官方文件。差別在於：官方文件描述的是 Claude Code 對外的行為與設定，不會解釋內部為什麼用 tree-sitter 而不是正則，也不會告訴你壓縮為什麼分成四級。這個專案填的正是那塊空白。反過來說，當你需要的是可引用的規格或穩定的 API 說明，這份逆向筆記不該被當成依據。它的正確用法是幫你建立假設，然後由你自己去驗證。
編輯結論
如果你要自己寫一個 Coding Agent，或需要向團隊解釋 Claude Code 為什麼在長對話、危險命令、多工具並發這幾件事上表現得像個系統而不是 demo，這份文件集值得從第 2 章「系統主迴圈」與第 11 章「權限與安全」開始讀。如果你要的是可 import 的函式庫、可重現的效能基準，或想拿它當 Anthropic 官方文件的替代品，那它不適合，README 自己就寫明內容是獨立研究與推理。動手前先確認三件事：線上文件站與 repo 內 docs 目錄是否同步、你要讀的章節是否標記為快照之後的黑盒逆向、以及那個章節的結論有沒有附上可複現的驗證方法。這三點決定你讀到的是分析還是猜測。
社群筆記