Claude Academy

Claude 是 Anthropic 開發的 AI 助理，你可能已經在網頁版、App、或某個工具的「AI 功能」背後見過它。但「Claude」不是單一一個東西——它其實是一整個模型家族的名字，背後撐著這個家族的公司叫 Anthropic，2021 年由一群曾在其他 AI 實驗室工作的研究者創立，成立宗旨很直白：確保通用 AI（transformative AI）的發展是安全、有益的，而不是先衝規模再回頭補安全。這也是為什麼 Anthropic 常被稱作一家「AI 安全公司」——安全不是附加條款，是創業的起點。

Claude 這個名字取自資訊理論之父 Claude Shannon，算是向「用數學馴服複雜系統」的傳統致敬。你在市面上看到的 Claude，不是只有一個版本在運作，而是分成 Opus、Sonnet、Haiku 三個系列，各自對應不同的能力、速度、成本組合——這件事會在後面幾課細講。現在你只需要知道：選 Claude，其實是在選一整個工具箱，而不是一把固定的槌子。

• Anthropic 是 2021 年成立的 AI 安全公司，使命是確保先進 AI 安全有益
• Claude 是 Anthropic 開發的 AI 助理／模型家族的名稱，不是單一模型
• Claude 之名來自資訊理論之父 Claude Shannon
• Claude 模型家族分成 Opus、Sonnet、Haiku 三個系列
• 選擇用哪個 Claude，其實是在能力、速度、成本間做取捨

如果你的印象還停留在「Claude 就是一個聊天機器人」，那該更新一下了。日常對話當然是最基本的用法——問問題、腦力激盪、潤稿，這些 Claude 都做得順手。但往上一層，Claude 更擅長長文件理解與分析：丟一份幾十頁的合約、財報、研究論文進去，它可以抓重點、找矛盾、做摘要，這靠的正是夠大的 context window（上下文視窗），下一課會細講。

寫程式是 Claude 另一個被大量依賴的場景，從讀懂一整個程式碼庫、抓 bug，到直接生成可執行的功能，Claude Code 這類工具讓它從「寫程式建議」進化成「真的動手改程式碼」。再往上，Claude 具備 tool use（工具使用）能力，能呼叫外部 API、查資料庫、執行搜尋，把自己從「只會講」的助理變成「講完還會做」的 agent（代理人）——查天氣、訂票、跑分析全部自己接手完成中間步驟，不用你一步步餵指令。

• 基礎能力：日常對話、腦力激盪、潤稿
• 進階能力：長文件理解與分析，靠夠大的 context window 支撐
• 寫程式：讀懂程式碼庫、抓 bug、生成功能，Claude Code 是代表工具
• tool use 讓 Claude 能呼叫外部 API、查資料，不只是回答文字
• agent（代理人）模式：Claude 自主串連多個步驟完成任務，不需逐步下指令

Opus、Sonnet、Haiku 這三個名字，你可以直接理解成「重型、中型、輕型」三種交通工具。Opus 是家族裡推理能力最強的一款，面對複雜的多步驟邏輯、艱深的研究問題、需要深度思考的策略規劃，它的表現最扎實，但相對的回應速度較慢、運算成本也較高。Sonnet 走的是平衡路線，在能力和速度之間抓一個「大多數任務都夠用」的甜蜜點，是很多正式產品、日常開發工作的預設選擇。Haiku 則是為速度和成本優化的輕量款，回應快、費用低，很適合客服快速回覆、大量重複性的分類或抽取任務、或是需要毫秒級反應的即時應用。

選模型的原則很簡單：先問「這個任務需要多深的推理？」再問「用量大不大、延遲敏感不敏感？」一個處理數萬筆訂單分類的批次任務，用 Opus 是殺雞用牛刀，錢跟時間都浪費；但一個需要拆解法律合約矛盾點的任務，用 Haiku 可能會漏掉關鍵細節。實務上很多團隊會混用——用 Haiku 做初篩、Sonnet 做主力、Opus 處理少數真正棘手的案例。

• Opus：推理能力最強，適合複雜多步驟任務，速度與成本較高
• Sonnet：能力與速度的平衡點，多數正式應用的預設選擇
• Haiku：速度快、成本低，適合大量、簡單、延遲敏感的任務
• 選模型看兩個問題：任務推理深度、以及用量與延遲需求
• 實務常見做法：依任務難度混用多個模型分層處理

你可能遇過 Claude 委婉拒絕某個請求，或是明明只是想開玩笑卻被它一本正經地提醒風險。這不是系統故障，而是 Anthropic 從訓練階段就刻意設計的行為，方法論的核心叫 Constitutional AI（憲法式 AI）。傳統訓練安全模型的做法，很依賴大量人工標註「這個回答好不好、有沒有害」，成本高、標準也容易因人而異。Constitutional AI 換了個做法：先給模型一套明確的原則（憲法），讓模型依照這套原則自己批評、修正自己的回答，再用這個過程產生的資料去訓練，大幅減少對人工標註有害內容的依賴。

這套機制的目標，是讓 Claude 在「有幫助」（helpful）和「無害」（harmless）之間找到平衡，而不是走極端。走太偏有幫助那端，模型可能配合任何要求，包含真的有風險的；走太偏無害那端，模型會變得動不動就拒絕、對正常請求也疑神疑鬼，體驗很差。你偶爾感受到的「過度謹慎」，其實就是這個平衡點還在調校的證據——而不是 Claude 存心跟你作對。理解這個背景，你就更容易判斷什麼時候該換個問法，而不是單純覺得被卡住。

• Claude 偶爾的拒絕或提醒，來自訓練時設計的安全機制，不是系統錯誤
• Constitutional AI（憲法式 AI）用一套明確原則讓模型自我批評、自我修正
• 這種方法減少了對大量人工標註「有害內容」的依賴
• 目標是在「有幫助」與「無害」之間取得平衡，不走極端
• 感覺被過度拒絕時，換個更明確、說明正當用途的問法通常有效

很多人寫 prompt 的方式，就是把心裡想的話原封不動打出來，然後對結果失望。問題往往不是 Claude 不夠聰明，是 prompt 本身缺了結構。一個穩定好用的 prompt，通常可以拆成四個部分：角色（role）、脈絡（context）、任務（task）、格式（format）。角色告訴 Claude「你現在是誰」，例如「你是一位資深法務顧問」，這會影響它用什麼語氣、站在什麼專業角度回答。脈絡是背景資訊——你的公司、你的讀者是誰、這份輸出要用在哪裡，缺了脈絡，Claude 只能用最通用、最安全的方式猜。

任務是具體要做的事，動詞要明確：「摘要」「比較」「改寫」「找出風險」都比籠統的「幫我看一下這個」有效。格式則是輸出長相的規格——要條列還是段落、要不要表格、字數上限、要不要中英夾雜。這四塊不是每次都要寫滿，但你可以把它當成一張檢查清單：結果不如預期時，回頭看是不是漏了角色、脈絡、任務、還是格式其中一塊，通常就能抓出問題在哪。

• 好 prompt 可拆成四塊：角色、脈絡、任務、格式
• 角色決定語氣與專業視角，脈絡補足背景資訊
• 任務要用明確動詞描述，避免籠統的請求
• 格式規定輸出長相：條列/段落、字數、要不要表格等
• 結果不理想時，可用這四塊當檢查清單回頭排查問題

如果只能學一個 prompt 技巧，很多實務工作者會選 few-shot prompting（少樣本提示）。概念很簡單：與其一直用文字描述你要的格式和風格，不如直接給 Claude 看一兩個「輸入 → 輸出」的範例，讓它照著範例的樣子做，而不是照你的文字說明去猜。相對的，完全不給範例、只靠文字指令的做法叫 zero-shot（零樣本），能用但精準度通常比較低，尤其是輸出格式比較特殊或風格要求很細的時候。

