如何撰寫可驗證的 /goal 條件

想像一下：您請代理在一款已完成的瀏覽器遊戲中下一盤棋。它走了幾步，描述棋盤局勢，接著就停了。棋局還沒結束。您輸入"繼續"，它又移動棋子，然後再次等您傳訊息。到某個時候，您會發現，最單調重複的工作竟然是您自己在做。

Goal 是一個附有完成條件的目標，您可以用 /goal 指令交給代理。例如："輪流替雙方下棋，直到頁面顯示棋局已結束。"代理每完成一輪工作，就會由另一個模型根據對話檢查目標是否達成。如果還沒達成，工作就會繼續，不必等您再說"繼續"。您可以等它交出結果，不過遇到障礙或錯誤時，工作仍可能提前停止。

我們先從一個現成的棋局條件開始，再為搜尋、表單和行動版頁面設定目標。每個目標都有明確的結果和驗證方式。接著也會看看如何請代理替您撰寫條件，以及怎麼分辨真正完成與沒有結果就停止。

/goal 如何讓工作繼續

棋局範例中有兩種不同的機制，很容易混淆。一種會在瀏覽器中操作：點擊、輸入棋步，並讀取頁面顯示的內容。另一種不會點擊任何東西，而是讀完整段對話，判斷工作是否該繼續。

前者是透過 MCP 預先連接的瀏覽器工具 Playwright。後者則由 /goal 指令啟動。Playwright 移動棋子，/goal 判斷何時該停止。兩者負責不同的工作，只是從外觀看起來可能像同一件事。

請留意，評估不是每次滑鼠點擊後都會進行，而是在代理完成一輪工作後才進行，簡單說就是等它整段回覆結束。在同一輪中，代理可能連續執行好幾個動作：移動棋子、讀取結果，再根據結果做出反應。等到有內容可供評估時，/goal 才會接手。

先準備好遊戲

設定條件之前，範例必須能正常運作：頁面可以透過已知網址開啟，操作遊戲的工具（此處是 Playwright）也已連接，而且頁面上要有標記，能看出棋局是否結束。

我們的範例使用 data 屬性：棋局進行中時為 data-game-over="false"，結束後則為 data-game-over="true"。這項約定由遊戲頁面的作者設定，代理不會自行發明，只會讀取它。

要確認很簡單：請代理開啟頁面並讀取屬性值。剛開始的棋局會得到 false。這完全正常，正是起始狀態應有的值。

如果頁面上根本沒有這個屬性，就還不適合設定目標。條件只能依據實際讀得到的資訊，因此要先把標記加回頁面，而不是臨時替它想個替代方案。範例設定好之後，也別在棋局進行中更改條件，或額外加上計時器，只為了讓示範快點結束。從頭到尾都要使用同一個條件。

執行已設定的目標

接下來就是實際指令。這個範例的條件可以這樣寫：

/goal 透過頁面介面輪流替雙方下棋。
每走一步就讀取 data-game-over，並顯示頁面上看到的內容。
data-game-over 變成 true 時，棋局才算結束。
如果下了 40 步仍未結束，請停止並說明卡在哪裡。不要修改遊戲程式碼。

我們把這段指令拆開來看。您自己的任務也用得上這幾個部分：

• "透過頁面介面下棋"是可衡量的動作，代理能在對話中實際展示；
• "data-game-over 變成 true 時，棋局才算結束"是唯一能算作真正結果的條件，評估器會在對話中尋找這項證據；
• "每走一步就讀取並顯示"提供了評估器可以檢查的資訊。沒有這句話，它就無從判斷；
• "如果下了 40 步仍未結束，請停止並說明"是 true 一直沒有出現時的額外指示。它不是成功條件，而是讓工作在未成功時停下來的方式：限制目標的工作範圍，但不取代結果。這仍然只是文字指令，不是程式控制的計時器，評估器也會根據對話來檢查；
• "不要修改遊戲程式碼"則說明代理追求結果的過程中，哪些事不能發生。

事先無法知道最後會怎樣，因此不能保證哪一方獲勝、棋局會下多久，甚至不能保證棋局一定結束。不過，代理必須展示的內容很明確：它讀到的遊戲狀態，以及繼續或停止工作的原因。

如何撰寫自己的條件

先從"任務在……時就算完成"這句話開始。如果後面接的是"一切都變好了"，代理就得自行猜測您的意思。把主觀評價改成看得見的行為，例如："清除搜尋條件後，所有卡片都會重新顯示"。只要多項檢查都在描述同一個結果，例如修好的搜尋功能，就可以一起列出。

