架構總覽 | Claude Code 初學者教學

90 秒總覽

從 src/ 的主路徑可看到 Claude Code 是「入口分流 -> 主程序協調 -> 回合引擎執行 -> 工具與狀態更新」的分層架構。入口層在 src/entrypoints/cli.tsx，先處理 fast-path；協調層集中在 src/main.tsx，負責把命令、工具、模式與會話串起來；執行層以 src/query.ts 的 query loop 為核心，管理模型回應、工具呼叫與錯誤復原。

執行路徑（主骨架）

// src/entrypoints/cli.tsx
if (args.length === 1 && (args[0] === '--version' || args[0] === '-v')) {
  console.log(`${MACRO.VERSION} (Claude Code)`)
  return
}

// 其他情境才進完整流程
const { main } = await import('../main.js')
await main()

入口先做快取路徑判斷，避免每次都載入整個系統。

CLI 參數輸入
-> entrypoint fast-path 分流（version / daemon / bg / runner...）
-> main.tsx 組裝命令、工具、模式、session、權限
-> query.ts 執行回合迴圈
-> runTools / hooks / compact / token budget
-> 更新狀態與輸出 UI

flowchart TD
  A[entrypoints/cli.tsx
快速分流] --> B[main.tsx
協調與初始化]
  B --> C[commands.ts
命令註冊與 gate]
  B --> D[tools.ts
工具清單與 gate]
  B --> E[tasks.ts
任務型別組裝]
  B --> F[query.ts
回合引擎]
  F --> G[toolOrchestration / hooks]
  F --> H[state + session storage]
  H --> I[terminal UI]

關鍵決策（為什麼是這個形狀）

決策 1：入口做 fast-path，重模組延遲載入

在 src/entrypoints/cli.tsx，--version 可零額外載入直接回應；其他指令才進 main.js。這讓常見查詢延遲最小化。

決策 2：功能透過 feature gate 漸進開放

src/commands.ts、src/tools.ts、src/main.tsx 大量使用 feature('...')，把 assistant、bridge、workflow、browser 等能力做條件載入。

決策 3：回合引擎集中處理錯誤與恢復

src/query.ts 把 compact、tool orchestration、token budget、max output recovery 集中在同一個 query loop，讓行為可預測且便於追蹤。

替代方案與取捨

方案	優點	缺點	目前採用判斷
單一 mega-main（入口直接初始化全部）	路徑單純、檔案切換少	冷啟動重、簡單命令成本高	未採用，改為 entrypoint 分流 + 延遲載入
全部功能預設啟用	行為一致、文件較好寫	實驗風險高，難灰度發布	未採用，改用 feature gate 漸進開放
每個模組各自處理復原	模組自治高	錯誤策略分散、難維護	未採用，query loop 集中復原策略

失敗路徑與防護

Failure 1：把入口做太重

症狀：簡單命令也變慢。防護：維持 src/entrypoints/cli.tsx 只做分流，不把業務邏輯塞進入口。

Failure 2：feature gate 與文件不同步

症狀：文件說可用，但實際被 gate 關閉。防護：每次寫教學都先查 src/commands.ts / src/tools.ts 的 gate 條件。

Failure 3：回合恢復邏輯散落

症狀：max token、tool 錯誤、compact 行為不一致。防護：以 src/query.ts 為唯一真實來源追蹤恢復策略。

實作驗證（overview tab 怎麼用）

先讀本頁 Mermaid 圖，確認你能說出「入口、協調、執行」三層責任。
再對照章節深讀：入口看「啟動流程」、協調看「指令系統/工具系統」、執行看「回合引擎」。
若你在排查功能可用性，先查 feature('...')，再看命令與工具是否真的被註冊。
改動前後都跑一次此頁提到的路徑檢查，確保沒有打破分層邊界。