few-shot 特別有效的場景，是那些「用文字很難講清楚，但看範例秒懂」的任務：客服信件的語氣拿捏、資料抽取要輸出的精確欄位順序、程式碼註解的風格。你只需要給 2-3 個具代表性的範例，涵蓋一般情況和至少一個邊界案例，Claude 就能抓到規律並套用到新的輸入上。範例的品質比數量重要——三個精挑細選、真的反映你要的結果的範例，勝過十個隨便湊的。

• few-shot prompting：給 1-3 個「輸入→輸出」範例讓模型模仿
• zero-shot：只靠文字指令、不給範例，精準度通常較低
• few-shot 特別適合語氣、格式、風格難以純用文字描述的任務
• 範例品質比數量重要，2-3 個精準範例通常就夠
• 建議至少包含一個邊界案例，讓模型學到規則的界線

面對需要多步驟推理的問題，直接要 Claude 給答案，常常會得到一個「看起來合理但沒細想過」的結果。chain of thought（思考鏈，簡稱 CoT）的做法很直覺：明確請 Claude「先一步步想清楚，再給出最終答案」。這個簡單的指示，會讓模型把中間的推理過程寫出來，而不是直接跳到結論——寫出來的過程本身也會提升最終答案的品質，因為模型是照著自己寫下的邏輯繼續往下推，比腦內直接跳答案更不容易漏掉步驟。

要讓思考過程和最終答案不混在一起，一個好用的技巧是用 XML 標籤組織 prompt 和期待的輸出，例如請 Claude 把推理放進 <thinking>...</thinking>，把要交付的答案放進 <answer>...</answer>。Claude 對 XML 標籤的結構特別敏感、遵循度高，這也是為什麼很多正式 prompt 會用 <context>、<document>、<instructions> 這類標籤把長 prompt 的不同區塊清楚分開，而不是全部擠成一大段文字。區塊分清楚了，Claude 比較不會把「參考資料」和「要執行的指令」搞混。

請先在 <thinking> 標籤中列出你的推理步驟，
再把最終結論寫在 <answer> 標籤中。

<context>
（這裡放參考資料或背景文件）
</context>

<instructions>
請根據以上 context，判斷這份合約是否有隱藏的自動續約條款。
</instructions>

• chain of thought（思考鏈）：請模型先寫推理過程，再給最終答案
• 寫出中間步驟能提升複雜任務的答案品質，減少跳步驟出錯
• Claude 對 XML 標籤遵循度高，適合用來切分 prompt 的不同區塊
• 常見標籤：<thinking>、<answer>、<context>、<instructions>
• 把推理過程和最終答案分開放，方便你只取用你要的那一段

Prompt 寫不好，症狀通常長得很像：答非所問、格式亂跳、明明說了不要卻還是做了。第一個常見病因是指令模糊——「幫我優化這份文案」太籠統，Claude 只能猜你想優化的是長度、語氣、還是說服力，猜錯了你會覺得它「不聽話」，但問題其實出在指令本身沒講清楚要優化哪個面向。第二個常見病因是一次塞太多任務——一段 prompt 裡同時要求摘要、翻譯、抓風險、寫建議，模型的注意力被分散，每件事都做得普普，不如拆成幾次請求或用清楚的分點列出優先順序。

第三個是過度依賴 negative instruction（負面指令），像是「不要用被動語態」「不要太長」。負面指令只告訴模型「不要做什麼」，卻沒說「要做什麼」，效果通常比正面描述弱，把「不要用被動語態」換成「全程用主詞開頭的主動句」，模型更容易照做。除錯的方法也很直接：先把 prompt 拆解回角色、脈絡、任務、格式四塊檢查有沒有缺漏；用小範例先測，觀察模型輸出卡在哪一步；懷疑是任務太多，就先拆分成單一任務測試，確認每一塊都對了，再組回完整版本。

• 常見失敗一：指令模糊，模型只能用最通用的方式猜測意圖
• 常見失敗二：一次塞太多任務，拆分成單一任務通常效果更好
• 常見失敗三：過度依賴負面指令，正面描述「要做什麼」更有效
• 除錯第一步：回頭檢查角色、脈絡、任務、格式是否有缺漏
• 除錯第二步：用小範例測試、拆解任務逐一排查卡點

要讓 Claude 接進你自己的程式或產品，起點是申請一把 API key——在 Anthropic 的開發者主控台（Console）建立帳號後就能產生，這把 key 是你的身分憑證，要當密碼一樣保管，不要寫進會被公開的程式碼或上傳到公開的程式碼庫。拿到 key 之後，你會透過官方提供的 SDK（Python、TypeScript 都有）呼叫 Messages API（訊息 API），這是目前 Claude API 的核心介面，取代了早期比較陽春的 completion 介面。

一次呼叫最基本要準備三樣東西：要用哪個 model（模型代號）、這次回應的 max_tokens 上限、以及 messages 陣列——裡面放使用者說的話。API 回傳的結果裡，實際文字內容放在 content 欄位，是一個區塊（block）的陣列，因為 Claude 的輸出除了文字，未來也可能包含其他類型的區塊（例如工具呼叫，第四章會講到）。第一次呼叫成功、印出模型的回覆，是接下來所有進階用法——多輪對話、工具串接、串流輸出——的共同起點。

import anthropic

client = anthropic.Anthropic(api_key="你的 API key")

message = client.messages.create(
    model="你選用的 Claude 模型代號",  # 實際代號請查官方文件
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "用一句話介紹台北 101"}
    ]
)

print(message.content)

• 呼叫 Claude API 前要先在 Console 申請 API key，需妥善保管不外流
• Messages API 是目前呼叫 Claude 的核心介面
• 一次呼叫至少要指定 model、max_tokens、messages 三樣
• messages 是陣列，裡面放對話中每一句話與說話者角色
• 回傳結果的 content 是區塊陣列，可能包含文字以外的類型

呼叫 Messages API 時，除了必要的 model、messages，還有幾個參數會直接影響輸出的樣子和品質。system 是一個獨立於 messages 陣列之外的頂層參數，用來設定「這次對話 Claude 要扮演什麼角色、遵守什麼規則」——例如「你是一個只用繁體中文回答、語氣正式的客服助理」。把角色設定放進 system 而不是塞進第一句 user 訊息，效果通常更穩定，也更不容易被使用者後續的訊息覆蓋掉。

max_tokens 是必要參數，設定這次回應最多能生成多少 token（權杖，語言模型處理文字的基本單位），太小會讓長回答被硬生生截斷，太大則沒有實際意義只是留了空間。temperature 控制輸出的隨機性，範圍通常在 0 到 1 之間：數值低（接近 0）代表模型會偏好選擇最有把握的字詞，回答比較穩定、適合需要一致性的任務，例如資料抽取、程式碼生成；數值高則輸出更有變化、適合需要創意發散的任務，例如寫文案、腦力激盪。同一個 prompt，光是調整 temperature，拿到的個性可能完全不一樣。

message = client.messages.create(
    model="你選用的 Claude 模型代號",
    max_tokens=1024,
    system="你是一位只用繁體中文回答的客服助理，語氣親切但專業。",
    temperature=0.3,
    messages=[
        {"role": "user", "content": "訂單還沒到怎麼辦？"}
    ]
)

• system 是頂層參數，用來設定角色與規則，比塞進 user 訊息更穩定
• max_tokens 是必要參數，設定這次回應最多能生成的 token 數量
• temperature 控制輸出隨機性，範圍常見是 0 到 1
• temperature 低：穩定一致，適合資料抽取、程式碼等任務
• temperature 高：更有創意變化，適合文案發想、腦力激盪

Claude API 本身是無狀態（stateless）的——它不會幫你記住上一次呼叫聊了什麼，每一次呼叫都是全新的。要做出「記得前面聊過什麼」的多輪對話，責任在你這邊：把每一輪的使用者訊息和 Claude 的回覆都存下來，下一次呼叫時把完整的歷史（history）連同新的問題一起放進 messages 陣列，並且維持 user、assistant 角色交替出現。歷史留得越完整，Claude 的回答就越能接上前文，但也代表每次呼叫要傳送和處理的內容越多。

