子代理：獨立的注意力視窗

1. 什麼是子代理，為什麼要用它

子代理是 Claude Code 把任務交給它處理的專門助手：它在自己的上下文視窗裡完成工作，再把一份簡短的摘要交回您的工作階段。讀取檔案、搜尋和工具呼叫都留在它的上下文裡。

為什麼要這樣做：在主工作階段裡，訊息、讀過的檔案和指令輸出都佔用同一個視窗的空間，而它的容量不是無限的。視窗逐漸填滿時，Claude Code 會精簡歷史紀錄，一部分細節可能因此遺失。子代理讓您把中間過程移到另一個視窗，主對話裡只留下結果。

最簡單的子代理

第一次試用，只要在 Claude Code 裡發一則普通訊息就夠了：明確請它呼叫子代理，並描述子代理的任務。不需要事先建立自己的角色檔案，這類任務交給內建助手就行。例如：

呼叫一個子代理來讀取 index.html 檔案。
讓它為檔案整理一份簡短的地圖：主要區塊
以及每個區塊的作用。接著用 3-5 句話
寫出內容的簡短摘要。
不要修改檔案。把子代理的回答帶回這個工作階段。

主代理會把任務交給助手，完成後在您的對話裡顯示它的回答。如果是在背景執行，輸入欄下方會出現一條狀態列，顯示子代理的名稱和工作狀態。點一下就能打開子代理的工作階段，看看它正在讀什麼、做什麼。工作進行時請確認確實另外啟動了子代理：用一般文字提出要求，會影響 Claude 的選擇，但本身不保證一定會委派。

子代理會拿到什麼

如果同一種任務要帶著固定規則反覆執行，可以把自己的角色寫成檔案。這種自訂子代理在啟動時有兩個主要輸入：

• 來自您設定檔的角色指示 - 專長和行為規則；
• 任務描述，由主代理根據您的要求撰寫。

除此之外，Claude Code 還會自動替它加上共用的背景資訊：專案的 CLAUDE.md 檔案、一份 git status 快照，以及執行環境的相關資訊。您與主代理之間的對話不在其中。

這張圖只有一個重點：子代理在自己的視窗裡完成任務，再把摘要交回主對話。主代理不必載入所有中間的讀取和搜尋。不過摘要本身同樣會佔用主上下文的空間。

這種分工也有代價：摘要看不出得出結論的完整過程。光看摘要，您可能察覺不到助手缺了哪些資料，或哪些地方沒檢查。所以回答裡要附上依據和限制，結論也值得再驗證。

為什麼 Claude 不會記得所有事

上下文視窗是模型在準備下一個回答時手上擁有的資訊：指示、能取得的對話歷史、讀過的程式碼、指令輸出。正因如此，代理才能沿用您幾則訊息前討論過的決定。視窗有上限，不會把整段對話的所有細節永遠保存下來。

截圖裡，/context 指令顯示 4k/200k tokens (2%)：可用的 20 萬個 token 已經用掉大約 4 千個。token 是一小段文字：一個詞、詞的一部分或一個符號。所以 20 萬個 token 並不等於 20 萬個詞。這是截圖中這個工作階段的視窗大小，換一個模型或設定可能不一樣。

下面列出佔用空間的項目：System prompt - 系統指示，Memory files - 載入的記憶與規則檔案，Skills - skill 的相關資訊，Messages - 訊息。這裡幾乎還沒有對話，但視窗已經有一部分被指示佔用。Free space: 196k (98.0%) 這一行顯示剩下的可用空間。隨著對話進行、讀取檔案和執行指令，這些空間會逐漸用掉。

接下來，我們用一個讀程式碼的自訂 reviewer 來拆解這個機制：它會拿到哪些資訊，以及怎麼建立它的角色檔案。這裡說的是一次全新的普通啟動；延續先前的工作或傳入歷史副本的方式，這個例子用不到。

2. reviewer 對專案知道些什麼

擁有獨立的上下文，不代表助手什麼都不知道。它有初始指示，也能存取專案。以下是我們例子中自訂 reviewer 的資訊來源：

CLAUDE.md 是寫給 Claude Code 的通用指示檔案：例如原始碼放在哪裡、專案採用了哪些慣例。不需要為了這次檢查特地建立它。

您的對話歷史不會自動傳過去。如果主代理已經讀過 app.js，那次讀取的內容不會自己出現在 reviewer 那邊。不過檔案並沒有消失：助手可以再打開一次。

聊天中做過的決定也一樣。假設您和代理討論過，清單裡兩個名稱相同的項目應該保持為兩筆不同的購物項目。對刪除功能的檢查來說，這是關鍵要求。只有主代理把它寫進委派內容，或助手讀到記錄它的文件，reviewer 才會知道。