• 說清楚結果。"修好搜尋"只指出方向；"搜尋能依名稱找到卡片，清除條件後也會顯示完整清單"才明確說出何時算完成。
• 列出驗證方式。寫清楚要開啟什麼、輸入什麼，以及預期會得到什麼回應。請代理在對話中展示實際結果，讓評估器讀得到。
• 限制修改範圍。如果只需要改樣式，就明確說出來。如果代理是在測試已完成的遊戲，就禁止它為了達成結果而修改遊戲程式碼。
• 預先說明未成功時如何停止。例如，嘗試修正並重新檢查三次後，代理應描述仍存在的問題。這是工作上限，不是另一種宣告任務完成的方式。

啟動前，請確認代理能存取所需的頁面、檔案和工具。條件中的網址與元素名稱必須符合您的專案。以文字設定嘗試次數上限有助於控制工作，但不是限制時間或費用的硬性技術機制。

請留意往回指的箭頭。如果結果尚未達成，代理會進入下一輪工作，可以修正問題後再檢查一次。不過，離開這個循環不一定代表成功：遇到障礙或達到約定的上限，都要另外說明。圖中呈現的是條件運作方式；代理和評估器會根據對話追蹤嘗試次數。

可套用到自己任務的三個範例

以下是針對現有頁面的練習條件。執行前，請換成您自己的網址、資料和預期行為。這些是條件範例，不是已完成工作的報告。

修正目錄搜尋

假設本機目錄裡有"Atlas"和"Orion"兩張卡片，但清除搜尋條件後，清單仍然是空的。只說"把搜尋做好"並沒有描述您想要的行為。這時最好列出三個具體情況：

/goal 修正 http://localhost:3000/catalog 的目錄搜尋。
輸入"atlas"時會找到"Atlas"卡片，
輸入"zzzz-no-match"時會顯示"找不到結果"，
清除欄位後則會還原所有原始卡片，這樣才算完成。
請透過 Playwright 檢查這三種情況，並在對話中展示
搜尋文字、預期結果，以及頁面實際顯示的卡片或訊息。
最後一次修改後，請重新檢查全部三種情況。
只修改搜尋邏輯；不要修改目錄資料或樣式。
如果修正並檢查三次後問題仍然存在，
請停止並列出哪些情況仍無法正常運作。

"全部"這個詞很重要：只找到一張卡片，還不足以證明搜尋已修好。目錄資料是固定的，因此不能靠重新命名卡片來製造預期結果。最後一次修改後再檢查也有必要，因為修好清除功能時，可能順手把搜尋本身弄壞。

只檢查表單，不做修改

目標也可以是整理一份觀察結果。假設您要檢查已完成的註冊表單，而修正工作打算另外討論。這時即使發現錯誤，只要所有情況都檢查完，目標就算完成。

/goal 透過 Playwright 檢查 http://localhost:3000/signup 的表單，
不要修改專案檔案。
請檢查以下兩種情況，每次都從空白表單開始：
1. 不填任何欄位就按下"註冊"。
預期會提示必填欄位，且不會完成註冊。
2. 在 email 欄位輸入"alex"，其他必填欄位填入有效的練習資料，
再按下按鈕。
預期會出現 email 格式錯誤，且不會完成註冊。
當對話中包含這兩種情況的報告，就算完成：
輸入了什麼、預期結果、頁面顯示內容，以及是否符合預期。
不要使用有效的 email 送出表單，也不要建立帳號。
如果無法開啟頁面或元素，請停止檢查，
並指出哪個情況尚未檢查及原因。

請注意兩者的差別："檢查表單"和"讓表單能正常運作"是兩種不同的任務。只要代理確實檢查了兩種情況並展示結果，即使表單有錯誤，報告仍可完成。但頁面無法存取就不行：用猜測取代實際觀察，不能算達成目標。

讓頁面適合手機瀏覽

"把手機版做漂亮一點"把太多事情留給代理自行決定。請指定頁面、視窗尺寸，以及必須保持可用的元素。

/goal 修正 http://localhost:3000 頁面的樣式，
視窗尺寸為 390x844 和 1440x900。
兩種尺寸都沒有水平捲動，標題和"開始"按鈕完整顯示、互不遮擋，
而且按下"開始"後仍會開啟遊戲區塊，這樣才算完成。
最後一次修改後，請透過 Playwright 檢查兩種尺寸。
展示畫面截圖、點擊結果，以及頁面根元素測得的
scrollWidth 和 clientWidth：
scrollWidth 不應大於 clientWidth。
只修改 CSS。不要隱藏或裁切內容來消除捲動。
保留原有文字和遊戲行為。
如果修正並檢查三次後條件仍未達成，
請停止並展示尚未符合的部分。