串流（streaming）解決的是體驗問題：預設情況下你要等 Claude 把整段回應生成完才會拿到結果，字數一長，使用者會盯著空白畫面等好幾秒。開啟串流後，文字會像打字機一樣一段段即時吐出來，讓使用者感覺回應「馬上開始」，特別適合聊天介面。視覺輸入（vision）則是讓 Claude 不只讀文字，也能看圖——把圖片以 base64 編碼或圖片網址放進 content 區塊裡，就能請它描述截圖、讀圖表數字、辨認照片裡的物件，這對處理發票、圖表、UI 截圖這類任務特別實用。

messages = [
    {"role": "user", "content": "台北明天會下雨嗎？"},
    {"role": "assistant", "content": "目前資訊有限，建議查氣象局預報。"},
    {"role": "user", "content": "那我該帶傘嗎？"},
]

with client.messages.stream(
    model="你選用的 Claude 模型代號",
    max_tokens=512,
    messages=messages,
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

• Claude API 是無狀態的，多輪對話的歷史要由你自己保存並每次傳入
• messages 陣列需維持 user、assistant 角色交替
• 串流讓文字逐段即時輸出，改善使用者等待體驗
• 視覺輸入可在 content 區塊放入圖片，讓 Claude 讀圖表、截圖、照片
• 歷史留得越完整，回答越能接上前文，但傳輸與處理量也越大

API 用量一大，成本就會變成認真要管理的事，Anthropic 提供兩個機制專門處理這個問題。第一個是 prompt caching（提示詞快取）：如果你的 prompt 裡有一大段內容是重複、不太會變的——例如很長的 system 指示、固定的參考文件、範例集——你可以把這段內容標記為可快取，之後的呼叫只要內容沒變，Claude 就不用重新「處理」這段一模一樣的內容，能明顯降低延遲和成本。特別適合那種「一份長文件、被問很多次不同問題」的場景，例如針對同一份合約反覆提問。

第二個是 Batch API（批次 API），針對的是「不急著馬上拿到結果」的大量請求，例如晚上要把一整天累積的十萬筆客服訊息做情緒分類。你把所有請求打包一次送出，Anthropic 在背景非同步處理，通常在一定時間內完成，換來的是比即時呼叫更低的單位成本。兩者的判斷邏輯不同：prompt caching 解決「同樣的內容被重複使用」，Batch API 解決「大量但不急」。實務上常常兩個一起用，把重複的長文件快取起來，再把大量非即時的請求丟進批次處理。

• prompt caching：把重複、不常變動的長內容標記快取，降低延遲與成本
• prompt caching 適合場景：同一份長文件被反覆提問的情境
• Batch API：把大量不急迫的請求打包非同步處理，單位成本更低
• Batch API 適合場景：離線分析、大量分類、報表產出等背景任務
• 實務上常兩者併用：快取重複內容 + 批次處理大量請求
• 實際費率與折扣幅度請以官方 pricing 頁面為準

Claude 本身是一個語言模型，它擅長理解和生成文字，但它不會憑空知道「現在台北的氣溫」，也沒辦法真的幫你查資料庫、算今天的匯率、或是預訂一張機票——這些都需要接到外部系統。tool use（工具使用，有時也稱 function calling）就是解決這個落差的機制：你先把可用的工具描述給 Claude 聽（這個工具叫什麼名字、做什麼事、需要什麼參數），Claude 在對話過程中如果判斷「這個問題需要用工具才能回答」，就會回傳一個結構化的請求，說明它想呼叫哪個工具、帶什麼參數，而不是自己亂猜答案。

要注意的是，Claude 本身並不會真的去執行工具——呼叫外部 API、查資料庫這些動作，是你的程式碼負責執行的，Claude 只負責「判斷該用哪個工具、該帶什麼參數」這個決策層。執行完之後，你把結果回傳給 Claude，它才會根據真實的結果組織成人話回覆使用者。這個設計讓 Claude 從「只會講」升級成「講完還能接手動作」，是 agent（代理人）能自主完成多步驟任務的核心機制，後面幾課會細講這個來回的完整迴圈。

• tool use（工具使用）讓 Claude 能在回答中判斷「這題需要查外部資訊」
• Claude 只負責決定要呼叫哪個工具、帶什麼參數，不會自己執行
• 實際執行工具（呼叫 API、查資料庫）是由你的程式碼負責
• 執行結果要回傳給 Claude，它才能組織成最終的自然語言回覆
• tool use 是 agent 能自主完成多步驟任務的核心機制

定義一個工具，本質上是在填三件事：name（工具名稱）、description（工具描述）、input_schema（輸入參數的 JSON Schema）。很多人以為 name 取得清楚就夠了，但實務上 description 才是決定 Claude 用不用得對這個工具的關鍵——它讀的是你寫的描述文字，不是你腦中的意圖。一個模糊的描述像「查詢資料」，Claude 很難判斷什麼情境該用它；一個具體的描述像「查詢指定城市今天的天氣狀況與攝氏氣溫，僅支援台灣縣市」，Claude 才能準確判斷這個工具適不適合眼前這個問題。

input_schema 用標準的 JSON Schema 格式定義參數，包含每個參數的型別、是否必填、以及同樣重要的參數描述。參數命名和描述一樣不能馬虎——city 這個參數如果描述寫「城市名稱，例如台北」，Claude 傳進來的值就會比較穩定；什麼都不寫，模型可能會傳英文、簡體、或加上「市」字不一致的格式。工具描述沒寫好，最常見的症狀是 Claude 該用工具時沒用、不該用時亂用，或是參數格式對不上你程式碼預期的樣子——這些問題往往不是模型能力不夠，是 schema 寫得不夠精準。

tools = [
    {
        "name": "get_weather",
        "description": "查詢指定城市今天的天氣狀況與攝氏氣溫，僅支援台灣縣市。",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "城市名稱，例如：台北、台中、高雄"
                }
            },
            "required": ["city"]
        }
    }
]

• 定義工具要填 name、description、input_schema 三個部分
• description 是 Claude 判斷「該不該用這個工具」的主要依據
• description 越具體、越明確標示適用範圍，模型用得越準
• input_schema 用 JSON Schema 定義參數型別、必填與描述
• 一個工具只負責單一功能，通常比塞多個 mode 的萬用工具好用

理解 tool use 最重要的一步，是搞懂它其實不是「問一次答一次」，而是一個來回的迴圈，通稱 agentic loop（代理迴圈）。流程是這樣的：你發送請求給 Claude，並附上可用的工具列表；如果 Claude 判斷需要用工具，它回傳的 stop_reason（停止原因）會是 tool_use，內容裡包含它想呼叫的工具名稱和參數，而不是最終答案。你的程式碼這時要做的事，是真正執行那個工具（呼叫 API、跑查詢……），拿到結果後，把 Claude 上一輪的完整回覆和你執行的結果一起送回去——結果要包成一個 tool_result（工具結果）區塊，並且帶上對應的 tool_use_id，讓 Claude 知道這是哪一次呼叫的答案。

送出之後，Claude 會根據這個真實結果，決定要不要再呼叫另一個工具、還是已經有足夠資訊可以組織成最終文字回覆給使用者。這個迴圈可能只跑一輪（查一次天氣就夠了），也可能連續跑好幾輪（先查匯率、再查商品價格、最後算出換算後金額）——迴圈會一直持續，直到 Claude 判斷不再需要工具、回傳 stop_reason 為 end_turn 的最終回答為止。這就是為什麼 agent 能自主完成多步驟任務：迴圈的每一輪，都是模型根據新資訊重新做一次判斷。

response = client.messages.create(
    model="你選用的 Claude 模型代號",
    max_tokens=1024,
    tools=tools,
    messages=messages,
)

if response.stop_reason == "tool_use":
    tool_call = next(b for b in response.content if b.type == "tool_use")
    result = run_tool(tool_call.name, tool_call.input)

    messages.append({"role": "assistant", "content": response.content})
    messages.append({
        "role": "user",
        "content": [{
            "type": "tool_result",
            "tool_use_id": tool_call.id,
            "content": str(result),
        }],
    })
    # 再送出一次 messages.create(...)，迴圈繼續