3. 建立角色檔案

角色放在專案內的 .claude/agents/reviewer.md。使用者資料夾裡的 ~/.claude/agents/ 也可以存放角色，供不同專案共用；符號 ~ 代表使用者的主資料夾。目前用專案內的版本就夠了。

可以直接請 Claude Code 建立這個檔案：

建立 .claude/agents/reviewer.md，用來檢查頁面程式碼，
不做任何修改。只允許 Read、Grep、Glob。
reviewer 回傳有依據的發現、檢查過的範圍
和限制；沒有發現也是可以接受的。
把建立好的檔案給我看。

結果應該是一個普通的文字檔。沒什麼神奇的。下面是完成的版本：可以拿來和代理的回答比對，也可以自己存成檔案。如果您已經有同名的角色，請先看看它的內容，以免覆蓋掉需要的指示。

---
name: reviewer
description: 檢查完成頁面的程式碼有沒有行為上的錯誤，並回傳有依據的報告。在被要求審查頁面、但不做修正時使用。
tools: Read, Grep, Glob
---
依照給定的要求，研究指定檔案的程式碼。
不要修改檔案。不要承諾會執行頁面：你只能讀取和搜尋。
每個發現都要寫出位置、預期行為、結論的依據、
檢查條件和影響。資料不夠時要標明。
另外列出你檢查了什麼、沒檢查什麼。
如果依照給定的標準沒發現問題，就直接這樣寫。

兩行 --- 之間的區塊叫做 frontmatter：Markdown 檔案開頭的設定。這裡的 name 設定角色名稱，description 告訴主代理什麼時候該選它，tools 列出可用的工具。再往下是用文字寫的一般指示。

範例裡的三個工具剛好涵蓋讀程式碼需要的功能：Read 讀取檔案，Grep 搜尋內容，Glob 依名稱或路徑找檔案。因此 reviewer 能找到刪除函式並讀它，但不會在瀏覽器裡執行頁面，也不會在終端機裡執行指令。

"不要修改檔案"這一行描述的是任務。tools 欄位限制的是完成任務的手段。如果只在文字裡提出要求而不限制工具，助手可能仍保有寫入的能力。完成的範例裡兩者都已經寫好，不需要事後再補上限制。

角色檔案和 skill 很像：都是設定加上指示文字。很容易搞混。但這裡我們設定的是一次專門用來檢查的獨立啟動。skill 通常是在目前的對話裡加入一套可重複的流程，雖然 skill 也可以在獨立的上下文中執行。請依照工作應該怎麼進行來選擇，而不是看兩個檔案長得像不像。

4. 檢查並呼叫 reviewer

檔案存在磁碟上，只是第一步。現在來確認工作階段看不看得到它。打開檔案，看看名稱 reviewer、描述、工具那一行和指示文字：裡面有沒有承諾會打開瀏覽器，或會直接修正錯誤。

在 Claude Code 的輸入欄輸入 @，選擇帶有 agent 標記的 reviewer。要選的是角色，而不是帶有檔案路徑、看起來很像的那一項。從清單中選擇，就能明確指定這次任務由哪個助手負責。

如果找不到這個角色，先檢查路徑：檔案應該放在目前開啟的專案的 .claude/agents/ 裡。再檢查 frontmatter：兩條分隔線、名稱和描述。也可以請 Claude Code 檢查這個定義檔本身。

根據 Claude Code 文件，已經在監看中的資料夾有變更時，幾秒內就會生效。如果 agents 資料夾是在工作階段啟動後才第一次建立，就需要重新啟動。結束目前的工作階段，然後在一般的終端機裡，從同一個專案資料夾執行：

claude --continue

這會接續目前目錄中最近一次的對話。啟動後，再檢查一次 @ 清單。這個啟動 Claude 的指令，是在退出後於終端機輸入的，而不是在已經執行中的對話裡輸入。

第一次委派，我們用一個購物清單頁面來示範：標記結構在 index.html，邏輯在 app.js，兩個檔案都在專案根目錄。在您自己的專案裡，請把路徑和預期行為換成自己的。從清單選好 reviewer 之後，在這個提及後面加上這段文字：

研究專案根目錄中的 index.html 和 app.js。
檢查新增和刪除項目：計數器必須等於
剩下的項目數，刪除一筆紀錄時不能
連帶刪掉另一筆同名的紀錄。
不要修改檔案。回傳從程式碼得出的結論，以及需要在瀏覽器裡檢查的地方。

範圍明確的檢查需要的東西，這裡都有了：去哪裡找、應該發生什麼、需要什麼樣的結果。不需要另外寫一份簡報檔。主代理會替選定的 reviewer 擬好任務；透過 @ 選擇決定的是由誰執行，而不是把您的訊息一字不改地轉交。

