D4：執行評估、錯誤分析與調校

D4-O1 定義成功標準與評估訊號

評估先問使用者要得到什麼，再選能觀察它的訊號。匯出案例的成功不是「代理寫了程式」，而是讀取匯出檔案的人能取得正確欄位，且原有格式沒有被破壞。測試通過率、耗時與成本有助於比較方案，但都不能替代這個行為定義。

把成果、限制與證據分開

Code scanning 分析程式中的潛在弱點；secret scanning 尋找支援類型的機密；dependency review 協助檢查依賴變更。它們處理的問題不同，掃描無告警也不能證明匯出規格已滿足。審查報告應說明用了哪些工具與設定，而不是把任何一個綠勾概括為「安全」。

GitHub status checks 是傳遞檢查狀態的機制，是否阻擋合併還取決於分支規則。官方文件也說明，被跳過的 job 可能回報 success；所以必須確認預期的工作確實執行，且結果對應目前提交。不要把「可合併」與「所有驗收情境都測過」混為一談。

判讀示例：同一份 PR 的四種證據

假設 CSV 修正已產生差異，交付包包含以下紀錄。表格中的結果是原創教學資料，不是本專案的實際掃描或測試報告。

這些證據互補，不能互相代替。換行未測不能由安全掃描補成通過；格式測試通過也不能撤銷掃描發現的弱點。若掃描出現告警，先定位規則、路徑、適用版本與可到達的程式流程，再決定修正或依政策處理；不能只因代理說「誤報」就忽略。

Status check 的綠燈還要追到實際 job 與步驟。官方文件描述被跳過的 job 可回報成功，但整個 workflow 未觸發、或 required check 一直等待，是不同情況。讀報告時應寫「換行測試未執行」，而不是把檢查列的成功概括為「全部測試通過」。

產物練習： 為上述 PR 寫兩句交付判斷。第一句指出已驗證的輸入與版本；第二句指出換行缺口及補驗方式。參考回答：「此受測版本的逗號與引號案例通過。換行案例未執行，需在同一交付版本補跑，現有掃描結果不能代替它。」若 PR 又增加修改，原證據的適用性也要重新核對。

判斷練習： 改版後測試通過率從 90% 升到 100%，但失敗的換行案例被排除。代理品質改善了嗎？

解析： 沒有足夠證據。分母改變了，使用者需要的換行行為反而失去檢查。應用相同案例集合比較前後，另列新增或移除案例的理由；不能以跳過檢查來達成品質目標。

來源：Status checks（GH-DOC-17）；Code scanning、Secret scanning、Dependency review（GH-DOC-18、GH-DOC-19、GH-DOC-20）。2026-09-30 核對；證據表與交付練習為教學設計。

D4-O2 分析代理失敗並識別根因

先保存可重跑的失敗輸入與版本，再整理時間線：代理讀了什麼、選擇了哪個工具、工具回傳什麼，以及哪個觀察首次偏離預期。最後才提出根因假設。若一開始就認定「模型不夠聰明」，後續很容易只尋找支持這個判斷的訊息。

用能區分原因的實驗縮小範圍

這些分類可以同時出現，不能只依錯誤字串硬選一類。缺少套件可能源於安裝步驟被跳過，也可能源於代理誤刪依賴宣告。找出可修正的因果鏈，才比貼上分類標籤更有用。

例如本機正常、runner 失敗時，先固定程式版本，只修正缺少的執行階段。如果同一測試恢復，就支持環境假設；若仍失敗，應撤回「只缺 SDK」的結論，繼續檢查其他差異。多跑幾次偶然通過，不能證明根因已消失。

診斷示例：測試通過，產物卻仍錯誤

假設代理說「CSV 測試通過」，但審查者用含換行的資料仍看到錯誤。先不要加長提示或換模型，先保存下面這份時間線。任務與步驟名稱是示意，不是任何產品固定的日誌格式。

任務：CSV-LF-01
步驟 1：讀取目前格式契約。
要求保留欄位內換行。
步驟 2：代理在另一個模組測試。
命令結束碼為 0。
步驟 3：代理摘要為
「CSV 測試通過」。
步驟 4：審查者在匯出模組
測試換行，斷言失敗。

步驟 2 與 3 的落差支持「測試工具使用或結果解讀錯誤」，尚不能解釋匯出程式如何破壞換行。這裡有兩條需要分開查的因果鏈：為什麼錯誤沒有被代理發現，以及程式為什麼產生錯誤輸出。