• agentic loop：請求 → Claude 回 tool_use → 你執行 → 回傳 tool_result → 繼續
• stop_reason 為 tool_use 時，代表 Claude 想呼叫工具、還沒給最終答案
• tool_result 要帶上對應的 tool_use_id，讓 Claude 知道這是哪次呼叫的結果
• 迴圈可能一輪就結束，也可能連續多輪，視任務需要幾個步驟
• stop_reason 變成 end_turn，代表 Claude 已組織出最終回覆

tool use 除了拿來串接真正的外部功能，還有一個很實用的延伸用法：強制 Claude 輸出結構化資料。做法是定義一個「假工具」——它不真的執行任何動作，input_schema 就是你想要的資料格式，例如「從這段文字抽取出姓名、日期、金額」。搭配 tool_choice 參數指定要求 Claude 必須呼叫這個工具（而不是自由決定要不要用），Claude 就會把答案套進你定義好的 schema 裡回傳，而不是生成一段可能格式跑掉的自由文字。這比要求 Claude「請用 JSON 格式回答」穩定得多，因為 schema 本身就是規格，不是一句期待模型自己遵守的口頭指示。

有了 schema 保底，錯誤處理還是不能省。工具的輸入可能不完整、外部 API 可能逾時或回傳錯誤、Claude 傳來的參數也可能和你預期的格式對不上。穩健的做法是：執行工具前先驗證輸入（缺必要欄位就直接拒絕，不要硬跑）；執行失敗時，把錯誤訊息也包進 tool_result 回傳給 Claude（可以標記 is_error），讓它有機會根據錯誤內容調整、重試或換個工具，而不是讓整個流程直接崩潰；對外部依賴設定合理的逾時和重試次數，避免一次呼叫卡住整個 agentic loop。

• 定義一個「假工具」、schema 就是想要的資料格式，可強制拿到結構化輸出
• 搭配 tool_choice 要求 Claude 必須呼叫該工具，比純文字要求 JSON 更穩定
• 執行工具前應先驗證輸入，缺必要欄位就不要硬跑
• 工具執行失敗要把錯誤訊息誠實回傳給 Claude，讓它能調整或重試
• 對外部依賴設定逾時與重試上限，避免卡住整個 agentic loop
• 錯誤處理不完整時，不要用假資料頂替，會讓後續推論建立在錯誤前提上

在 MCP（Model Context Protocol，模型情境協定）出現之前，如果你想讓 Claude 讀你的 Google Drive、查你的資料庫、又順便叫 Slack 發訊息，每一個都要各家自己寫一套串接邏輯。假設你有 M 個 AI 應用（Claude Desktop、Claude Code、其他 agent 框架⋯），又想接 N 個外部系統（GitHub、Notion、資料庫、內部 API⋯），沒有共同協定的世界裡，你得寫 M×N 種客製整合，任何一邊變動，整條線都要重接。這就是所謂的「N×M 整合問題」。

MCP 的想法很單純：定義一套所有人都遵守的協定，讓「應用端」和「工具端」各自只需要對協定講一次話，不用互相遷就。這樣一來，整合數量從 M×N 降成 M+N——每個應用寫一次 MCP client、每個系統寫一次 MCP server，就能任意組合，不用再為每一對關係各寫一份客製程式。

• 沒有共同協定時，M 個應用 × N 個系統 = M×N 種客製整合，維護成本隨兩邊成長而爆炸
• MCP（Model Context Protocol，模型情境協定）是 Anthropic 提出、開放的協定標準
• 有了 MCP，整合量從 M×N 降成 M+N：應用寫一次 client、系統寫一次 server
• 常被比喻成「AI 應用的 USB-C」：統一的接頭，任何相容裝置都能接上
• 對工具開發者來說，寫一個 MCP server 就能被所有支援 MCP 的應用重複使用
• 對應用開發者來說，接上 MCP client 就能瞬間取用整個生態系已經寫好的 server

MCP 的架構分成三個角色。Host（主機）是使用者實際互動的應用程式，例如 Claude Desktop、Claude Code，或是你自己寫的 agent 程式；它負責管理整個對話、決定要不要把某個工具結果交給模型。Client（客戶端）活在 host 裡面，每個 client 對應一個 server，負責用協定跟那個 server 講話——傳送請求、接收結果、維持連線狀態；一個 host 通常會同時開好幾個 client，各自連到不同的 server。

Server（伺服端）則是實際提供能力的那一方，例如「GitHub MCP server」知道怎麼查 issue、開 PR；「檔案系統 MCP server」知道怎麼讀寫本機檔案。Server 不需要知道自己被哪個 host 使用，也不用管背後是哪個模型，它只要遵守協定就能被任何相容的 client 接上。三者的分工可以簡化成一句話：host 管對話、client 管連線、server 管能力。

• Host：使用者實際互動的應用（Claude Desktop、Claude Code 等），管理整體對話與決策
• Client：存在於 host 內部，一對一連接一個 server，負責協定層的溝通
• Server：實際提供 tools／resources／prompts 能力的一方，可以是本機程式或遠端服務
• 一個 host 可以同時管理多個 client，等於同時接上多個 server
• Server 只需要遵守 MCP 協定，不需要知道是被哪個 host、哪個模型呼叫
• 這種分層讓 server 開發者和 host 開發者可以各自獨立演進，互不綁死

MCP server 能提供給 client 的能力，收斂成三種「原語」(primitives)。Tools（工具）是模型可以主動呼叫的函式，例如「查詢資料庫」「建立 GitHub issue」；它們的設計精神跟你在 CH04 學過的 tool use 一致——模型自己決定要不要呼叫、什麼時候呼叫、傳什麼參數。Resources（資源）是應用讀取的資料，例如一份檔案內容、一則資料庫紀錄、一段日誌；重點是 resources 通常由「應用」（host/client 端的程式邏輯或使用者）決定要不要抓進來，而不是模型自主呼叫，這跟 tools 的「模型主導」剛好相反。

Prompts（提示）是使用者觸發的範本，通常包在選單或斜線指令裡，例如「/summarize-pr」，讓使用者一鍵套用一段設計好的提示語，不用每次手打。三者的呼叫發起者不同：tools 由模型發起、resources 由應用發起、prompts 由使用者發起。分清楚這一點，設計自己的 server 時就知道某個能力該包成哪一種原語。

• Tools：模型可主動呼叫的函式，用來「做事」，例如查詢、寫入、執行動作
• Resources：應用讀取的唯讀資料，通常由應用邏輯或使用者決定要不要載入
• Prompts：使用者觸發的提示範本，常見於選單或斜線指令，幫使用者套用設計好的提示
• 三者的發起者不同：tools 由模型主導、resources 由應用主導、prompts 由使用者主導
• 設計 server 時，先想清楚這個能力「誰來決定要不要用」，再決定包成哪種原語
• 三大原語都定義在同一份協定裡，client 連上 server 後可以列出它支援哪些

理論講完，來實際接一個。不管是 Claude Desktop 或 Claude Code，設定現成 MCP server 的方式都類似：寫一段 JSON 設定，告訴 host 要怎麼啟動這個 server。最常見的是本機（stdio）型 server，host 會用你指定的指令把它跑起來，透過標準輸入輸出跟它講話。舉例來說，接上一個檔案系統 server 的設定大致長這樣：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]
    }
  }
}

存好設定、重啟應用後，host 會自動啟動這個 server 並列出它提供的 tools／resources／prompts，之後只要用自然語言請 Claude 操作，它就會在需要時自己呼叫對應的 tool。Claude Code 也支援用指令行直接新增 server，不用手動編輯 JSON，對第一次嘗試的人更省事。裝好之後第一件事，永遠是先問 Claude「你現在有哪些工具可以用」，確認 server 真的連上、能力清單符合預期，再開始正式操作。