這裡的尺寸是瀏覽器視窗的寬度和高度，單位為像素。scrollWidth 是包含視窗邊界外部分的內容寬度，clientWidth 則是可用寬度。比較兩者有助於找出溢出的內容，但光靠這項檢查，無法證明文字沒有被裁切或按鈕可以操作。因此條件還要求截圖和點擊測試。兩種尺寸也無法證明所有裝置都好用，它們只是界定這項任務的範圍。

請代理協助擬定 goal

您不必從零開始撰寫條件。Claude Code Best Practice 彙整了社群的兩個建議：請代理依據專案脈絡提出目標，或讓它先讀取對話和檔案，再替您擬好條件。以下將這些做法調整為適合小型任務的版本。

如果還不確定該把哪些事交給長時間執行的工作，可以先傳一般訊息，不使用 /goal：

請閱讀目前的對話，以及與任務相關的專案檔案。
提出三個有用且能以可驗證結果作結的目標。
每個目標都請說明結果、驗證方式、修改範圍，以及啟動前還缺少什麼。
請依據我們已達成的共識。先不要啟動目標，也不要修改檔案。
如果我的意圖不清楚，請先提問。

選一個目標即可。工作時間長不代表更有價值：與其花幾個小時做不明確的"改進"，不如把搜尋功能修好。如果任務已經很清楚，可以略過第一個請求，直接請代理擬一份條件草稿：

請根據我們的對話、專案檔案和文件，為選定的任務撰寫 /goal 內容。
現在先不要執行任何操作。
請指出可觀察的結果、驗證方式，以及要在對話中展示什麼。
補上修改範圍，以及未成功時的停止條件。
不要自行編造網址、指令或完成標記：
請從專案中確認，或向我提問。
請回覆一份完整文字，並另外列出尚不明確的地方。

送出草稿前，先確認內容是否符合您的意思。結果真的是您想要的嗎？指定的頁面存在嗎？代理有沒有在草稿裡順便允許修改資料或新增功能？如果最後還列著不明確的地方，先把它們釐清。等內容確認後再啟動，因為 /goal 指令會立刻開始工作。

查看狀態並停止工作

目標執行期間，您可以隨時查看進度：不帶參數執行 /goal，就會顯示目前條件、已經過的時間和工作輪數，以及評估器回傳的最新原因。

您也可以用 /goal clear 提前停止目標，即使棋局還沒結束也一樣。

這裡已確認的結果只有一種：條件已達成，而且評估器在對話中的回覆能證明這一點。用 /goal clear 清除目標也是一個明確的結局，但那是您決定停下來，而不是工作已經完成的證明。目標自行停止的其他原因，都不能證明結果已達成。

評估模型實際收到什麼

/goal 評估器看到的不是頁面本身，而是對話內容：代理寫了什麼，以及它從瀏覽器觀察結果中複製了什麼。評估器沒有自己的工具，不會重新開啟頁面或自行執行指令，只會讀取目前累積的文字。

因此，代理說"棋局結束了"，本身並不能向評估器或您證明任何事。能證明結果的是代理確實從頁面讀到的內容，也就是 data-game-over 的值。前者是代理的說法，後者是實際觀察；即使聽起來相近，仍是兩回事。

也要了解這項指標的限制。data-game-over 回報的是特定應用程式的狀態，也就是頁面作者寫入的資訊。它不能證明整盤棋都依照西洋棋規則正確下完。同樣地，沒有水平捲動，也不代表按鈕一定能正常使用。請根據真正想達成的結果選擇指標，別把它解讀得超出實際含義。

這對工作方式有什麼改變

您可以用同一套簡短流程處理自己的任務：

• 明確的結果，以及可實際使用的驗證方式；
• 透過 /goal 設定條件，並列出修改範圍和停止方式；
• 隨時可查詢的狀態：不帶參數執行 /goal；
• 以觀察結果和檢查結果為依據的結論；
• 如果工作卡住或條件不合適，就手動執行 /goal clear 清除目標。

自動繼續工作，和決定接下來該做什麼，是兩件不同的事。在同一個工作階段中，您可以把前者交給 /goal。後者仍由您負責：判斷實際完成了什麼、清除尚未完成的目標，再設定下一項任務。

評估器的實際行為和狀態格式可能因 Claude Code 版本而略有不同。整體原則不變：根據對話進行評估，而不是直接存取頁面。