從 Claude Code 源碼學到的 11 個設計模式

作者：與AI同行之路

日期：2025年12月30日下午3:46

來源：WeChat 原文

✦整理版優先睇

速讀 5 個重點高亮

Claude Code 嘅設計精髓：簡單 while 循環，靠模型能力唔靠複雜架構

整理版摘要

呢篇文章係作者逆向咗 Claude Code 最新版源碼之後嘅觀察。背景係 Manus 被收購，AI Agent 賽道好火爆，但真正好用嘅產品唔多。Claude Code 作為 Coding Agent 裏口碑最好嘅之一，冇用花哨框架但就係好使，作者想從源碼拆解佢嘅設計模式，睇下有咩可以俾自製 Agent 嘅人參考。整體結論係：Claude Code 核心只係一個 while 循環，所有複雜嘢都交俾模型自己搞，而家模型嘅推理同規劃能力已經夠強，唔使開發者逐歩編排。

作者列出咗 11 個具體模式，涵蓋核心架構、搜索策略、上下文隔離、任務追蹤、工具設計、安全防護、模型回退等等。重點係：用 ripgrep 代替 RAG 做精確搜索、用子代理隔離上下文、純靠 prompt 做任務追蹤、用 bash 做萬能工具而唔整幾十個專用 tool、先讀後改嘅文件操作、命令注入防護、模型自動降級回退、Extended Thinking 預算控制、持久化輸出管理同會話恢復機制。

作者認為，呢啲模式嘅共同趨勢係：模型推理同指令遵循能力不斷增強，可以逐步拆走以前嗰啲腳手架（ embedding、分類器、正則），俾模型做更多嘢。但唔係每個場景都啱用，要根據自己情況判斷。

核心架構只係一個 while 循環加 tool 調用，模型自己決定下一步，唔使 DAG 或狀態機。
代碼搜索用 ripgrep 做精確匹配，唔用 vector DB，簡單又唔使維護 embedding pipeline。
子代理模式用嚟隔離上下文：主 agent fork 出 worker，獨立上下文，做完只回結果。
任務追蹤純靠 prompt 約束，冇 code-level 校驗，證明而家模型指令跟從能力夠強。
文件操作強制先讀後改，仲會檢測外部修改同 command injection，安全機制好完善。

整理重點

核心架構：就係個 while 循環

好多人以為 Agent 要複雜編排，但 Claude Code 證明咗：現代模型嘅推理同規劃能力已經足夠好，唔需要開發者逐歩話佢知要做咩。呢個賭注嘅前提係模型指令跟從能力夠強，而家嘅模型已經做到。

程式內容 typescript

while (turns < maxTurns) {
 const cleanedMessages = cleanOldPersistedOutputs(messages, 3);
 response = await client.createMessage(cleanedMessages, tools, systemPrompt);
 for (const block of response.content) {
 if (block.type === 'tool_use') {
 result = await toolRegistry.execute(block.name, block.input, onPermissionRequest);
 toolResults.push({ tool_use_id: block.id, content: formatToolResult(result) });
 }
 }
 if (toolResults.length > 0) {
 session.addMessage({ role: 'user', content: toolResults });
 } else if (response.stopReason === 'end_turn') {
 break;
 }
}

簡單循環背後嘅信念係：模型可以自己 decide 下一步，開發者只需要提供工具同系統提示詞就得。呢個設計大幅降低咗 Agent 框架嘅複雜度。

整理重點

關鍵模式：Grep、子代理、純 Prompt 追蹤

第一，搜索代碼時 Claude Code 用 ripgrep 而唔係向量數據庫。原因係代碼搜索要精確匹配，模型好擅長構造 search command 同解讀結果，而且 infrastructure 簡單好多。如果你嘅場景係大量文檔需要語義搜索或者多語言內容，咁先考慮 RAG。