• 現成 MCP server 通常透過一段 JSON 設定接上 host，指定啟動指令與參數
• 本機型 server 常用 stdio（標準輸入輸出）transport，host 直接把它當子行程啟動
• Claude Code 也提供指令行方式新增 server，不用手動寫 JSON
• 裝好後先請 Claude 列出目前可用的工具，確認連線成功、能力清單正確
• 連不上時，第一步永遠是檢查設定檔路徑與執行環境，而不是急著重裝
• 官方與社群都維護了現成 server 清單，涵蓋檔案系統、版本控制、資料庫等常見情境

接上別人寫好的 server 只是第一步，真正的威力在於你能把公司內部系統包成 MCP server，讓 Claude 直接操作。官方提供 Python（FastMCP）與 TypeScript 的 SDK，把協定細節都封裝好，你只需要專心定義「這個 server 提供什麼能力」。用 FastMCP 寫一個最小可用的 server 大概長這樣：

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("weather")

@mcp.tool()
def get_weather(city: str) -> str:
    """查詢指定城市的目前天氣"""
    return f"{city} 目前晴天，25 度"

if __name__ == "__main__":
    mcp.run()

這段程式碼定義了一個名叫 get_weather 的 tool，函式的 docstring／型別標註會被 SDK 自動轉成 tool 的 schema，也就是模型用來判斷「這個工具是做什麼、要傳什麼參數」的說明書——跟 CH04 學的 tool schema 是同一套精神。寫完之後啟動它，再把它接進 Claude Desktop／Claude Code 的設定裡測試。第一次寫的建議是：先做一個功能單純的 tool，確定整條路能通，再逐步加更多能力，不要一開始就想包山包海。

• 官方提供 Python（FastMCP）與 TypeScript SDK，封裝協定細節，讓你專心定義能力
• 用裝飾器（如 @mcp.tool()）搭配函式的型別標註與 docstring，SDK 會自動產生 tool schema
• Tool schema 的角色跟 CH04 的 tool use schema 相同：是模型判斷何時、如何呼叫的說明書
• 建議先做一個單純的 tool，打通「啟動、連線、呼叫、回傳」全流程，再逐步擴充
• Server 開發完成後，用本機設定接進 Claude Desktop 或 Claude Code 就能測試
• 一個 server 可以同時定義多個 tools、resources、prompts，彼此獨立註冊

到目前為止都是「client 呼叫 server」的方向，但 MCP 也定義了反過來的機制。Sampling 讓 server 在執行任務的過程中，回頭請 client 代打一次 LLM 呼叫——例如 server 收集到一堆資料，想先請模型幫忙摘要或判斷，但 server 本身沒有、也不該自己持有 API key，於是它把「幫我問一下模型」這個請求丟回 client，由 client 用使用者已經授權的模型額度去執行，結果再回傳給 server 使用。這樣的好處是：server 開發者不用管理自己的模型金鑰與費用，權限與成本控管都留在 client／使用者手上。

Elicitation 則是另一個方向的「求助」：server 在執行到一半，發現需要使用者提供額外資訊才能繼續（例如「你要刪除的是哪個檔案？」），它可以透過協定向 client 發出請求，由 client 跳出介面讓使用者回答，而不是自己亂猜或直接中斷。這兩個機制的共通點是：server 不是孤立運作，它可以在需要時把「思考」或「決策」的權力交還給 client 端。

• Sampling：server 請 client 代為呼叫 LLM，結果回傳給 server 繼續使用
• Sampling 的好處是 server 不需要自己管理模型金鑰與費用，成本與權限留在 client 端控管
• Elicitation：server 在執行過程中向使用者要額外輸入，透過 client 呈現互動介面
• 兩者都是「server 反向請求」的機制，跟平常 client 呼叫 server 的方向相反
• 使用這兩個機制時，client 通常仍會做確認或授權把關，不會無條件配合 server 的請求
• 善用這兩個機制能讓 server 的邏輯更靈活，不必把所有判斷都寫死在程式裡

前面的例子多半是本機 server，用 stdio transport（標準輸入輸出）跟 client 講話，適合單機工具，但沒辦法給團隊共用，也沒辦法給雲端服務用。這就是 remote MCP 要解決的問題：把 server 架成一個網路服務，用 streamable HTTP transport 讓任何地方的 client 都能連上——不只是你自己的電腦，也可以是雲端上跑的 agent。

本機 server 通常假設「跑起來的人就是使用者本人」，不太需要認證；但一旦 server 搬到網路上，任何人理論上都能連進來，就必須有認證機制確認「這個 client 到底代表誰在講話、有沒有權限」。MCP 採用業界標準的 OAuth 流程處理這件事：使用者透過瀏覽器登入、授權 client 可存取的範圍（scope），client 拿到 token 後才能繼續跟 server 溝通，之後每次請求都帶著 token 證明身分。重點不是背 OAuth 的每個步驟，而是建立一個原則：server 一旦離開你自己的機器，認證與授權就不是加分項，而是必要條件。

• 本機 server 常用 stdio transport，適合單機工具，難以給團隊或雲端服務共用
• Remote MCP 讓 server 架成網路服務，用 streamable HTTP transport 供任何地方的 client 連線
• Server 離開本機、成為網路服務後，認證與授權從「可選」變成「必要」
• MCP 採用 OAuth 這套業界標準流程處理授權：使用者登入、授權範圍、client 取得 token
• Client 之後的每次請求都帶著 token，讓 server 確認這個請求代表誰、能做什麼
• 部署 remote server 前，先確認認證機制到位，不要因為圖方便而先跳過

MCP 讓 Claude 能直接碰觸真實系統，威力越大，風險也越大，這一課整理幾個必須放在心上的安全原則。第一是 prompt injection（提示注入）：如果一個 tool 的回傳內容（例如一封信、一個網頁、一份文件）裡藏著偽裝成指令的文字，模型有可能把它當成使用者的新指示去執行，尤其是「幫我讀某個外部內容」這類 tool 特別危險。第二是 confused deputy（受騙的代理人）問題：server 本身權限很大（例如能存取整個資料庫），但呼叫它的人／模型未必該有那麼大的權限，如果 server 沒有做好授權檢查，就等於把自己的高權限借給了不該用的人。

第三是權限最小化：一個 server、一個 tool 該有的權限，就是完成任務所需的最小範圍，不要因為「以後可能用得到」就先開好所有存取權。第四是供應鏈信任：安裝別人寫的 server 前，要清楚它會存取什麼、程式碼是否可信，就像你不會隨便執行來路不明的程式一樣，接一個 MCP server 本質上也是在讓一段外部程式碼碰你的資料。

• Prompt injection：藏在 tool 回傳內容裡的偽裝指令，可能被模型誤當成真正的使用者指示執行
• Confused deputy：權限很大的 server 若沒做好授權檢查，等於把高權限借給不該有權限的呼叫者
• 權限最小化原則：每個 server／tool 只給完成任務所需的最小存取範圍，不要先開好備用權限
• 供應鏈信任：安裝別人寫的 server 前，要清楚它的來源、程式碼與存取範圍是否可信
• 對會讀取外部內容（信件、網頁、文件）的 tool 要特別警覺，這是 prompt injection 最常見的入口
• 安全不是裝完 server 就結束，而是持續盤點權限、更新來源、留意異常行為的過程

Claude Code 是一個跑在終端機（terminal）裡的 agentic coding 工具，跟你平常用網頁版或 IDE 外掛聊天最大的不同，是它可以直接讀你的專案檔案、執行指令、修改程式碼，而不只是幫你生成一段貼上去的文字。你在終端機打開專案資料夾、輸入啟動指令，Claude Code 就會以那個資料夾為工作範圍開始對話；你可以像跟同事講話一樣描述需求，例如「幫我把這個函式的錯誤處理補齊」，它會自己去讀相關檔案、理解上下文，再提出或直接進行修改。

