D1：準備代理架構與 SDLC 流程

D1-O1 將代理整合至軟體開發生命週期

把代理接進軟體開發生命週期（SDLC），首先要決定由它承擔哪一段工作，以及人如何判斷結果可接受。模型能產生程式碼，不代表它已理解產品的完成條件。需求若仍是「讓報表更好用」，直接要求實作，只會把尚未決定的產品取捨交給代理猜測。

先寫可觀察的任務契約

全書使用同一個教學案例：報表匯出 CSV 時，含逗號的欄位被拆成兩欄，團隊要讓代理修正。以下是示意需求，不是官方考題或特定產品的內建流程。

這份契約讓代理與審查者面對同一個問題。若只要求「測試全綠」，代理可能刪掉失敗測試也得到綠燈；把輸入與預期輸出寫清楚，才能指出真正要保護的使用者行為。

選擇值得委派的工作

有明確輸入、可重跑環境與驗收方式的工作，比依賴大量未寫明領域知識的任務容易控制。需求分析也能使用代理協助整理疑點，但輸出應是問題與選項，而非自行決定尚未核准的規格。GitHub 官方最佳實務同樣強調清楚範圍與完整驗收條件，並提醒寬泛、敏感或模糊任務需要更審慎處理。

GitHub 作為 system of record，意思是把需求、差異、檢查與決策放在能追溯的 issue、commit、PR 等紀錄中。聊天說過「已修好」，不能代替可定位到特定版本的測試結果。

判斷練習： issue 只寫「全面改善匯出效能」，代理要開始重構。最先補什麼？

解析： 補上代表性資料、目前耗時、可接受結果及不可改變的格式契約。若連瓶頸都未量測，先委派觀測與分析；不能把「可能更快」當成已確認的實作方向。

來源：GitHub Copilot 任務最佳實務（GH-DOC-03，2026-09-22 核對）；技能範圍：GH600-SG。

D1-O2 定義規劃、推理與行動的界線

規劃是在尚未造成副作用前，整理目標、假設、依賴與驗證方法；推理則支援比較方案與判斷下一步。行動透過工具讀取或改變環境，不能因為它被寫在計畫裡，就視為已執行或已獲准。

不必要求代理提供不可驗證的內部思考過程。審查需要的是外部可檢查的理由：哪份資料支持判斷、哪些假設尚未驗證、為何選擇這個變更，以及什麼結果會推翻它。

把計畫寫成可核對的順序

匯出案例可以先讀取序列化程式與既有測試，再用最小資料重現欄位錯位；確認原因後，只修正欄位編碼，最後重跑逗號、引號、換行與空值案例。計畫還應說明：若需求其實是另一種檔案格式，先停止確認，不直接擴大成格式轉換專案。

在執行前審查這份計畫，要看它是否漏掉約束，而不只是步驟是否詳細。若最後一步突然包含「推送並部署正式站」，就已超過原先只交付差異與測試的契約。approval gate 必須對應實際待執行的動作、資源與版本；核准方向不等於授權所有後續衍生操作。

指令與強制控制的分工

Repository instructions 適合告訴代理建置方法、專案慣例與驗證要求。它們是提供脈絡的文字，不會自行建立檔案系統隔離或撤銷 API 權限。需要保證某個動作不能執行時，仍要依賴工具權限、執行環境或受控核准路徑。具體工具設定留到第二章討論。

判斷練習： 人核准「修正匯出並驗證」，代理發現可順便更新驗證框架。是否可以直接做？

解析： 先判斷更新是否是本次修復的必要條件。若現有測試足以驗證，就維持原工具鏈；若確實被版本問題阻擋，提出可重現證據與新增變更範圍，再取得相應決策。不能把核准的目標解讀成不限手段的授權。

本節的任務契約與核准設計為教學示例。技能範圍：GH600-SG；指令設定延伸閱讀：GH-DOC-04。

D1-O3 設定自主代理的可觀測性與控制

可觀測性讓人知道代理做了什麼、為何停下，以及結果落在哪個版本；控制則讓人能限制、暫停或終止工作。只有日誌而不能阻止越界，是看得見卻管不住；只有核准按鈕而沒有差異與測試，則是要求人盲目決定。

讓產物回答審查問題

代理在獨立工作目錄與指定分支修正 CSV 並執行測試，可以由明確契約授權自動完成；是否合併或發布則取決於工作流程與權責配置。人應在需要判斷取捨或承擔副作用的位置介入，而不是對每一次無副作用的檔案搜尋重複按確認。

停止也要有具體條件，例如「預期只改匯出模組，卻需要變更資料庫結構」或「相同步驟重試後仍無法確認寫入結果」。停止後保留差異、未完成事項與已知副作用，才能讓下一個人安全接手。

判斷練習： 代理回報 20 項測試通過，但沒有 commit 識別，PR 又新增了一筆修改。這份證據能支持合併嗎？

解析： 先把測試結果對回實際受測版本；若新增修改未被測試，必須補驗。測試數量不會補足版本關聯的缺口。第四章會進一步處理成功訊號與誤導性指標。

技能範圍：GH-600 Study Guide（GH600-SG）；案例與檢查表為本書設計，並非官方固定程序。