第二，子代理隔離上下文。主 agent 遇到複雜 task 時，會 spawn 一個子代理，俾佢一個乾淨嘅上下文去做 research，做完只返結果。咁樣就唔會污染主 agent 嘅 context window。Claude Code 入面有 explore、plan、communication 等多種子代理類型。

第三，純靠提示詞嘅任務追蹤。源碼冇任何 code-level 嘅 todo 校驗，只係喺 system prompt 寫明「任何時候只能有一個 task 係 in_progress」，然後模型就會乖乖跟住做。呢個一年前仲唔 work，但而家模型指令跟從能力強到可以慳返好多 code。

1 用 ripgrep 做精確匹配，唔使維護 embedding pipeline。
2 子代理有獨立短上下文，主 agent fork 出去收集結果再匯總。
3 任務狀態靠 prompt 約束，模型會自動標記 completed 或 pending。

整理重點

工具設計與安全防護：Bash 萬能 + 多層攔截

Claude Code 冇整幾十個專用 tool，反而重度依賴 bash：execute_shell 一個 function 就搞掂。模型自己 generate 命令（cat、grep、pytest、git），甚至可以臨時寫 Python 腳本跑完就刪。好處係組合性強，壞處係危險，所以要有強力防護。

除咗防護，文件操作強制先讀後改。Edit tool 裏面會檢查個 file 係咪 read 過，仲會 detect 外部修改（比對 mtime），防止覆蓋。另外有智能引號處理（將 Word 嘅彎引號轉直引號）同行號前綴剝離。

程式內容 typescript