第一次使用最重要的心態調整是：Claude Code 不是自動完成，而是一個會主動探索、會問你問題、也會執行指令的協作者，你講得越清楚、給的脈絡越完整，它做出來的東西就越貼近你要的。跟它的第一次對話，不妨從一個小範圍的任務開始，例如請它先解釋某段程式碼在做什麼，感受一下它讀程式碼、回覆的方式，再逐步交付比較大的任務。

• Claude Code 是跑在終端機裡的 agentic coding 工具，能讀檔案、執行指令、直接修改程式碼
• 啟動時以當下資料夾為工作範圍，對話脈絡跟著這個專案走
• 與純聊天工具的差異：它會主動探索專案、執行指令，而不只是生成一段文字讓你自己貼上
• 描述需求時給的脈絡越完整（目的、限制、期望格式），產出越貼近需求
• 建議從小範圍任務開始熟悉互動節奏，例如先請它解釋一段程式碼，再逐步交付大任務
• 它會在必要時主動提問或請你確認，而不是悶著頭亂做

面對一個有點複雜的任務，Claude Code 比較穩健的做法不是一頭栽進去改程式碼，而是走一輪「探索 → 規劃 → 實作 → 驗證」的循環。探索階段，會先讀相關檔案、搜尋關鍵字、理解現有架構，搞清楚「這件事現在是怎麼運作的」，再動手。規劃階段，把要做的改動拆成明確步驟，尤其是牽涉多個檔案或有風險的改動，先講出計畫讓你能確認方向對不對，比悶頭改完才發現方向錯划算得多。

實作階段才是真正動手寫、改程式碼，這時因為前面探索夠紮實、規劃夠清楚，改動通常會比較集中、精準，不會東改一點西改一點。驗證階段是最容易被跳過、卻最重要的一步：跑測試、實際執行一次、檢查輸出是否符合預期，而不是「看起來應該沒問題」就結束。這個循環不是一次性的，遇到大任務時，你可以要求先只做探索和規劃、跟你確認過再進入實作，把風險控制在你想要的顆粒度上。

• 核心工作流四步驟：探索、規劃、實作、驗證，循序漸進降低風險
• 探索：讀相關檔案、搜尋關鍵字，先搞懂現有架構再動手
• 規劃：把改動拆成明確步驟，牽涉多檔案或高風險的改動先講計畫讓你確認
• 實作：在前面基礎紮實的前提下動手修改，改動通常更集中、精準
• 驗證：跑測試、實際執行、檢查輸出，不能只憑「看起來沒問題」收尾
• 大任務可以要求先只做到規劃、跟你確認方向後再進入實作，控制風險顆粒度

每次開新對話都要重新解釋一次「這個專案用什麼框架、程式碼風格是什麼、哪些事絕對不能做」很浪費時間，這就是 CLAUDE.md 存在的理由：一份放在專案裡、Claude Code 每次啟動都會讀的專案記憶檔案。適合放進去的內容包括：專案的技術棧與架構慣例（例如用什麼測試框架、目錄怎麼分）、團隊約定的程式碼風格、常用指令（怎麼跑測試、怎麼建置）、以及明確的邊界（例如「這個目錄的檔案不要動」「資料庫遷移一律要先問過我」）。

不適合放進去的是：會頻繁變動、容易過時的細節（例如某個功能今天的進度），或是太長、太瑣碎、模型讀了也用不上的資訊——CLAUDE.md 不是專案的百科全書，塞太多反而稀釋了真正重要的規則。好的 CLAUDE.md 應該是「新同事到職第一天，你會口頭交代的那幾件事」的濃縮版：講清楚規矩、講清楚地雷，而不是鉅細靡遺地寫流水帳。可以把它想成隨專案一起進版本控制、隨時間逐步修正的活文件，發現 Claude Code 一直犯同一種錯，通常就是該回頭補一條規則的訊號。

• CLAUDE.md 是放在專案裡、每次啟動都會被讀取的專案記憶檔案
• 適合放：技術棧與架構慣例、程式碼風格、常用指令、明確的邊界與禁區
• 不適合放：容易過時的進度細節、太長太瑣碎、模型用不上的資訊
• 目標是濃縮版的「新同事到職交接」，講清楚規矩與地雷，不是流水帳
• CLAUDE.md 可以隨專案進版本控制，隨時間逐步修正、精煉
• 發現 Claude Code 一直重複犯同一種錯，通常代表該補一條規則進 CLAUDE.md

除了 CLAUDE.md，Claude Code 還提供兩種讓工作流更順手的機制。Slash commands（斜線指令）是你自己定義的提示範本，把常常重複打的一長串指示存成一個指令，例如打 /review 就自動套用一段「請照這幾個標準審查目前的改動」的完整提示，不用每次重新打字，也能確保團隊裡每個人用的審查標準一致。Hooks（掛鉤）則更進一步，是在特定事件發生時自動觸發的腳本，例如「每次它要執行指令前」「每次它修改完檔案後」，讓你能插入自己的檢查或自動化，不需要每次都口頭提醒它「記得跑一下 linter」。

兩者分工清楚：slash commands 是「主動觸發」的捷徑，hooks 是「事件自動觸發」的守門員。要用到什麼程度，牽涉 permission（權限）模式的取捨——每個動作都先問過你再執行最安全但最慢；放寬讓它在明確範圍內自主執行能換取速度，但要承擔非預期改動的風險。實務上常見做法是：先從嚴格權限熟悉行為，搭好 hooks 這類防護網後再逐步放寬。

• Slash commands：自訂的提示範本，把常重複的指示存成一個指令，一鍵套用、團隊標準一致
• Hooks：在特定事件（例如指令執行前、檔案修改後）自動觸發的腳本，不用每次口頭提醒
• 分工原則：slash commands 是使用者主動觸發的捷徑，hooks 是事件驅動的自動守門員
• Permission 模式是速度與安全的取捨：每步都確認最安全但慢，放寬自主執行換取效率但擔風險
• 實務上建議先用較嚴格的權限熟悉行為，累積信任、搭好自動化防護網後再逐步放寬
• 這些機制的共同目標：把重複性高、規則明確的事情交給機器，把判斷留給你自己

Agent Skill（代理技能）說穿了很簡單：一個資料夾，裡面至少有一份 SKILL.md。它不是工具（tool），不會幫 Claude 多一個「能做的動作」，而是一包知識與流程——教 Claude 遇到某種情境時，該怎麼想、按什麼順序做、要注意哪些眉角。你可以把公司的報帳 SOP、品牌文案規範、退款審核流程，通通寫成一個 Skill，讓它變成可以重複使用、可以搬到別的專案的知識包。

Skill 真正厲害的地方在於 progressive disclosure（漸進式揭露）：Claude 不會一開始就把所有 Skill 的完整內容塞進 context（上下文視窗），那樣太浪費。它分層載入——平常只有每個 Skill 的 name（名稱）和 description（說明）常駐在背景，成本極低；任務看起來用得上時，才讀完整的 SKILL.md；若還帶了腳本、範本、參考文件，等真正動手做的那一刻才會被讀取。

skills/
└── expense-policy-check/
    ├── SKILL.md
    ├── scripts/
    │   └── check_limit.py
    └── references/
        └── policy.md

• Skill 是資料夾＋SKILL.md，可以額外包含腳本、範本、參考文件等資源檔
• 平常只有 name 與 description 常駐在 context 裡，成本很低
• 只有任務可能用得上時，Claude 才會讀取完整的 SKILL.md 內容
• 更深一層的資源檔（腳本、長文件、範本）等真正需要動手時才會被載入
• Skill 讓組織的 SOP、風格指南變成可重複使用、可攜帶的知識包
• 跟把所有規則硬塞進 system prompt 不同，Skill 讓平常的 context 保持精簡

SKILL.md 開頭一定是一段 YAML frontmatter（檔案最前面用 --- 包起來的中繼資料），至少要有 name 和 description 兩個欄位。這兩個欄位就是 Skill 平常唯一會被 Claude 看到的部分，所以 description 寫得好不好，直接決定這個 Skill 會不會在對的時機被叫出來。

