大多數 Claude Agent 教學都在「Hello World」階段就結束了
它們教你怎麼讓 Claude 呼叫一個工具、怎麼建立基本迴圈、怎麼在一個簡單的玩具任務上取得自主回應。
然後當你真的想建構點什麼時，一切就分崩離析了。
任務太模糊。Agent 卡住了。輸出不一致。工作階段結束，什麼都沒存下來。下一次你只能從頭開始。
一個在教學中運作良好的 Claude agent，和一個能在生產環境中運作的 Claude agent 之間的差距，並不是 Claude 能力的差距。
而是 Agent 設計上的差距。
這份指南將徹底彌合這個差距。
讀完之後，你將擁有一個能在真實工作流程中穩定運作的 Claude agent。不是 demo。不是玩具任務。而是一個能產出穩定結果、優雅處理邊界情況、隨著時間持續改進，而且不需要你手動啟動每個步驟的工作流程。
真實世界的 Agent 有何不同
在開始建構之前，先了解真實世界的 agent 與教學用 agent 的差別在哪裡。
教學用 agent 執行一個乾淨的任務，擁有乾淨的輸入，產出乾淨的輸出。任務定義明確。輸入以完全預期的格式提供。不會有意外發生。成功與否是二元且顯而易見的。
真實世界的 agent 執行的是 messy 的任務，輸入也很 messy，卻必須產出有用的輸出。任務是部分定義的。輸入的格式五花八門。意外狀況時常發生。成功與否是一個程度的問題，需要靠判斷來評估。
有四項特性決定了 agent 能否在真實世界中存活下來：
穩固的任務定義。 Agent 不僅知道要做什麼，還知道如何處理在實務中會遇到的二十種任務變體。指令涵蓋了邊界情況，而不只是 happy path。
持續的記憶。 Agent 能跨工作階段累積脈絡。上週完成的工作能為今天的工作提供資訊。它不會每個工作階段都從零開始。
優雅的失敗處理。 當出錯時，Agent 能夠恢復，而不是直接停擺。它會記錄發生了什麼、嘗試替代方案，只有在無法恢復時才通知人類。
品質自我驗證。 Agent 在交付輸出之前，會根據定義好的標準檢查自己的輸出。它自己完成反饋迴圈，而不是隨便交出第一個產出的東西。
大多數教學用 agent 都不具備這些特性。這份指南將逐步建構這四項。
Agent 架構
這個架構由四個協同運作的元件組成。
任務定義層
一個結構化的技能檔案，定義了任務、流程、邊界情況處理方式以及品質標準。這不是一個提示詞。這是一份完整的作業規範，agent 在每次執行前都會讀取它。
記憶層
一個持久化資料庫，儲存 agent 做過什麼、學到了什麼，以及需要跨工作階段記住的事。基於 SQLite，透過 Hermes Agent 或手動以檔案為基礎的日誌系統來實現。
執行層
實際執行工作的 Claude API 呼叫。結構化設計，能針對工作流程的每個步驟使用正確的模型、正確的上下文和正確的工具。
品質層
驗證迴圈，在交付輸出之前檢查其是否符合定義的標準；當輸出未達標時，會根據具體問題進行修正並重試。
建立基礎
安裝所需的工具：
安裝 Hermes Agent 用於編排和記憶
git clone https://github.com/NousResearch/hermes-agent
cd hermes-agent
npm install
安裝 MCP 伺服器以取得工具存取權限
npm install -g @modelcontextprotocol/server-filesystem
npm install -g @modelcontextprotocol/server-brave-search
設定你的環境：
核心設定
MODEL_PROVIDER=anthropic
MODEL_NAME=claude-opus-4-8
ANTHROPIC_API_KEY=your-api-key-here
記憶設定 — 使用絕對路徑
MEMORY_BACKEND=sqlite
MEMORY_PATH=/Users/yourname/agent-data/memory.db
排程器設定
ENABLE_SCHEDULER=true
SCHEDULER_TIMEZONE=America/New_York
輸出設定 — 結果存放位置
OUTPUT_PATH=/Users/yourname/agent-outputs
失敗復原
SKILL_RETRY_ENABLED=true
SKILL_RETRY_MAX=3
SKILL_RETRY_DELAY=300
通知
NOTIFICATION_GATEWAY=telegram
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_CHAT_ID=your-chat-id
撰寫 CLAUDE.md：
這是整個設定中最重要的檔案。每個 agent 工作階段都是從讀取這個檔案開始的。每個輸出的品質都取決於這裡的內容有多具體。
Agent 設定 — CLAUDE.md
身份與目的
[用一個特定的段落描述這個 agent 做什麼。
不是描述 Claude 的一般能力，而是這個特定的 agent
為這個特定的作業被設定來做什麼。]
作業脈絡
[描述這個 agent 運作所在的商業或個人脈絡。
設定這個 agent 的人是做什麼的？
他們的標準和優先事項是什麼？]
當前活躍任務
[列出這個 agent 執行的特定重複性任務。
每個任務包含：它做什麼、何時執行、好的輸出長什麼樣子。]
工具權限
你被允許自主使用以下工具：
- 檔案系統：讀取和寫入 [特定路徑]
- 網頁搜尋：用於研究 [特定主題]
- [其他工具及其特定範圍]
你不得：
- 寫入任何設定輸出目錄以外的路徑
- 進行上述清單以外的外部 API 呼叫
- 未經明確核准採取任何影響外部系統的行動
品質標準
[描述每個任務類型的良好輸出是什麼樣子。
盡可能包含範例。
具體到 agent 可以自我評估的程度。]
記憶指示
將以下內容存入記憶：
- 每個重要的輸出及其日期和品質評估
- 遇到的每個邊界情況及其處理方式
- 每個品質失敗及其原因
- 在輸出中識別出的每個模式
錯誤處理
工具失敗時：重試一次，記錄失敗，使用可用工具繼續。
品質失敗時：以具體修正為目標重試，而非完全重寫。最多重試三次。
不可恢復的失敗時：儲存部分工作，記錄具體失敗，發送通知，優雅地停止。
建構任務定義層
任務定義層是大多數真實世界 agent 失敗的地方。
人們只寫一個描述 happy path 的提示詞就停了下來。Agent 能很好地處理 happy path，但面對其他所有情況時就崩潰了。
一個穩固的任務定義涵蓋了任務完整的實際運作狀況。以下是範本：
[任務名稱]
目的
[一句話：這個技能要完成什麼？]
觸發條件
[導致此技能執行的確切條件：
排程時間、檔案出現、手動指令等]
執行前檢查
開始之前，請確認：
- [必要的輸入存在且可存取]
- [必要的工具已連接並有回應]
- [輸出路徑可寫入]
- [記憶可存取且為最新狀態]
如果任何檢查失敗：記錄失敗並停止。
缺少必要條件時不要繼續進行。
主要流程
步驟 1：載入脈絡
讀取 CLAUDE.md 以取得完整作業脈絡。
讀取標記為 [TASK-TAG] 的記憶以取得相關歷史記錄。
注意先前執行中應能用以指導本次執行的任何模式。
步驟 2：輸入處理
[精確描述如何處理輸入。
涵蓋主要格式以及實務中會出現的替代格式。]
對於標準輸入格式：
[確切的處理步驟]
對於替代輸入格式 A：
[如何處理]
對於替代輸入格式 B：
[如何處理]
對於格式錯誤或缺失的輸入：
[如何處理 — 絕不靜默失敗]
步驟 3：核心執行
[技能的主要工作。
拆解為子步驟。每個子步驟應具體到
一個全新的 Claude 實例也能在沒有額外脈絡的情況下執行。]
步驟 4：品質驗證
在儲存輸出之前，根據以下標準驗證：
必要：[不可妥協的輸出屬性]
優先：[能提升輸出品質的屬性]
禁止：[絕不應出現在輸出中的內容]
如果輸出未通過必要檢查：
- 具體識別失敗之處
- 以針對性修正為目標重試
- 最多重試三次
- 如果仍然失敗：以失敗標記儲存
步驟 5：輸出與儲存
儲存輸出至：[特定路徑與檔案名稱格式]
存入記憶，標記：[TASK-TAG, DATE]
如果任何當前資訊有變更，更新 CLAUDE.md。
發送通知：[通知中應包含的內容]
邊界情況
[邊界情況 1 名稱]
條件：[何時發生]
檢測：[如何識別]
回應：[該怎麼做]
[邊界情況 2 名稱]
條件：[何時發生]
檢測：[如何識別]
回應：[該怎麼做]
[邊界情況 3 名稱]
條件：[何時發生]
檢測：[如何識別]
回應：[該怎麼做]
品質標準
優秀的輸出：[具體描述]
可接受的輸出：[最低門檻]
不可接受的輸出：[應觸發重試的狀況]
記憶指示
每次執行後儲存：
- 執行日期與持續時間
- 輸出品質評估（優秀/可接受/失敗）
- 遇到的任何邊界情況及其處理方式
- 任何值得在未來執行中注意的模式
你的第一個真實 Agent：研究與摘要 Agent
這是一個使用此架構建構的完整真實世界 agent。這個 agent 每天監控一系列來源，研究與你工作相關的主題，並在每天早上交付一份結構化的摘要。
這不是一個玩具任務。這是一個真實的工作流程，每天能取代 45 分鐘的手動資料蒐集。
建立 skills/research-brief.md：
research-brief
目的
監控已設定的來源，產出一份結構化的
情報摘要，涵蓋與當前專案和優先事項相關的發展。
觸發條件
每天上午 6:00 自動排程。
手動觸發：「研究摘要」或「晨間摘要」
執行前檢查
開始之前，確認：
- CLAUDE.md 可在 07-SYSTEM/CLAUDE.md 讀取
- Brave Search MCP 有回應
- 輸出路徑 outputs/briefings/ 可寫入
- 記憶資料庫可存取
主要流程
步驟 1：載入脈絡
完整讀取 CLAUDE.md。注意：
- 當前活躍專案及其狀態
- 標記為需監控的主題
- 任何需要情報支援的待決策
- 此摘要的品質標準
讀取標記為 research-brief 的記憶。
注意：近期摘要已涵蓋的內容，
以避免重複。
步驟 2：來源研究
針對 CLAUDE.md 監控清單中的每個主題：
搜尋查詢：「[主題] 過去 24 小時新聞」
收集：標題、來源、日期、主要主張
套用訊號篩選器：
包含：新發展、數據、產品發布、重要聲明、研究發現
排除：重複既有報導、沒有新資訊的評論、
過去 3 次摘要已涵蓋的內容
對於每個通過訊號篩選器的結果：
如果初始結果顯示有重大發展，
則進行後續搜尋以深入調查。
步驟 3：綜合分析
按主題分組發現。
針對每個主題群組，識別：
- 單一最重要的發展
- 為何它對當前專案重要
- 它暗示了什麼行動（如果有的話）
跨主題綜合分析：
- 是否有兩個或以上的發現相互關聯，暗示更大的模式？
- 是否有任何發現直接影響活躍專案或待決策？
步驟 4：品質驗證
在定稿前，驗證：
必要：
- 至少 3 個訊號項目（非雜訊）
- 每個項目都基於特定來源
- 每個項目都要說明與當前工作的相關性
- 沒有項目與過去 5 次摘要重複
優先：
- 至少一個跨主題連結
- 至少一個暗示具體行動的項目
- 如果當天新聞較少，誠實告知
禁止：
- 沒有具體證據的泛泛分析
- 有趣但不相關的項目
- 為了讓摘要看起來更全面而塞入的內容
如果摘要未通過必要檢查：具體識別
缺少什麼，並在重試前搜尋更多來源。
不要用弱訊號來充數。
步驟 5：輸出生成
依此確切格式生成摘要：
晨間情報摘要 — [日期]
今日最重要
[單一最重要的發展，以及它為何
對當前工作重要。具體且有根據。]
訊號項目
[主題 1]
發展： [發生了什麼]
來源： [出版物，日期]
相關性： [為何這對當前專案重要]
啟示： [這暗示了什麼行動]
[主題 2]
[同樣格式]
[繼續列出每個訊號項目]
連結
[如果有兩個或以上的項目相互關聯，
暗示更大的模式，在此描述。
如果沒有真正的連結，則跳過此項。]
決策相關性
[如果有任何項目與 CLAUDE.md 中的
待決策直接相關，在此標記並提供細節。]
涵蓋範圍說明
[誠實評估：內容豐富的一天 / 新聞較少的一天。
搜尋的來源數量。]
步驟 6：儲存與通知
儲存至：outputs/briefings/[日期]-morning-brief.md
存入記憶：
- 日期：[今天]
- 涵蓋項目：[主題清單]
- 品質：[優秀/可接受/失敗]
- 值得一提：[任何邊界情況或模式] 標記：research-brief
發送 Telegram 通知：
「晨間摘要已準備好：[N] 個訊號項目。
[今日最重要，一行說明]」
邊界情況
某個主題未找到訊號
條件：搜尋未回傳任何新發展
檢測：所有結果都超過 48 小時
回應：在該主題旁標註「無新發展」。
不要捏造或充數。跳到下一個主題。
來源回傳矛盾資訊
條件：兩個來源報告互相矛盾的事實
檢測：針對特定主張的直接矛盾
回應：報告兩個版本，引用兩個來源，
標記為矛盾。不要選擇其中一個。
搜尋工具無法使用
條件：Brave Search MCP 沒有回應
檢測：工具呼叫回傳錯誤
回應：記錄失敗。透過 Telegram 通知。
儲存部分摘要並附註：「搜尋功能不可用 —
摘要僅基於記憶脈絡。」
不要靜默失敗。
摘要將重複昨天的頭條
條件：最重要的發展與昨天相同
檢測：與記憶中昨天的摘要交叉比對
回應：標註「來自 [日期] 的持續發展」，
並專注於今天具體的新內容。
品質標準
優秀的摘要：4-6 個訊號項目。每個項目都相關。
至少一個跨主題見解。閱讀時間少於 5 分鐘。
可接受的摘要：3 個訊號項目。全部相關。
無跨主題見解。閱讀時間少於 5 分鐘。
不可接受的摘要：少於 3 個訊號項目。
任何泛泛而談或與當前工作不相關的項目。
任何與過去 3 次摘要重複的項目。
建構品質驗證層
品質驗證層是區分「能產出穩定結果的 agent」與「產出變異結果的 agent」的關鍵。
大多數 agent 完全跳過這一層。它們生成一個輸出然後直接回傳。品質完全取決於生成當時的狀態。有些工作 session 表現很好，有些則平庸。你永遠不知道會得到哪一種。
品質驗證層透過檢查每個輸出是否符合定義的標準，並在標準未被滿足時以具體修正為目標重試，來讓輸出品質保持一致。
以下是實現品質驗證的 Claude API 呼叫模式：
async function executeWithQualityVerification(prompt, qualityStandard, maxRetries = 3) {
let attempt = 0;
let lastOutput = null;
let lastFailure = null;
while (attempt < maxRetries) {
// 生成輸出
const response = await fetch('https://api.anthropic.com/v1/messages', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': process.env.ANTHROPIC_API_KEY,
'anthropic-version': '2023-06-01'
},
body: JSON.stringify({
model: 'claude-opus-4-8',
max_tokens: 4096,
messages: [
{
role: 'user',
content: attempt === 0
? prompt
: ${prompt}
Previous attempt failed quality check: ${lastFailure}
Correct specifically for this failure. Do not rewrite everything.
}
]
})
});
const data = await response.json();
lastOutput = data.content[0].text;
// 驗證品質
const verificationResponse = await fetch('https://api.anthropic.com/v1/messages', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': process.env.ANTHROPIC_API_KEY,
'anthropic-version': '2023-06-01'
},
body: JSON.stringify({
model: 'claude-opus-4-8',
max_tokens: 1000,
messages: [
{
role: 'user',
content: `You are a quality checker. Evaluate this output against these standards:
${qualityStandard}
Output to evaluate:
${lastOutput}
Respond with ONLY:
PASS if the output meets all required standards
FAIL: [specific description of what failed] if it does not meet required standards
Do not explain. Do not suggest improvements. Just PASS or FAIL with specific failure description.`
}
]
})
});
const verificationData = await verificationResponse.json();
const verificationResult = verificationData.content[0].text.trim();
if (verificationResult.startsWith('PASS')) {
return { output: lastOutput, attempts: attempt + 1, passed: true };
}
lastFailure = verificationResult.replace('FAIL:', '').trim();
attempt++;
}
// 所有重試次數已用完
return {
output: lastOutput,
attempts: maxRetries,
passed: false,
failure: lastFailure
};
}
這個模式會生成輸出，根據定義的標準檢查，並在失敗時以具體修正為目標重試。如果所有重試都失敗，它會回傳最佳輸出以及一個失敗標記，而不是直接崩潰。
記憶整合模式
記憶是將一個有能力的 agent 轉變為一個會學習的 agent 的關鍵。
沒有記憶，每個工作 session 都從零開始。Agent 不知道自己做過什麼。它無法應用過去執行中學到的經驗。它無法避免已經犯過的錯誤。
有了記憶，每個工作 session 都建立在上一個的基礎上。Agent 知道什麼有效、什麼無效。它應用累積的脈絡來改善當前的輸出。它會隨著時間在特定任務上變得越來越好。
以下是任何 Claude agent 的記憶整合模式：
在每次執行開始時：
讀取標記為 [TASK-TAG] 的記憶項目。
限制：最多 20 個最相關的項目。
策略：相關性（不只是時間新舊）。
應用此脈絡：
- 注意先前執行中的模式
- 注意先前遇到的邊界情況
- 注意先前識別出的品質問題
- 將學到的經驗應用於當前執行
在每次執行結束時：
存入記憶：
date: [今天]
task: [任務名稱]
quality: [優秀/可接受/失敗]
noteable: [任何值得記住的事]
edge_case: [遇到的任何邊界情況]
pattern: [觀察到的任何模式]
標記：[TASK-TAG], [DATE]
每月整合：
讀取所有標記為 [TASK-TAG] 的記憶項目。
識別：
- 跨越多個項目出現的模式
- 重複出現的邊界情況
- 重複出現的品質問題
- 優秀輸出 vs 可接受輸出之間的相關因素
整合為單一更新後的脈絡項目。
將超過 90 天的個別項目封存。
失敗復原系統
真實世界的 agent 會遇到失敗。來源離線、API 速率限制、檔案不在預期位置、輸出在最大重試次數後仍未通過品質檢查。
失敗復原系統決定了這些失敗是看不見的小插曲，還是災難性的停擺。
三層次的失敗處理：
第一層：自動復原
可透過重試解決的暫時性失敗。工具不可用、網路超時、觸發速率限制。
第一層復原協定
在任何工具呼叫失敗時：
- 等待 60 秒
- 重試完全相同的呼叫
- 如果重試成功：正常繼續，記錄此小插曲
- 如果重試失敗：升級至第二層
第二層：優雅降級
無法解決但允許部分完成的失敗。某個來源不可用、某個工具無回應、輸出的某個部分未通過品質檢查。
第二層復原協定
在無法解決的部分失敗發生時：
- 完成可以完成的部分
- 具體記錄跳過了什麼以及原因
- 在檔案名稱中標記輸出為部分輸出
- 在輸出本身中包含明確的說明
- 發送通知：「部分輸出 — [具體原因]」
- 不要因為某個元件失敗而讓整個任務失敗
第三層：優雅停止
使整個任務無法執行的失敗。找不到 CLAUDE.md、輸出路徑不可寫入、記憶資料庫無法存取。
第三層復原協定
在完全失敗發生時：
- 識別具體的失敗點
- 將任何已完成的工作儲存至暫存位置
- 記錄完整的失敗脈絡
- 發送通知：「任務失敗 — [具體原因]」
- 乾淨地停止，不損壞任何現有輸出
- 不要自動重試 — 等待人工介入
在部署前測試你的 Agent
真實世界 agent 部署中最常見的錯誤就是跳過結構化測試。
在任何 agent 上線前，進行三個測試階段：
第一階段：元件測試
在測試整個工作流程之前，先單獨測試每個元件。
測試記憶是否持續存在
hermes chat
你儲存的最舊的記憶項目是什麼？
預期：應回報一個項目或回報資料庫為空
如果回傳錯誤：記憶設定有誤
測試工具存取權限
列出 [OUTPUT PATH] 中的檔案
預期：應列出實際檔案
如果回傳錯誤：filesystem MCP 設定不正確
測試搜尋
搜尋「AI news today」並告訴我第一個結果
預期：應回傳實際搜尋結果
如果回傳錯誤：Brave Search MCP 設定不正確
第二階段：Happy Path 測試
在乾淨的標準輸入上手動執行技能，並驗證輸出是否符合品質標準。
手動執行技能
hermes run research-brief
檢查輸出
cat outputs/briefings/[今天]-morning-brief.md
根據品質標準驗證：
- 至少 3 個訊號項目？
- 每個項目都與當前工作相關？
- 沒有泛泛分析？
- 閱讀時間少於 5 分鐘？
第三階段：邊界情況測試
刻意觸發每個記錄的邊界情況，並驗證復原行為。
測試：無網路連線
在 .env 中停用 Brave Search
執行技能
預期：第三層失敗，乾淨停止，發送通知
測試：輸出路徑不可寫入
將 OUTPUT_PATH 改為不存在的目錄
執行技能
預期：第三層失敗，乾淨停止，發送通知
測試：新聞較少的一天
在週末或假日執行
預期：第二層輸出，COVERAGE NOTE 標示為新聞較少
在生產環境中執行你的 Agent
一旦所有三個測試階段都通過，設定排程器並移至生產環境。
{
"schedules": [
{
"skill": "research-brief",
"cron": "0 6 *",
"description": "每天上午 6 點",
"timeout_minutes": 15,
"on_failure": "notify_and_stop"
}
]
}
以背景模式啟動 Hermes：
npm run start -- --daemon
驗證第一次排程執行：
檢查上午 6 點後的日誌
cat logs/hermes-[日期].log
檢查輸出是否已產出
ls outputs/briefings/
檢查記憶是否已更新
hermes chat
你有多少個 research-brief 記憶項目？
如果第一次自動執行產出了良好的輸出，那麼你的 agent 就已經在生產環境中了。
第三個月會有什麼變化
第一個月：Agent 穩定運作。輸出一致。失敗處理優雅。你每天早上省下 45 分鐘。
第二個月：記憶層開始產生明顯的改善。Agent 已經處理了六十天的來源資料，累積了對哪些來源產出高訊號內容、哪些只是雜訊的判斷依據。訊號過濾的品質提升了，因為 Agent 已經學會哪些來源值得持續追蹤。
第三個月：記憶整合已經運行了兩次。Agent 在九十天的研究範圍中辨識出模式。摘要中參照了累積的上下文，讓它們比任何單次研究產出的結果更紮實、更具體。
第三個月的 Agent，並不是在執行與第一個月相同的工作流程。
它執行的是該工作流程的改良版本，背後有九十天累積的運營智慧作為基礎。
這就是教程 Agent 與真實世界 Agent 之間的差異。
教程 Agent 只是完成任務。
真實世界 Agent 則學會如何把任務做得更好。
用這個週末打好基礎。
讓它跑一週。修復出錯的地方。
讓它跑一個月。看著它進步。
讓它跑三個月。注意它學到的東西，那些是你第一天根本無法告訴它的知識。
這就是打造一個能在真實世界中運作的 Claude Agent 的真實樣貌。
追蹤 @cyrilXBT 取得所有能讓你的 Claude Agent 在真實世界中存活下來的 Agent 架構、技能模板與生產部署模式。