保持程式版本與輸入固定，改在正確目錄重跑原本應執行的案例。若能重現格式錯誤，就證明先前的綠燈沒有驗證這項需求；接著讀取匯出實作，找出造成錯誤輸出的處理步驟。若正確案例反而通過，應撤回「目前程式仍有相同缺陷」的假設，查核審查者使用的版本與輸入差異。

產物練習： 在診斷紀錄分別填「已觀察」「候選原因」「區分實驗」「撤回條件」。本例可寫：已觀察到測試目錄不符；候選原因是工具誤用；區分實驗是在同一版本的匯出模組執行相同輸入；若原紀錄其實確實涵蓋該模組，便不能再以目錄錯誤解釋漏測。不要把尚未讀過的序列化程式直接列為已確認根因。

判斷練習： 日誌最後一行是「PR 建立失敗」，應先改 PR 內容嗎？

解析： 先查看實際工具回應，分清驗證失敗、網路逾時與權限拒絕。標題格式錯誤才需要調整內容；身分不具權限則需要走授權處理。症狀文字沒有提供足夠證據時，把原因標為未知，不用推測補齊。

技能範圍：GH600-SG；產品診斷延伸閱讀：GH-DOC-22。代理產生的審查意見（GH-DOC-24）同樣是待查證線索，不會自動成為根因。

D4-O3 依評估結果調整代理行為

調校應對準已確認的失敗機制。代理漏讀格式要求，可以改善任務輸入或文件查找；工具參數反覆錯誤，可以改善工具契約；環境缺依賴，應修正環境準備。把每個問題都改寫成更長的 prompt，會讓系統愈來愈複雜，卻不一定修到原因。

建立可比較的基線

保留調整前的程式、指令、工具設定與 evaluation set，再選一個主要變因修改。匯出案例可先加入「修改前讀取格式契約並列出邊界案例」的指令，觀察是否降低漏測，而不是同時換模型、換工具與換測試資料。

評估集合應包含已知失敗案例，也包含原本正常的情境與尚未用來調校的代表性案例。只測剛修好的逗號案例，可能看不見空值或引號處理退步。若代理輸出具有變動性，可在相同條件下重複觀察，記錄每次結果與失敗分布；不要只保留最好的一次。

提升通過率之外，也要看是否增加權限、人工介入、時間或成本。若方案 A 每次都要求人替它做關鍵判斷，它的成功率不能直接與自主完成同一工作的方案 B 比較。評估應保留任務條件與人工協助程度。

對照示例：指令調整改善了什麼

假設已確認代理常在未讀格式契約前修改程式。保留原指令為 A，只在 B 加入「先引用格式契約，再列出邊界案例」，其餘模型、工具、權限、任務資料與時間預算保持一致。每次執行都從相同程式基底與乾淨任務狀態開始，避免 B 直接承接 A 已修好的產物。

以下是教學用對照表，不能當成實際改善成果或統計結論：

若 B 仍漏掉換行，不應先宣稱整體能力提升。先看它是否讀到契約、是否列出該案例、是否真的執行測試，再針對已確認的失敗調整。若人工介入不同，就不能把最後通過率全歸功於新指令。

未參與調校的案例用來檢查遷移能力；一旦看過它的失敗並據此改指令，它就成為調校資料，後續仍可作回歸測試，但不能繼續當作未見案例。測試集合也應有版本，保留每次結果，避免反覆挑選最好的一次或偷偷縮小分母。

產物練習： 寫一份調校決策，列出唯一改動、固定條件、每次結果、人工協助及採用／撤回理由。若新指令使原本正常的空值案例退步，就依事先約定的門檻停止採用並恢復舊指令；設定恢復不會自動還原已經改動的程式與外部資料，這些產物仍須分別核對。

判斷練習： 增加幾段提示後，已知題庫全部答對，可以宣稱泛化能力提升嗎？

解析： 先確認是否只是記住固定案例。用未參與調校、但仍代表相同需求的資料檢查；若新資料依舊失敗，只能說特定案例改善。對部署中的代理，還要訂出回復舊設定的條件，避免把調校變成不可追溯的連續試錯。

技能範圍：GH600-SG。基線與對照實驗是本書採用的工程方法，並非官方保證的分數提升程序。