好的 description 不是抽象介紹「這是什麼」，而是具體寫出「什麼情境該用」——用第三人稱描述任務類型、關鍵字、使用者可能問的問題形式。frontmatter 之後就是本文，通常會列操作步驟、注意事項、範例輸出。如果流程需要固定的檢查清單、範本或可執行腳本，就把它們放進同一個資料夾的子目錄（例如 scripts/、references/），在本文裡指示 Claude 什麼時候該去讀或去執行它們。

---
name: expense-policy-check
description: 當使用者要核對報帳金額、詢問<差旅>或<交際費>額度上限時使用，檢查是否符合公司報支政策
---

## 使用時機
1. 讀取使用者提供的金額與費用類型
2. 對照 references/policy.md 裡的額度表
3. 回報是否超標，超標時引用對應政策條款

• SKILL.md 開頭是 YAML frontmatter，至少包含 name 與 description
• description 是平常唯一常駐的說明文字，寫法要具體到「什麼情境該用」
• frontmatter 之後的本文放操作步驟、注意事項與範例
• 資源檔（scripts、references、templates）放在同一資料夾的子目錄
• 本文要明確指示 Claude 什麼情況該去讀取或執行哪個資源檔
• description 用詞越貼近使用者實際會講的話，觸發準確率通常越高

這三個名詞常常被混在一起講，但它們各自負責不同層次的事。Tool（工具）是單一、明確定義的動作，有輸入輸出的 schema（結構定義），讓 Claude 能真的「做事」——查資料庫、算數字、呼叫某支 API。MCP（Model Context Protocol）是一種標準協議，負責把 Claude 用統一的方式「接上」外部系統；一個 MCP server 可以同時提供 tools、resources、prompts，是「怎麼連上東西」的管道，不是動作本身。

Skill 則是知識與流程的封裝，它不執行動作，而是教 Claude 在特定任務裡「該怎麼組合這些工具、按什麼順序、要注意什麼」。三者不是三選一的競爭關係，實務上常常疊在一起：MCP 負責連線與授權，Tool 是連上之後可以呼叫的具體動作，Skill 是那本告訴 Claude 什麼時候該用哪個工具、用完該怎麼收尾的操作手冊。

• Tool 負責「執行」，一次呼叫完成一件明確定義的動作
• MCP 負責「連線」，用標準協議把外部系統的 tools/resources/prompts 接進來
• Skill 負責「知識與流程」，教 Claude 何時、如何組合工具完成任務
• 三者不是互斥選項，實務上經常疊在一起使用
• 判斷準則：要新增一個「動作」用 Tool；要接一個「外部系統」用 MCP；要沉澱一套「做法」用 Skill
• 換團隊、換專案時，Skill 資料夾通常能直接搬過去複用

第一個 Skill 不用想得太宏大，最好的題材就是「你已經反覆手動教過 Claude 好幾次的事」。流程大致是：先挑一個重複出現的任務；接著寫 SKILL.md，description 寫清楚使用情境，本文列出步驟與注意事項；如果流程需要固定範本、檢查清單或可執行腳本，才另外建資源檔——不用一開始就求完整。

寫完之後最容易被跳過、卻最重要的一步是測試觸發。拿幾種不同措辭的真實提問去試，看 Claude 會不會正確判斷「這時候該打開這個 Skill」；同時也要丟一些看起來相關、但其實不該觸發的問題，確認沒有誤觸發。根據測試結果回頭調整 description 的用詞——通常觸發不準的問題，八成都出在 description 沒寫到使用者實際會用的說法。

• 先挑一個你反覆手動說明的重複性任務當作第一個 Skill 候選
• description 要涵蓋使用者可能用的多種措辭與情境關鍵字
• 本文用清楚的步驟與注意事項，不必塞入不必要的細節
• 資源檔按實際需要才建立，避免一開始就過度複雜
• 測試要同時包含「該觸發」與「不該觸發」兩種情境
• 依實測結果反覆調整 description，觸發率才會穩定

Subagent（子代理）是另一個獨立的 Claude 實例，有自己的 context window（上下文視窗）、自己的 system prompt、自己的工具權限，由主對話（也叫 orchestrator，協調者）在需要時呼叫，去處理某個子任務。乍看之下多一層很麻煩，但它解決的是一個很實際的問題：context 會被子任務的雜亂過程塞爆。

如果什麼事都在同一個對話裡做——翻十份文件找一句話、試了五次才成功的指令、大量的中間輸出——主對話的 context 很快就被這些「過程垃圾」占滿，模型反而抓不到重點。把子任務丟給 subagent，它在自己的空間裡搞定所有嘗試與失敗，只回傳整理過的結論，主對話因此保持乾淨。除了 context 隔離，subagent 還帶來另外兩個好處：可以平行執行多個獨立子任務，不用排隊一件一件做；也可以針對性地給每個 subagent 專屬的角色設定，讓它把一件事做得更專精。

• Subagent 是有自己 context window、system prompt、工具權限的獨立 Claude 實例
• 最大好處之一是 context 隔離：子任務的雜亂過程不會污染主對話
• 彼此獨立的子任務可以平行派工，不用排隊等
• 針對性的角色設定（窄工具白名單、專屬 system prompt）讓子任務做得更專精
• 主對話（orchestrator）通常只需要看子任務整理過的結論，不用看完整過程
• 不是所有任務都值得拆給 subagent，過於簡單的事直接做可能更快

定義一個 subagent，通常要交代清楚三件事。第一是角色與 system prompt：這個 subagent 是誰、負責什麼範圍、輸出格式的期待是什麼。第二是工具白名單：只給它完成任務所必要的工具，沒有列進白名單的工具，就是它做不到的事——這是一個硬性的權限邊界，不是「反正給多一點也沒差」。第三是觸發描述：讓 orchestrator 知道什麼情境該指派給它，寫法跟 Skill 的 description 概念很像，要具體到「什麼任務該找它」。

工具白名單特別值得認真對待。一個只負責讀程式碼、給審查建議的 subagent，原則上不該擁有能刪除檔案、能執行 git push 的工具——就算它「應該」不會亂用，把危險工具排除在外，本身就是一種防呆設計。

---
name: code-reviewer
description: 當使用者要求審查程式碼變更、找出潛在 bug 或風格問題時使用，只做唯讀分析
tools: Read, Grep, Glob
model: sonnet
---

你是一個嚴謹的資深工程師，只做唯讀的程式碼審查，
不修改任何檔案，發現問題時指出具體行號與原因。

• 定義 subagent 三要素：角色與 system prompt、工具白名單、觸發描述
• 工具白名單是明確的權限邊界，不是「反正給多一點沒差」
• 觸發描述的寫法和 Skill 類似，要具體到「什麼情境該指派給它」
• 角色越窄、越專一，子任務的品質通常越穩定
• 高風險操作（刪除、部署、金錢相關）的工具權限要格外謹慎
• subagent 能不能再往下呼叫其他 subagent，要看系統整體的設計

Orchestrator-worker（協調者－工作者）模式大致分三步。第一步，主模型先規劃：把一個大任務拆成可以獨立執行的子任務，判斷哪些彼此獨立、可以平行做，哪些有先後依賴、必須照順序來。第二步，把子任務分派給對應的 subagent，獨立的部分同時進行，不必排隊等。第三步，也是最容易被省略的一步：主模型要驗收匯整——檢查每個 subagent 回報的結果是否合理、彼此有沒有矛盾，再統整成最終要給使用者的答案，而不是把幾份結果直接拼貼轉貼。

拆分的粒度也要拿捏：切得太細，光是協調與整合的成本就會超過平行化省下的時間；切得太粗，又會失去平行處理的好處。一般來說，值得拆分的子任務要「夠大、夠獨立」，光是查一個小數字這種事，直接自己做通常比開一個 subagent 快。

任務：分析三個競品的定價頁面

