從零構建 Claude Code 式 AI Agent 執行框架教程

解決什麼

當前 AI Agent 開發領域充斥著"無程式碼平臺"和"視覺化編排工具",它們宣稱通過拖拽節點、串聯 Prompt 就能"構建 Agent"。這個專案用一記重拳打破這種幻覺:Agent 的智慧來自模型訓練(如 GPT、Claude 的預訓練和強化學習),而非外部程式碼編排。工程師的真正任務是構建"執行框架"(Harness)——讓已有智慧的模型能在特定環境(如程式碼編輯器、終端)中感知、推理和行動。

專案通過從零實現一個類 Claude Code 的微型 Agent 框架,教你理解 Agent 產品的本質:模型(駕駛員)+ 執行框架(車輛)。它用 Bash 和 Python 演示如何給模型提供工具(檔案讀寫、Shell 執行)、知識(文件、API 規範)、觀察介面(日誌、Git diff)和許可權控制(沙箱隔離),而不是試圖用 if-else 邏輯"創造智慧"。

為何火

7 萬+ stars 背後是開發者對 Agent 底層原理的渴求。專案 README 開篇就用 DeepMind DQN(2013 年玩 Atari)、OpenAI Five(2019 年擊敗 Dota 2 世界冠軍)、AlphaStar(2019 年達到星際爭霸 2 宗師段位)等里程碑證明:所有 Agent 的智慧都來自模型訓練,而非周圍的程式碼。這種"思維轉變"擊中了被 Prompt 編排工具誤導的工程師痛點。

專案用"Bash is all you need"這句挑釁式口號,強調執行框架的本質是簡單、原子化的工具組合,而非複雜的流程編排。它將 Agent 工程師的角色重新定義為"Harness Engineer"(執行框架工程師),明確職責邊界:實現工具、管理上下文、控制權限,而非"創造智慧"。這種清晰的定位讓開發者從"Agent 鍊金術"迴歸工程本質。

核心功能

專案是教學性質,核心內容包括:

1. 執行框架(Harness)設計模式:定義 Harness = 工具 + 知識 + 觀察介面 + 行動介面 + 許可權控制,用公式化方式拆解 Agent 產品的組成部分
2. 工具實現示例:演示如何用 Python 封裝檔案讀寫、Shell 執行、API 呼叫等原子化工具,強調"可組合、描述清晰"的設計原則
3. 上下文管理策略:展示如何按需載入領域知識(產品文件、架構決策記錄),而非一次性塞滿上下文視窗
4. 許可權與安全邊界:講解沙箱隔離、審批流程、信任邊界的實現思路,避免 Agent 失控
5. 思維框架糾偏:用歷史案例(DQN、AlphaStar、OpenAI Five)和反面教材(無程式碼 Agent 平臺)對比,強化"智慧來自訓練"的核心觀念

安裝

這是教學專案而非生產工具,使用方式是:

1. 克隆倉庫:git clone https://github.com/shareAI-lab/learn-claude-code.git
2. 閱讀 README 和程式碼示例,理解 Harness 設計模式
3. 根據示例程式碼(Python + Bash)自行實現或改造為生產環境的執行框架

專案未提供 Docker 或 pip 安裝包,因為它是"教你造車"而非"給你一輛車"。開發者需要有 Python 基礎和對 LLM API(如 Claude、GPT)的呼叫經驗。

適合誰

• 被無程式碼 Agent 平臺誤導的開發者:想理解 Agent 底層原理,擺脫"拖拽節點就能造 Agent"的幻覺
• LLM 應用工程師:需要給 GPT/Claude 等模型構建生產級執行環境,學習工具設計、上下文管理、許可權控制的最佳實踐
• AI 產品經理:想理解"模型能力"與"工程實現"的邊界,避免對 Agent 產品產生不切實際的期待
• 教學與培訓場景:專案多語言 README(英文、中文、日文)和清晰的概念拆解適合作為 Agent 開發課程的教材

不適合:期待開箱即用工具的使用者,或對 Python/Bash 完全陌生的初學者。

社群評價

HN 上有使用者提問專案是否適合初學者,還是涵蓋高階模式(如工具使用、Prompt 鏈)。從 README 內容看,專案更偏向思維框架糾偏而非具體技術實現細節——它用大量篇幅論證"智慧來自模型訓練"這一觀點,但工具實現、Prompt 工程等細節需要開發者自行探索。

56 個 open issues 和 11,466 個 forks 顯示社群參與度高,但也反映專案作為教學資源,使用者在實際落地時遇到不少問題(如缺少完整示例程式碼、工具介面設計的具體實現等)。專案更像一篇"Agent 工程宣言"而非完整教程,需要讀者有一定工程經驗才能轉化為生產程式碼。

選型對比

vs Claude Code(商業工具):Claude Code 是 Anthropic 的官方 Agent 產品,提供開箱即用的程式碼編輯、終端執行、瀏覽器控制能力。本專案是教你"如何從零實現類似功能",適合想理解底層原理或需要深度定製的團隊,但不提供生產級穩定性和 UI。

vs LangChain/AutoGPT(開源框架):這些框架提供高層抽象(如 Chain、Agent Executor),但專案批評它們"過度工程化",用複雜的流程編排掩蓋了 Agent 的本質。本專案主張"Bash is all you need",強呼叫簡單、原子化的工具組合,而非龐大的抽象層。

vs 無程式碼 Agent 平臺(如 Dify、Coze):專案直接將這類平臺定義為"Rube Goldberg 機器"(過度設計的無用裝置),認為它們只是"帶 LLM 節點的 Shell 指令碼",無法產生真正的自主行為。本專案適合想擺脫這類平臺束縛、深入底層的開發者。

已知坑

1. 教學性質,非生產工具:專案未提供完整可執行的程式碼框架,更多是概念講解和設計模式,需要開發者自行實現
2. 缺少具體實現細節:README 用大量篇幅論證"為什麼",但"怎麼做"(如工具介面設計、錯誤處理、併發控制)需要讀者自行探索
3. 依賴外部 LLM API:專案假設你已有 Claude/GPT 等模型的 API 訪問許可權,中國大陸使用者需要解決網路訪問和 API Key 獲取問題
4. 無沙箱實現示例:雖然強調許可權控制的重要性,但未提供 Docker/虛擬機器級別的沙箱隔離程式碼,生產環境需自行補充
5. 社群問題響應滯後:56 個 open issues 顯示維護者可能無法及時回覆所有問題,適合有自主解決能力的開發者

總結:這是一個"思維轉變"專案而非"拿來即用"工具,適合有經驗的開發者學習 Agent 底層設計哲學,但需要投入時間將概念轉化為生產程式碼。