const DANGEROUS_PATTERNS = [
 { name: 'Recursive Delete', pattern: /rm\s+(-[rf]*\s+)*\//, severity: 'critical' },
 { name: 'Disk Wipe', pattern: /dd\s+if=\/dev\/(zero|random)/i, severity: 'critical' },
 { name: 'Download and Execute', pattern: /(curl|wget).*\|\s*(sh|bash|python)/, severity: 'critical' },
 { name: 'Sudo Command', pattern: /sudo\s+/, severity: 'high' },
 // ... total 15 patterns
];

整理重點

模型回退、持久化輸出、會話恢復

生產環境必備嘅模型自動降級。ModelFallback 類會先試主模型，遇到 rate_limit / overloaded 等錯誤會指數退避重試，N 次都失敗就自動 switch 去 fallbackModel（例如 opus 降 sonnet），仲會 record 切換事件。

持久化輸出管理解決大輸出撐爆 context 嘅問題。超過 400KB 嘅 tool output 會 truncate 剩 2KB 嘅 preview，包喺 <persisted-output> tag 裏面。每次 API call 前 clean 舊嘅 persisted output，只 keep 最近 3 個。

會話恢復機制：context 就快滿嘅時候，agent 會自動 generate summary 並 save 到 ~/.claude/sessions/summaries/。新 session 開始時 load 返個 summary，build 一條 resume message 叫模型繼續。長 task 唔使從頭做過。

模型回退：主模型失敗自動降級，唔使成個 task 死咗。
持久化輸出：大 output 只留 preview，清理舊記錄慳 context。
會話恢復：生成摘要，下次繼續，唔使從頭開始。

整理重點

總結：拆走腳手架，讓模型做更多

作者最後提出咗幾個演進方向：自適應推理預算（按問題難度分配 thinking tokens）、技能作為可擴展提示（agent 需要時先 load 額外 context）、無頭 Agent SDK（放喺 CI/CD 或定時任務）。

整體嚟講，Claude Code 嘅設計思路係：簡單循環夠用就唔加複雜度，模型做得到嘅就唔用 code 去做，但係關鍵安全位一定要做足。呢啲模式對自己整 Agent 好有參考價值。

今日俾 Manus 收購嘅新聞洗曬版。Manus 先出咗幾個月，轉眼就俾 meta 收購咗，AI Agent 呢個賽道真係捲到飛起。

講真，而家造 Agent 嘅工具同框架一大堆，但真正跑得掂嘅產品冇幾個。啱啱呢兩日見到有人將 Claude Code 最新版嘅代碼逆向咗出嚟，我花咗幾日時間睇咗嚇，發現佢嘅架構設計幾得意。

Claude Code 算係而家 Coding Agent 入面口碑最好嘅之一。佢冇用乜嘢花巧嘅框架，但就係好用。呢啲唔係乜嘢金科玉律，只係一啲觀察，睇嚇邊啲對你自己造 Agent 有啟發。

核心架構：就係一個 while 循環

講出嚟你可能唔信，Claude Code 嘅核心就係咁簡單：

while (turns < maxTurns) {
// 清理舊的大輸出，防止上下文爆炸
const cleanedMessages = cleanOldPersistedOutputs(messages, 3);

  response = await client.createMessage(cleanedMessages, tools, systemPrompt);

for (const block of response.content) {
    if (block.type === 'tool_use') {
      result = await toolRegistry.execute(block.name, block.input, onPermissionRequest);
      toolResults.push({ tool_use_id: block.id, content: formatToolResult(result) });
    }
  }

if (toolResults.length > 0) {
    session.addMessage({ role: 'user', content: toolResults });
  } elseif (response.stopReason === 'end_turn') {
    break;
  }
}

冇複雜嘅 DAG，冇花巧嘅狀態機。模型決定用乜嘢工具，執行，攞結果，再決定。maxTurns 預設 50，夠用㗎喇。

呢個唔係偶然嘅。背後嘅賭注係：現代模型嘅推理同規劃能力已經夠好，唔需要你去安排每一步。

模式一：用 Grep 而唔係 RAG

搜索代碼嗰陣，Claude Code 用嘅係 ripgrep，唔係向量數據庫：

// 模型生成 shell 命令
rg "function calculatePrice" --type ts

// 原始輸出直接塞進上下文
// 模型自己解析，決定下一步讀什麼

點解可能適合你：

代碼搜索要嘅係精確匹配，唔係語義相似
唔使維護 embedding pipeline
模型好擅長構造搜索命令同解讀結果
基礎設施更簡單

幾時仲要用 RAG：

大量文檔需要語義搜索
要揾概念相關而唔係關鍵詞匹配嘅內容
多語言內容

模式二：子代理隔離上下文

上下文窗口塞滿咗，模型性能就冧咗。Claude Code 用子代理解決呢個問題：

const subTask = {
  name: "Task",
  parameters: {
    description: "找到 DefaultChatContext 在哪實例化的",
    prompt: "搜索 ChatTabViewViewModel.swift，只返回文件路徑和行號"
  }
};

主代理做協調者，需要調研或者完成特定任務時，spawn 一個子代理，子代理有自己乾淨嘅上下文，做完嘢只係返返個結果。

關鍵洞察：每個 worker 有獨立嘅短上下文；主代理 fork，子代理收集，主代理彙總。

Claude Code 入面嘅子代理類型（src/agents/）：

explore.ts - 代碼庫探索
plan.ts - 軟件架構師，做計劃
communication.ts - 通信代理
monitor.ts - 監控系統
parallel.ts - 並行執行
resume.ts - 會話恢復

如果你嘅 Agent 成日喺任務中途走樣，呢個模式值得試嚇。

模式三：純靠提示詞嘅任務追蹤

呢個令我意外：Claude Code 嘅任務追蹤冇代碼層面嘅校驗，純靠 prompt 約束：

系統提示詞入面寫：

任何時候只可以有一個任務標記做 in_progress
完成之後立即標記做 completed
俾人阻塞就保持 in_progress，創建子任務

然後模型就……照做咗：

{
  "todos": [
    {"id": "a1f", "title": "復現失敗的測試", "status": "done"},
    {"id": "b9c", "title": "實現修復", "status": "running"},
    {"id": "e7d", "title": "加回歸測試", "status": "pending"}
  ]
}

一年前呢招唔掂。而家嘅模型指令遵循能力強到可以慳返好多代碼層面嘅校驗。

模式四：Bash 做萬能工具

Claude Code 冇整幾十個專用工具，而係重度依賴 bash：

// 不是這樣
def read_file(path): ...
def write_file(path, content): ...
def run_tests(): ...

// 而是這樣
def execute_shell(command):
    return subprocess.run(command, shell=True, capture_output=True)

模型自己生成需要嘅命令：cat、grep、pytest、git，甚至臨時寫個 Python 腳本跑完就刪咗佢。

點解得：

模型訓練數據入面見過大量 bash
可組合性：任意工具黐埋一齊
少咗工具註冊嘅開銷

代價： 又勁又危險。Claude Code 靠多層防護兜底（下面會講）。

模式五：佢哋選擇唔做嘅嘢

有時候冇做乜嘢同做咗乜嘢一樣有意思。Claude Code 明確唔用：

代碼搜索嘅 embeddings
路由用嘅分類器
意圖檢測嘅正則匹配
解析模型輸出嘅正則
基於 ML 嘅意圖檢測層

邏輯係：模型做得嘅嘢，俾模型做。每多一層都係可能壞嘅點、需要維護嘅嘢、增加嘅複雜度。

模式六：持久化輸出管理

呢個係我翻源碼發現嘅精華。大工具輸出點處理？Claude Code 用 <persisted-output> 標籤：

const OUTPUT_THRESHOLD = 400000; // 400KB
const PREVIEW_SIZE = 2000; // 2KB

function wrapPersistedOutput(content: string): string {
if (content.length <= OUTPUT_THRESHOLD) return content;

// 超大輸出只保留 2KB 預覽
const { preview } = truncateOutput(content, PREVIEW_SIZE);
return`<persisted-output>\nPreview:\n${preview}\n...</persisted-output>`;
}

// 每次 API 調用前，清理舊的持久化輸出，只保留最近 3 個
function cleanOldPersistedOutputs(messages, keepRecent = 3) {
// 找到所有 persisted-output，只保留最近 3 個
// 舊的替換成 '[Old tool result content cleared]'
}

呢個就係點解 Claude Code 可以處理巨大檔案而唔會將上下文撐爆。

模式七：模型回退機制

源碼入面有個 ModelFallback 類（src/models/fallback.ts），實現咗自動降級：

class ModelFallback {
  async executeWithFallback<T>(operation: (model: string) => Promise<T>) {
    // 1. 先用主模型（如 opus）
    // 2. 遇到 rate_limit/overloaded 等錯誤，指數退避重試
    // 3. 重試 N 次還失敗，自動切換到 fallbackModel（如 sonnet）
    // 4. 記錄切換事件，支持監聽器
  }
  
  // 可重試的錯誤類型
  RETRYABLE_ERRORS = [
    'overloaded_error', 'rate_limit_error', 'api_error',
    'timeout', 'ECONNRESET', 'capacity_exceeded'
  ];
}

生產環境必備。模型服務唔穩定係常態，自動降級好過冧檔。

模式八：Extended Thinking 預算控制

Claude Code 支援 Extended Thinking（src/models/thinking.ts），但唔係無腦開：

class ThinkingManager {
// 根據任務複雜度推薦預算
  recommendBudget(complexity: 'simple' | 'medium' | 'complex'): number {
    switch (complexity) {
      case'simple': return2000;
      case'medium': return10000;
      case'complex': return50000;
    }
  }

// 檢查是否快用完預算了
  processThinkingResponse(response) {
    if (thinkingTokens >= budgetTokens * 0.95) {
      result.budgetExhausted = true;
    }
  }
}

思考唔係免費嘅，要管預算。簡單問題俾 2K tokens 諗，複雜架構設計俾 50K。

模式九：先讀後改嘅檔案操作

Edit 工具有個硬性要求：一定要先 Read 再 Edit。源碼入面有個 FileReadTracker：

class FileReadTracker {
private readFiles: Map<string, { path, readTime, mtime }>;

  markAsRead(filePath: string, mtime: number): void {
    this.readFiles.set(path.resolve(filePath), { path, readTime: Date.now(), mtime });
  }

  hasBeenRead(filePath: string): boolean {
    returnthis.readFiles.has(path.resolve(filePath));
  }
}

// Edit 工具裏
if (!fileReadTracker.hasBeenRead(input.file_path)) {
returnthis.error('File must be read before editing');
}

// 還會檢查 mtime，防止外部修改後覆蓋
const currentMtime = fs.statSync(input.file_path).mtimeMs;
if (currentMtime !== record.mtime) {
returnthis.error('File has been modified externally since last read');
}

另外仲有智能引號處理（將 Word 複製出嚟嘅彎引號轉返做直引號）同行號前綴剝離（Read 輸出帶行號，Edit 時自動刪咗佢）。

模式十：命令注入防護

俾 Agent shell 權限好危險。Claude Code 喺 src/security/command-injection.ts 入面做咗 15 種危險模式檢測：

const DANGEROUS_PATTERNS = [
  { name: 'Recursive Delete', pattern: /rm\s+(-[rf]*\s+)*\//, severity: 'critical' },
  { name: 'Disk Wipe', pattern: /dd\s+if=\/dev\/(zero|random)/i, severity: 'critical' },
  { name: 'Download and Execute', pattern: /(curl|wget).*\|\s*(sh|bash|python)/, severity: 'critical' },
  { name: 'Sudo Command', pattern: /sudo\s+/, severity: 'high' },
  { name: 'Command Substitution', pattern: /`[^`]*`|\$\([^)]*\)/, severity: 'high' },
  { name: 'Path Traversal', pattern: /\.\.[\/\\]/, severity: 'medium' },
  // ... 還有 9 種
];

// 檢測到危險命令會記審計日誌
if (violations.length > 0) {
  auditLogger.logSecurityEvent('command_injection_detected', 'critical', { command, violations });
}

沙箱都分級：Linux 用 Bubblewrap，macOS 用 Seatbelt，仲支援 Docker 隔離。

模式十一：會話恢復機制

上下文溢出咗點算？Claude Code 支援會話恢復（src/session/resume.ts）：

// 1. 對話快溢出時，生成摘要並保存
async function generateAndSaveSummary(sessionId, turns, client) {
  const summary = await generateAISummary(turns, client, contextBudget);
  saveSummary(sessionId, summary);  // 存到 ~/.claude/sessions/summaries/
}

// 2. 新會話開始時，構建恢復消息
function buildResumeMessage(summary: string): string {
  return `This session is being continued from a previous conversation that ran out of context.
The conversation is summarized below:
${summary}
Please continue from where we left off without asking further questions.`;
}

長任務跑到一半上下文滿咗，唔使從頭嚟過。摘要存喺本地，下次繼續。

俾自己造 Agent 嘅啟示

簡單循環可能夠用。while 循環加工具調用可能就得，先試嚇再加複雜度
上下文係寶貴嘅。子代理隔離、持久化輸出、會話恢復，都係為咗慳上下文
提示詞約束可行。現代模型指令遵循夠好，可以砍咗一啲代碼校驗
Bash 好強但要防護。命令注入檢測 + 沙箱 + 審計日誌，缺一不可
模型會冧檔。回退機制、指數退避、錯誤分類，生產環境必備
思考要管預算。Extended Thinking 按任務複雜度分配
檔案操作要謹慎。先讀後改、檢測外部修改、智能匹配
質疑每個組件。唔需要嘅 embedding、分類器、正則，都係負擔

喺演進嘅方向

自適應推理預算：根據問題難度調整思考深度（"think"、"think hard"、"ultrathink"）
技能作為可擴展提示：Agent 決定需要時先加載額外上下文
無頭 Agent SDK：將 Agent 跑喺自動化流水線入面（CI/CD、定時任務）

底層趨勢係：模型推理同指令遵循越來越強，可以拆咗棚架，俾模型做更多嘢。

呢個對你嘅具體場景係咪啱嘅方向，值得仔細諗嚇。但知道人哋喺度點玩總係有用嘅。

今天被 Manus 收購的新聞刷屏了。Manus 這才出來幾個月，轉眼就被 meta 收了，AI Agent 這個賽道真是卷得飛起。

說實話，現在造 Agent 的工具和框架一大堆，但真正跑得好的產品沒幾個。恰好這兩天看到有人把 Claude Code 最新版的代碼給逆向出來了，我花了幾天時間翻了翻，發現它的架構設計挺有意思的。

Claude Code 算是目前 Coding Agent 裏口碑最好的之一了。它沒用什麼花哨的框架，但就是好使。這些不是什麼金科玉律，只是一些觀察，看看哪些對你自己造 Agent 有啓發。

核心架構：就是個 while 循環

說出來你可能不信，Claude Code 的核心就這麼簡單：

while (turns < maxTurns) {
// 清理舊的大輸出，防止上下文爆炸
const cleanedMessages = cleanOldPersistedOutputs(messages, 3);

  response = await client.createMessage(cleanedMessages, tools, systemPrompt);

for (const block of response.content) {
    if (block.type === 'tool_use') {
      result = await toolRegistry.execute(block.name, block.input, onPermissionRequest);
      toolResults.push({ tool_use_id: block.id, content: formatToolResult(result) });
    }
  }

if (toolResults.length > 0) {
    session.addMessage({ role: 'user', content: toolResults });
  } elseif (response.stopReason === 'end_turn') {
    break;
  }
}

沒有複雜的 DAG，沒有花哨的狀態機。模型決定調什麼工具，執行，拿結果，再決定。maxTurns 默認 50，夠用了。

這不是偶然的。背後的賭注是：現代模型的推理和規劃能力已經足夠好，不需要你去編排每一步。

模式一：用 Grep 而不是 RAG

搜索代碼時，Claude Code 用的是 ripgrep，不是向量數據庫：

// 模型生成 shell 命令
rg "function calculatePrice" --type ts

// 原始輸出直接塞進上下文
// 模型自己解析，決定下一步讀什麼

為什麼可能適合你：

代碼搜索要的是精確匹配，不是語義相似
不用維護 embedding pipeline
模型很擅長構造搜索命令和解讀結果
基礎設施更簡單

什麼時候還是用 RAG：

大量文檔需要語義搜索
要找概念相關而非關鍵詞匹配的內容
多語言內容

模式二：子代理隔離上下文

上下文窗口塞滿了，模型性能就垮了。Claude Code 用子代理解決這個問題：

const subTask = {
  name: "Task",
  parameters: {
    description: "找到 DefaultChatContext 在哪實例化的",
    prompt: "搜索 ChatTabViewViewModel.swift，只返回文件路徑和行號"
  }
};

主代理當協調者，需要調研或完成特定任務時，spawn 一個子代理，子代理有自己乾淨的上下文，幹完活只返回結果。

關鍵洞察：每個 worker 有獨立的短上下文；主代理 fork，子代理收集，主代理彙總。

Claude Code 裏的子代理類型（src/agents/）：

explore.ts - 代碼庫探索
plan.ts - 軟件架構師，做計劃
communication.ts - 通信代理
monitor.ts - 監控系統
parallel.ts - 並行執行
resume.ts - 會話恢復

如果你的 Agent 總是在任務中途跑偏，這個模式值得試試。

模式三：純靠提示詞的任務追蹤

這個讓我意外：Claude Code 的任務追蹤沒有代碼層面的校驗，純靠 prompt 約束：

系統提示詞裏寫：

任何時候只能有一個任務標記為 in_progress
完成後立即標記 completed
被阻塞就保持 in_progress，創建子任務

然後模型就……照做了：

{
  "todos": [
    {"id": "a1f", "title": "復現失敗的測試", "status": "done"},
    {"id": "b9c", "title": "實現修復", "status": "running"},
    {"id": "e7d", "title": "加回歸測試", "status": "pending"}
  ]
}

一年前這招不好使。現在的模型指令遵循能力強到可以省掉很多代碼層面的校驗。

模式四：Bash 當萬能工具

Claude Code 沒造幾十個專用工具，而是重度依賴 bash：

// 不是這樣
def read_file(path): ...
def write_file(path, content): ...
def run_tests(): ...

// 而是這樣
def execute_shell(command):
    return subprocess.run(command, shell=True, capture_output=True)

模型自己生成需要的命令：cat、grep、pytest、git，甚至臨時寫個 Python 腳本跑完刪掉。

為什麼能行：

模型訓練數據裏見過大量 bash
可組合性：任意工具鏈在一起
少了工具註冊的開銷

代價： 又強又危險。Claude Code 靠多層防護兜底（下面會講）。

模式五：他們選擇不造的東西

有時候沒做什麼和做了什麼一樣有意思。Claude Code 明確不用：

代碼搜索的 embeddings
路由用的分類器
意圖檢測的正則匹配
解析模型輸出的正則
基於 ML 的意圖檢測層

邏輯是：模型能幹的事，讓模型幹。每多一層都是可能壞的點、需要維護的東西、增加的複雜度。

模式六：持久化輸出管理

這個是我翻源碼發現的精華。大工具輸出怎麼處理？Claude Code 用 <persisted-output> 標籤：

const OUTPUT_THRESHOLD = 400000; // 400KB
const PREVIEW_SIZE = 2000; // 2KB

function wrapPersistedOutput(content: string): string {
if (content.length <= OUTPUT_THRESHOLD) return content;

// 超大輸出只保留 2KB 預覽
const { preview } = truncateOutput(content, PREVIEW_SIZE);
return`<persisted-output>\nPreview:\n${preview}\n...</persisted-output>`;
}

// 每次 API 調用前，清理舊的持久化輸出，只保留最近 3 個
function cleanOldPersistedOutputs(messages, keepRecent = 3) {
// 找到所有 persisted-output，只保留最近 3 個
// 舊的替換成 '[Old tool result content cleared]'
}

這就是為什麼 Claude Code 能處理巨大文件而不會把上下文撐爆。

模式七：模型回退機制

源碼裏有個 ModelFallback 類（src/models/fallback.ts），實現了自動降級：

class ModelFallback {
  async executeWithFallback<T>(operation: (model: string) => Promise<T>) {
    // 1. 先用主模型（如 opus）
    // 2. 遇到 rate_limit/overloaded 等錯誤，指數退避重試
    // 3. 重試 N 次還失敗，自動切換到 fallbackModel（如 sonnet）
    // 4. 記錄切換事件，支持監聽器
  }
  
  // 可重試的錯誤類型
  RETRYABLE_ERRORS = [
    'overloaded_error', 'rate_limit_error', 'api_error',
    'timeout', 'ECONNRESET', 'capacity_exceeded'
  ];
}

生產環境必備。模型服務不穩定是常態，自動降級比掛掉強。

模式八：Extended Thinking 預算控制

Claude Code 支持 Extended Thinking（src/models/thinking.ts），但不是無腦開：

class ThinkingManager {
// 根據任務複雜度推薦預算
  recommendBudget(complexity: 'simple' | 'medium' | 'complex'): number {
    switch (complexity) {
      case'simple': return2000;
      case'medium': return10000;
      case'complex': return50000;
    }
  }

// 檢查是否快用完預算了
  processThinkingResponse(response) {
    if (thinkingTokens >= budgetTokens * 0.95) {
      result.budgetExhausted = true;
    }
  }
}

思考不是免費的，要管預算。簡單問題給 2K tokens 想，複雜架構設計給 50K。

模式九：先讀後改的文件操作

Edit 工具有個硬性要求：必須先 Read 再 Edit。源碼裏有個 FileReadTracker：

class FileReadTracker {
private readFiles: Map<string, { path, readTime, mtime }>;

  markAsRead(filePath: string, mtime: number): void {
    this.readFiles.set(path.resolve(filePath), { path, readTime: Date.now(), mtime });
  }

  hasBeenRead(filePath: string): boolean {
    returnthis.readFiles.has(path.resolve(filePath));
  }
}

// Edit 工具裏
if (!fileReadTracker.hasBeenRead(input.file_path)) {
returnthis.error('File must be read before editing');
}

// 還會檢查 mtime，防止外部修改後覆蓋
const currentMtime = fs.statSync(input.file_path).mtimeMs;
if (currentMtime !== record.mtime) {
returnthis.error('File has been modified externally since last read');
}

另外還有智能引號處理（把 Word 複製出來的彎引號轉成直引號）和行號前綴剝離（Read 輸出帶行號，Edit 時自動去掉）。

模式十：命令注入防護

給 Agent shell 權限很危險。Claude Code 在 src/security/command-injection.ts 裏做了 15 種危險模式檢測：

const DANGEROUS_PATTERNS = [
  { name: 'Recursive Delete', pattern: /rm\s+(-[rf]*\s+)*\//, severity: 'critical' },
  { name: 'Disk Wipe', pattern: /dd\s+if=\/dev\/(zero|random)/i, severity: 'critical' },
  { name: 'Download and Execute', pattern: /(curl|wget).*\|\s*(sh|bash|python)/, severity: 'critical' },
  { name: 'Sudo Command', pattern: /sudo\s+/, severity: 'high' },
  { name: 'Command Substitution', pattern: /`[^`]*`|\$\([^)]*\)/, severity: 'high' },
  { name: 'Path Traversal', pattern: /\.\.[\/\\]/, severity: 'medium' },
  // ... 還有 9 種
];

// 檢測到危險命令會記審計日誌
if (violations.length > 0) {
  auditLogger.logSecurityEvent('command_injection_detected', 'critical', { command, violations });
}

沙箱也分級：Linux 用 Bubblewrap，macOS 用 Seatbelt，還支持 Docker 隔離。

模式十一：會話恢復機制

上下文溢出了怎麼辦？Claude Code 支持會話恢復（src/session/resume.ts）：

// 1. 對話快溢出時，生成摘要並保存
async function generateAndSaveSummary(sessionId, turns, client) {
  const summary = await generateAISummary(turns, client, contextBudget);
  saveSummary(sessionId, summary);  // 存到 ~/.claude/sessions/summaries/
}

// 2. 新會話開始時，構建恢復消息
function buildResumeMessage(summary: string): string {
  return `This session is being continued from a previous conversation that ran out of context.
The conversation is summarized below:
${summary}
Please continue from where we left off without asking further questions.`;
}

長任務跑到一半上下文滿了，不用從頭來。摘要存本地，下次繼續。

給自己造 Agent 的啓示

簡單循環可能夠用。while 循環加工具調用可能就行，先試試再加複雜度
上下文是寶貴的。子代理隔離、持久化輸出、會話恢復，都是在省上下文
提示詞約束可行。現代模型指令遵循夠好，可以砍掉一些代碼校驗
Bash 很強但要防護。命令注入檢測 + 沙箱 + 審計日誌，缺一不可
模型會掛。回退機制、指數退避、錯誤分類，生產環境必備
思考要管預算。Extended Thinking 按任務複雜度分配
文件操作要謹慎。先讀後改、檢測外部修改、智能匹配
質疑每個組件。不需要的 embedding、分類器、正則，都是負擔

在演進的方向

自適應推理預算：根據問題難度調整思考深度（"think"、"think hard"、"ultrathink"）
技能作為可擴展提示：Agent 決定需要時才加載額外上下文
無頭 Agent SDK：把 Agent 跑在自動化流水線裏（CI/CD、定時任務）

底層趨勢是：模型推理和指令遵循越來越強，可以拆掉腳手架，讓模型幹更多活。

這對你的具體場景是不是對的方向，值得仔細想想。但知道別人在怎麼玩總是有用的。