1. 主模型規劃：拆成「分析競品 A」「分析競品 B」「分析競品 C」三個獨立子任務
2. 平行分派給三個 subagent，各自抓取並整理該競品的定價資料
3. 主模型驗收：比對三份結果格式是否一致，有沒有明顯矛盾或缺漏
4. 主模型整合三份結果，寫成一份比較報告回覆使用者

• Orchestrator 先規劃拆解任務，判斷子任務的獨立性與依賴順序
• 獨立的子任務平行分派，有依賴關係的子任務照順序處理
• subagent 各自在自己的 context 裡執行，回傳整理過的結果
• 主模型要做「驗收」：檢查結果是否合理、彼此是否矛盾
• 最終呈現給使用者的答案是主模型整合過的版本，不是子任務結果的直接拼貼
• 拆分粒度要拿捏：太細增加溝通與整合成本，太粗會失去平行化的好處

多代理架構好用，但也容易踩坑。最常見的是過度分派：連查一行程式碼、算一個簡單數字這種事都開一個 subagent，多繞一圈的延遲與成本卻沒換到對應好處。第二個是結果未驗證就照單全收：subagent 也是模型，一樣會出錯或產生幻覺（hallucination，講得煞有其事但其實不對），主模型如果不檢查就直接採用，錯誤反而被放大、包裝得更像真的。

第三個是 context 傳遞不完整：分派任務時只丟了一句指令，沒把「為什麼要做這件事、背景是什麼」一起交代，subagent 做出來的東西方向對，但深度不夠，甚至答非所問。第四個是成本與延遲失控：每個 subagent 都是獨立的 context 與 token 消耗，平行開太多、巢狀呼叫（subagent 又呼叫 subagent）疊太深，帳單和等待時間都可能不成比例地暴增。

• 過度分派：小到一行程式碼的事也開 subagent，增加成本與延遲卻沒有實質好處
• 結果未驗證：把 subagent 的輸出當成絕對正確，錯誤會被放大
• context 傳遞不完整：只丟任務指令、不給背景，容易做出「對但不到位」的結果
• 成本與延遲失控：平行度太高或巢狀呼叫太深，token 消耗與等待時間會迅速膨脹
• 判斷是否值得拆分的準則：任務夠大、夠獨立、夠有平行化空間才值得
• 高風險或對外的最終輸出，一定要有明確的驗收關卡

把 Claude 接進正式產品，主要有三條管道。Claude API 是 Anthropic 直接提供的服務，通常最先拿到新模型與新功能，接入方式也最單純。Amazon Bedrock 把 Claude 整合進 AWS 生態，如果團隊本來就用 AWS，就能沿用既有的雲端合約、IAM 權限管理與帳務系統，資料處理也留在 AWS 環境內。Google Vertex AI 是給 GCP 陣營團隊的對應選項，邏輯類似，一樣能沿用既有的雲端採購關係與權限體系。

選哪一條管道，重點不在「哪個 Claude 比較強」——底層模型能力是一致的，差別主要在怎麼接、資料怎麼流、帳單怎麼算。實務上要考慮的因素包括：公司既有的雲端合約與採購關係、資料落地與合規要求（資料需不需要留在特定雲端環境或地區）、統一帳務與權限管理是否重要，以及要不要最快拿到新模型或新功能。

• Claude API 是 Anthropic 直接提供的管道，通常最快取得新模型與新功能
• Amazon Bedrock 讓已經在用 AWS 的團隊透過既有帳務、IAM 權限存取 Claude
• Google Vertex AI 提供給 GCP 陣營團隊類似的整合方式
• 選擇考量：既有雲端合約、資料落地與合規需求、統一帳務與權限管理
• 三種管道底層的模型能力一致，差異主要在接入方式與資料流向
• 沒有絕對最好的選項，要看團隊既有的雲端生態與治理要求

Evals（評估）是把「感覺這次回答得比較好」換成可以重複驗證的具體流程。核心是一份 golden test set（黃金測試集）：一組具代表性的輸入與預期結果，用來衡量目前系統的表現。評分方式有很多種，簡單的可以用精確比對或規則式評分；輸出比較開放、難用固定規則量化好壞的情境，可以用 LLM-as-judge——另外呼叫一次 Claude，依照你訂的評分標準幫忙打分。

Evals 不是做一次就結束的事，而是要持續維護的資產。每次調整 prompt、換模型、改流程，都應該重跑一次評估，這就是regression test（迴歸測試）：確認新版本沒有讓原本表現好的案例悄悄變差。實務上，黃金測試集也要隨著使用中發現的真實失敗案例不斷補進去，才能真正貼近實際會遇到的情境，而不是只涵蓋當初設計時想得到的那幾種。

• 黃金測試集是一組具代表性的輸入與預期輸出，作為評估基準
• 評分可以用精確比對／規則，也可以用 LLM-as-judge 處理開放式輸出
• 迴歸測試：每次改動 prompt 或模型，都要重跑一次評估
• Evals 不是一次性任務，要隨實際使用中發現的失敗案例持續補充
• 目的是把「感覺變好了」換成可以重複驗證的具體指標
• 好的黃金測試集要涵蓋常見情境，也要涵蓋邊界情況與已知的失敗案例

AI Fluency（AI 流暢力）4D 框架把「怎麼好好用 AI」拆成四個環環相扣的能力。Delegation（委派）：判斷這個任務該交給 AI 做多少、哪些部分該保留人為決策——不是遇到任務就整個丟給 AI。Description（描述）：怎麼把任務、脈絡、期待格式講清楚，讓 AI 真正理解你要什麼，這其實就是前面學過的角色、脈絡、任務、格式那一套。

Discernment（判斷）：拿到 AI 的產出後，用專業判斷力評估是否正確、有沒有偏誤或幻覺，而不是照單全收。Diligence（盡責）：使用 AI 的人始終對最終結果負責，包括遵守公司政策與法規，對高風險輸出做額外查核。四者缺一不可——委派錯了、描述不清、不做判斷、不負責任，任何一環斷掉，整個流程都會出問題。

• Delegation：判斷任務該交給 AI 多少、哪些決策該留在人身上
• Description：清楚描述任務、脈絡與期待格式，AI 才能給出你要的東西
• Discernment：用專業判斷力檢視 AI 產出，不是照單全收
• Diligence：使用者對最終結果始終負責，高風險輸出要額外查核
• 四個 D 環環相扣，任何一環做不到位都會拉低整體品質
• AI Fluency 是一種可以刻意練習的能力，不是天生會或不會

送進 prompt 裡的內容，都要當作「可能被處理」的資料看待。牽涉敏感個資或機密資訊時，先確認資料使用政策，以及所選部署管道（Claude API、Bedrock、Vertex AI）當下的資料保留承諾是否符合規範——各管道細節可能不同，要以官方當下條款為準，不要只憑印象假設。治理面同樣重要：團隊要有清楚的使用規範；高風險或不可逆的操作（金錢、對外發布、刪除資料）要設人工核准關卡；也要保留紀錄與稽核軌跡，方便回溯是誰、何時讓 AI 做了什麼。

走到這裡，這門課也接近尾聲了。從 CH01 認識 Claude 開始，一路走過 Prompt Engineering、API、Tool Use、MCP、Claude Code，再到這三章的 Agent Skills、Subagents、部署與 AI Fluency——這些能力是一層層疊上去的：先學會把話講清楚，才有辦法把任務交代給工具、Skill、subagent。找一個手邊真實的任務，把學到的東西串起來動手做，是鞏固所學最快的方式。

• 送進 prompt 的內容都要當作「可能被處理」的資料，先確認清楚資料使用政策
• 不同部署管道的資料保留與使用承諾可能不同，以官方當下條款為準
• 高風險、不可逆的操作要設人工核准關卡，不能讓 AI 全自動執行
• 治理需要清楚的使用規範，讓團隊知道什麼能問、什麼不能問
• 保留紀錄與稽核軌跡，方便回溯輸入、輸出與決策過程
• 從認識 Claude 到部署與 AI Fluency，這條路徑的能力一層層疊上去，找一個真實任務動手練習最能鞏固所學