5. 結果怎麼回來

送出要求後，看看 reviewer 是否已經啟動。在一般的互動式工作階段中，這類工作可能在背景執行：您會在面板上看到它，同時可以繼續對話。/tasks 指令可以查看任務，包括最近完成的。

檢查結束後，主代理會拿到結果並轉告您。如果轉述太簡略，可以要求："把 reviewer 的最終報告完整貼出來"。這樣比較容易保留發現的確切措辭和檢查的限制。

例如，一份關於計數器的示範報告可能長這樣：

檢查了 app.js 中的新增和刪除。
removeItem() 會重新繪製清單，但在這條路徑上
沒有找到 updateCounter() 的呼叫。預期計數器會顯示
剩下的紀錄數。
瀏覽器檢查：新增一個項目，再刪除它，
比對計數器和空清單。
沒有另外檢查刪除同名紀錄的情況。
沒有在瀏覽器中執行。

這只是回答格式的範例，不保證您的頁面裡一定有這個 bug。我們的 reviewer 只能讀程式碼，所以最後一行老實交代了它的能力範圍。不執行頁面，從程式碼得出的結論也可能站得住腳，但它的依據需要驗證：例如，同一條路徑上是不是有別的函式會更新計數器。

打開報告指出的位置，或在瀏覽器裡重現描述的操作。如果問題確實存在，可以請主代理修正。如果不存在，就告訴它您觀察到的情況，請它再檢查這個結論。一份排版漂亮的報告，並不能決定到底該改什麼。

"依照給定的標準沒有發現問題"也是可以接受的回答，前提是清楚交代了檢查過什麼。而"找不到刪除邏輯所在的檔案"代表只有部分結果：得先確認路徑。沒必要為了湊數而在報告裡塞進猜測。

順帶一提，清單裡可能會看到內建角色 Explore 和 Plan。不需要自己建立角色檔案就能使用。

6. 什麼時候值得委派

第一次檢查順利之後，很容易想替每個動作都配一個專門的助手。這種衝動可以理解。但每次另外啟動都應該帶來些什麼：獨立的審視，或是一段主對話不需要看到詳細過程的獨立工作。

幾個彼此相依的步驟，也可以組成一個交給子代理的任務。找到處理函式、檢查它在哪裡被呼叫、再下結論 - 這是一個正常而完整的任務。不該做的，是把每一步都分給不同的助手，最後還得再向每個人重新說明前一步的結果。

子代理的模型可以用 model 欄位另外指定。目前還用不到：先得到一個清楚的角色和可驗證的結果更有用。另外啟動本身，並不代表模型會更強或更弱。

第二個角色應該檢查別的東西

假設除了 reviewer，您還需要一個 playtester 來檢查使用者操作情境。把原本的指示換個名字複製一份，幾乎不會帶來任何改變。先分清楚工作對象和結果：

例如，這個角色可以只處理一件事：兩筆同名購物項目刪掉其中一筆。操作後應該剩下一筆紀錄，計數器應該顯示 1。這是可以衡量的任務。"評估一下這個頁面好不好"則留下太多空間給主觀的建議。

接著把任務和工具對照一下。像我們的 reviewer 這樣只能讀取和搜尋，助手就無法在瀏覽器裡操作。它可以擬出檢查腳本，或分析您記錄下來的觀察結果。這是檢查的準備或分析，不是它自己完成的 playtest。

擬一份檢查腳本，測試在兩筆同名購物項目中
刪除其中一筆。每一步都寫出操作
和預期結果。不要修改程式碼，也不要聲稱已經執行。
等我提供觀察結果後，比對預期和實際結果，
並列出還缺哪些資料。

要讓它自己執行，需要一個可用的瀏覽器操作工具，還要確認執行真的發生了。光是叫 playtester 這個名字並不夠。先選好檢查方式，再在角色裡寫清楚什麼時候呼叫它，以及它能誠實回傳什麼樣的結果。

7. 在您的工作階段裡會是什麼樣子

現在您有了一個工作階段看得到的角色檔案，以及一項可以交給它的簡短檢查。開始用這些就夠了。不需要事先準備十幾個差不多的 reviewer。

接下來，問題出在哪一層就修改哪一層。重要條件沒傳過去 - 補進委派內容。拿到可疑的結論 - 檢查它的依據。reviewer 經常回傳太籠統的答案 - 調整角色指示。檔案會留在專案裡，下一次檢查一開始就會帶著這些規則。

需要重複委派時，給 reviewer 的簡報會派上用場。拿到回答之後，請接著看如何檢查發現並選擇要做的修正。