代理程式的四種任務類型

"把入口網站首頁收尾一下"這句請求，其實藏著好幾種不同工作。促銷清單少了篩選器。橫幅按鈕連到錯誤頁面。排行榜資料準備程式寫了兩份，每次修改都得多花一倍工夫。至於促銷頁面的網址到底從哪裡來，幾乎沒人記得。

接到這種請求的人，多半會先追問。Claude Code 也可能追問，但常常會自行補上缺漏，做出看似合理、其實沒人要求的工作。不同類型的任務，也會引出不同的多餘工作：篩選器旁邊多了搜尋欄、修正連結時順手改了版面、重構時"修好"排序，研究最後則變成直接修改程式碼。

應該改變什麼

最簡單的分類方式，是看工作完成後哪些地方會不一樣：

• 新增了原本沒有的行為 - 這是 feature，也就是新功能；
• 行為被修正成符合預期 - 這是 bugfix，也就是錯誤修正。已經實作、但從一開始就不符合約定的功能，也算在這類；
• 從外部看起來都一樣，只有內部程式碼的組織方式不同 - 這是 refactoring；
• 您得到專案相關問題的答案，原始檔案則維持原樣 - 這是 research，也就是研究。

任務類型能提示您該在請求中明確說明什麼，以及要檢查什麼。代理程式能有多大自由，還取決於錯誤的代價和任務規模：修改已經有人在使用的程式碼，需要比在練習專案新增頁面更仔細。有些任務也會混合不同類型，例如先研究，再修改。這時每個階段都要有自己的結果和界線。

新增功能

促銷清單需要一個切換開關，只顯示進行中的促銷活動。先把條件說清楚：有 active: true 標記的促銷活動才算進行中，A 和 C 有啟用這個標記，B 的標記則是關閉的。這裡的資料是練習用的，以下請求範例可以套用到您的專案。

代理程式很可能會完成"新增進行中促銷活動篩選器"這個請求，還順便多做一些。結果可能是切換開關做好了，旁邊多出搜尋欄，心想"既然都在篩選了"，還加上依結束日期排序。每項新增功能單看都說得通，合在一起卻把一個功能變成沒人要求、現在還得額外檢查的小型子系統。

至少這些多餘功能會顯示在頁面上。更麻煩的是，代理程式默默替您做了決定。Andrej Karpathy 分享過他的 MenuGen 專案：使用者透過 Google 登入、透過 Stripe 付款，而代理程式用電子郵件地址把購買紀錄連到帳戶。如果兩個服務中的電子郵件地址不同，付款就不會出現在帳戶裡。資料要用什麼欄位連結、如何處理專案裡已有的紀錄，這些決定應由您做，最好直接寫進請求。我們的問題簡單一些：沒有 active 標記的促銷活動該怎麼處理？

另一個容易讓代理程式自行發揮的來源，是它參考的範例。它會在專案中尋找相似程式碼並照著做，但相似的程式碼可能正好是大家早就想重寫的地方。如果專案裡有值得參考的範例，請直接指出來。

新增功能時，請提供一個使用情境，並明確列出不在任務範圍內的事項：

在首頁的促銷清單中新增"只顯示進行中"切換開關。
有 active: true 的紀錄才算進行中；沒有這個欄位的紀錄視為未啟用。
用目前的資料檢查：開啟時顯示 A 和 C，關閉時顯示 A、B 和 C。
不要新增搜尋、排序或其他篩選器，那些是獨立任務。
如果專案裡已有類似的切換開關，請依照它的做法，
並告訴我您參考的是哪一個。
先用一句話說明您打算實作的使用情境，
等我回覆後再繼續。現在先不要修改檔案。

最後兩行成本很低，卻很實用：如果代理程式描述的情境和您的想法不同，您可以在修改前發現。代理程式提出計畫後，簡短問它：這個方案會不會太複雜、是否有沒做完的部分，以及它為什麼這麼判斷。這個問題適用於任何計畫，對 feature 特別有用，因為多做的部分最容易藏在這裡。完成後請檢查切換開關的兩種狀態，也順便看看頁面上有沒有多出不需要的內容。

修正錯誤

首頁橫幅的按鈕應該開啟顯示促銷條款的 /campaign/ 頁面，現在卻連到 /old/。

對代理程式來說，最快的作法是直接把 /campaign/ 寫進按鈕連結。如果網址原本就寫在連結裡，這樣確實足夠。但如果網址來自其他按鈕也共用的資料，直接替換只會掩蓋表面症狀：這個按鈕會正常運作，資料中的錯誤卻還在。另一種常見情況是，代理程式順手調整橫幅的間距和顏色，理由是反正已經打開了這個檔案。

光看按鈕本身，無法判斷是哪一種情況；只有查看程式碼才能知道。

提出請求前，先自行重現問題：按下按鈕，看看它連到哪裡。如果您這邊無法重現錯誤，先別急著結束任務，請確認當時看到問題的操作步驟和資料。重現問題後，下一步才是找出原因。不知道按鈕從哪裡取得網址嗎？沒關係，這正是要先問代理程式的問題：

首頁橫幅的按鈕連到 /old/，但應該連到 /campaign/。
先找出按鈕從哪裡取得網址，並指出程式碼中的位置。
現在先不要修改任何檔案。
等我確認後，再到設定網址的位置修正它。
不要修改橫幅的樣式。

修正後，重做原本的操作：按下按鈕、確認網址，並確認頁面顯示促銷條款。如果共用的網址資料有變更，也請再檢查另一個使用它的地方。

調整程式碼的組織方式

排行榜的資料準備程式寫了兩份，內容幾乎相同，每次修改都得在兩處進行。這項任務要保留一份，並確保表格不變。

修改時必須保持不變的條件，稱為 invariant（不變條件）。這裡指的是資料相同時，參與者的順序和表格中的數字都要維持原樣。

重構出錯時，問題不會大聲提醒您。分數相同時排序改變了、四捨五入方式不同了，卻沒有任何錯誤訊息，表格只是顯示錯誤內容。代理程式合併兩份程式碼後，可能什麼都沒執行，就回報"行為沒有改變"。也可能因為舊排序看起來奇怪，順手"改善"它。

假設資料順序如下：A 得 10 分、C 得 20 分、B 得 20 分、D 得 15.5 分。現在表格顯示 C: 20、B: 20、D: 15.5、A: 10。重構的基準就是目前程式碼輸出的這個結果，即使您希望它不同也一樣。這組資料是刻意安排的：C 排在 B 前面，因此如果新版依姓名排列同分項目，B 就會跳到前面。小數也能看出四捨五入是否改變。

以下請求可以避免這兩種偏差：

排行榜的資料準備程式在兩個地方重複，請只保留一份。
不要改變表格的行為，即使有些地方看起來奇怪，
請另外列出那些地方。
修改前先執行現有檢查，並輸出以下資料的表格：
A: 10、C: 20、B: 20、D: 15.5。請保存兩次輸出。
修改後重做一次並比較結果。
在報告中指出現在的資料準備程式位於哪裡。

請自行比較保存的輸出，不要只相信報告中的"結果相同"。結果相同只能說明這些資料上的行為維持不變，僅此而已。請求的最後一行則用來確認任務本身是否完成：表格相同，不代表重複程式碼真的已經移除。

這種情況只做一半比完全不做還糟。假設有一份副本留下來，部分呼叫則改用新版本。表格雖然一樣，準備資料的方法卻有兩種；代理程式可能會以舊版本為基礎處理下一個請求，因為它不知道哪一份才是正確的。既然開始合併，就完成到只剩一份；如果時間不夠，就先停下來，記錄目前還有哪些部分沒完成。

只研究，不修改

Research 和其他類型最不一樣：最後得到的不是修改過的專案，而是一個答案。以我們的入口網站為例，要查的是促銷按鈕的網址在哪裡決定。這和修正錯誤一開始問的是同一件事，只是這裡完全沒有要求修改。這就是混合任務的樣子：先研究，再把修正放到另一個階段。

代理程式在這裡常有兩種偏差。第一種是查到一半就開始修改：發現一段程式碼不太理想，覺得直接修正比描述問題更省事。研究於是變成沒有規格、也沒有檢查的修改。第二種比較不明顯：代理程式讀過程式碼後，就很有把握地說明頁面如何運作，雖然它根本沒執行頁面。從外部看來，轉述讀到的內容和實際觀察看起來沒什麼兩樣。

第三種偏差從請求本身開始。如果您在請求中寫下下一步打算做什麼，代理程式就會讓答案配合這個目標：您得到的不是目前的運作方式，而是它認為應該如何運作。因此，進行 research 時請詢問目前的結構，把您的打算留到下一階段。下面的請求完全沒有提到之後要修正網址。

找出首頁橫幅按鈕從哪裡取得網址。不要修正任何內容。
請在回答中列出檔案和程式碼位置，以及它們之間的關係，
說明哪些發現來自閱讀，哪些來自執行，
以及目前還有哪些未知之處。

這項請求的理想回答大致如下："在 pages/home.html 中，按鈕網址來自 promo.url；/old/ 這個值設定在 data/promo.json。這是我閱讀兩個檔案後確認的。我沒有執行頁面，也沒有確認是否有指令碼會改變網址。"這樣既能檢查兩者的關係，也誠實說明了知識的界線。

如果過程中發現可疑的地方，請另外寫在回答中：目前看到什麼，還缺少哪些資訊才能下結論。修正則是下一階段的工作，需要另外說明範圍。

第一步與界線

把所有重點整理在同一張表裡。

第三欄列出值得在請求中明確排除的事項。第四欄則是您可以自行檢查，或請代理程式在回答中展示的內容。

反過來說，任務類型的名稱本身不代表可以任意修改。"這只是 refactoring"不是重寫半個模組的理由；"這是 bugfix"也不代表可以順手改版面。類型會提示該問什麼、檢查什麼，但界線仍由您決定。

改寫六個請求

以下是六個常見的請求。請逐一判斷類型，並改寫請求，減少代理程式需要自行猜測的部分：結果、界線和檢查方式。解析緊接在後面，不妨先自己試試看。

1. "新增排行榜的 CSV 匯出功能"。
2. "排行榜有時會把同一位參與者顯示兩次，請修好"。
3. "把 pages/home.html 拆成幾個部分，它太大了"。
4. "為什麼首頁載入這麼慢？"
5. "修正連結，順便重做版面"。
6. "讓入口網站變得更好"。

以下是其中一種解析方式。您的說法可以不同，重要的是涵蓋相同的要點。

1. 匯出排行榜。
Feature。還缺少使用情境：哪些欄位要匯出、資料列的順序為何、匯出按鈕放在哪裡。還有一個容易忽略的資料問題：目前沒有分數的參與者是否也要匯出？請自行決定，否則代理程式會替您決定。另外要明確列出不做的事：匯入、選擇欄位、其他格式。檢查方式很簡單：用 A、B、C、D 這組資料匯出，再和畫面上的表格逐列核對。

2. 參與者重複出現。
Bugfix，但關鍵字是"有時"，不是"修好"。目前還不知道重複項目何時出現，代理程式就無從下手；它最可能會在顯示表格前移除重複資料，這正是掩蓋表面症狀。先找出在哪種操作和資料下會出現重複，再請代理程式找出發生位置，但不要修改。檢查時重做當初會產生重複項目的情境。

3. 拆分大型檔案。
Refactoring，但沒有說明不變條件，也就無從檢查"沒有任何東西損壞"。請補上：頁面外觀和行為都要和以前相同，包括橫幅、促銷清單和排行榜；修改前先記錄檢查結果。也要排除順手修改的可能：代理程式拆分檔案時，可能順便調整間距或重新命名 class。

4. 頁面載入很慢。
Research：這是提問，不是要求加快速度。但代理程式可能把它理解成"讓它快一點"；如果沒寫明"不要修改任何內容"，回答就可能變成盲目最佳化。請要求它區分測量結果和閱讀程式碼後的推測：如果代理程式實際檢查過，"圖片檔案總共好幾 MB"就是事實；"可能是指令碼拖慢速度"則是猜測。原因確定後，再把修正放到下一階段。

5. 修正連結並重做版面。
一個請求包含兩個結果。修正連結是 bugfix。新的版面不完全屬於這四種類型：行為沒變，外觀變了。它最接近 feature，只是結果不是由使用情境，而是由參考資料 - 設計稿或截圖 - 來定義。先用 bugfix 章節的請求修正連結，檢查後再處理版面：

現在請依照設計稿 @banner-mockup.png 調整橫幅版面。
不要修改按鈕網址或文字。

6. 讓入口網站變得更好。
無法判斷任務類型，也不必猜。應該反問提出請求的人：目前究竟是哪裡造成困擾？如果是您自己提出的請求，那就先問問自己。也可以交給代理程式協助釐清：

修改任何內容之前，先問我最多五個問題，
以了解我究竟想改善什麼。
不要修改任何檔案。

根據回答，通常就能看出任務類型。