把需求說清楚，讓工作接得下去
這一章練習三件事：把想做的事交代清楚、遇到錯誤時提供足夠線索，以及讓下一次對話接得上。你不需要多裝工具，也不需要換模型。
一份任務要交代什麼
想像你請同學幫忙。他需要知道你要做什麼、資料在哪裡，以及做到哪裡算完成。給 agent 的需求也一樣。
| 要素 | 你要回答的問題 | 分群例子 |
|---|---|---|
| 目標 | 我想知道什麼？ | 比較群數改變時，分群結果有何差異 |
| 輸入 | 資料或既有程式在哪裡？ | 本專案的 lab1_cluster.py 與 sklearn digits |
| 限制 | 哪些方法或條件要保留？ | 沿用 random_state=0，用 uv run python 執行 |
| 輸出 | 要交付哪些檔案？ | 新程式、圖檔與一段解釋，放在指定路徑 |
| 完成判準 | 我要看到什麼才算完成？ | 檔案確實存在、程式跑完、解釋對得上結果 |
不必每次都寫很長。工作坊已把共通規則放進 AGENTS.md，每次只補上這個任務的條件。
練習：先自己寫一份需求
請 agent 把 Lab 1 的群中心畫回手寫數字影像。先自己寫需求，再展開下面的參考寫法。這裡選 k=10 是為了觀察十個群中心，並不表示每群一定對應一個數字。
參考寫法
把下列文字貼到 OpenCode 對話裡：
請先讀 lab1_cluster.py 與 AGENTS.md，整理目前的資料前處理與分群參數。
我要觀察 k=10 的群中心，各自像哪些手寫數字。
請另寫 lab1_centers.py，保留原檔；沿用原本的資料前處理，
使用 random_state=0、n_init=10，將十個群中心各自 reshape 成 8×8。
把十張影像排在同一張圖，標出群編號，存成 figs/lab1_centers.png。
用 uv run python 實際執行，印出群中心的 shape 與圖檔路徑。
最後說明：為什麼群編號不能直接當成數字標籤？這份需求指定了讀取來源、保留原檔、產圖方式與完成判準。如果你改成其他前處理，請先思考群中心能否直接還原成原本的像素尺度。
完成後自己開圖。確認十個群中心都出現、標籤是群編號，並用自己的話解釋其中一張模糊影像。agent 的解釋需要和你看到的結果相符。
把一個大任務分成幾次對話
不確定做法時，先讓 agent 提出步驟，再決定要執行哪一步。可以用 Tab 切換到 Plan，查看畫面上的模式標示；回到 Build 才開始寫程式。仍要閱讀每次的權限要求。
先不要修改檔案。請讀 lab1_cluster.py，告訴我若要比較不同 random_state，
哪些參數應該固定、需要保存哪些輸出，以及我能從比較中回答什麼問題。看完後再給下一步：
請先只做讀取資料與執行一次分群的部分，另存為 lab1_repeat.py。
跑完後印出資料 shape、參數和分群指標，先不要加重複實驗。等這一步能跑，再要求加入迴圈與圖。這樣發生錯誤時，你知道是哪一步引入的，也有機會在它大量產生檔案前調整方向。
出錯時怎麼求助
ModuleNotFoundError 是錯誤種類，下面的檔名與行號才說明它發生在哪裡。請保留從 Traceback 開始到最後一行的完整內容。不要只截取最後一個單字，也不要要求 agent 在看過錯誤前把整個專案重寫。
在原本執行程式的 PowerShell 或 Ubuntu 終端機確認位置：
pwd
ls然後把下面的範本填完整，貼進 OpenCode：
我在 Windows PowerShell／WSL Ubuntu（請保留實際使用的一個）遇到錯誤。
目前資料夾：填入 pwd 的結果。
執行指令：貼上剛才實際執行的完整指令。
預期結果：說明原本應該產生什麼。
實際錯誤：貼上從 Traceback 到最後一行的完整文字。
已嘗試：列出做過的操作與結果，沒有就寫尚未嘗試。
請先根據這些證據找原因，再提出最小修正。
不要刪除既有輸出，也不要重裝整套環境。
若需要更多資訊，告訴我應該執行哪一個檢查指令。錯誤內容可能包含自己的姓名或私人路徑；分享給同學前，把不需要的個人資訊遮掉。套件找不到時，先確認用的是 uv run python，並完成 uv sync。
網路模型暫時不能用
先確認網路，再重試一次。仍然失敗時，保留錯誤訊息，停下來找講師；可以先閱讀既有程式、圖片與教材的參考輸出，寫下自己的判讀。不要為了繼續操作而新增付款方式、升級方案或改接需要付費的模型。
Session、context 與壓縮
Session 是一串可回頭查看的對話；context 是模型這一次回應時能讀到的內容。程式會把對話、讀取的檔案與工具輸出放進 context，長任務不一定能一直保留所有細節。
| 目前狀況 | 怎麼做 |
|---|---|
| 同一題還在進行，只是關掉終端機 | 用 /sessions 找回正確的對話，核對名稱與內容 |
| 換了題目 | 用 /new 開新對話，重新提供相關檔案與目標 |
| 同一題對話已很長 | 先保存進度，再用 ctrl+p 搜尋壓縮功能，或按 ctrl+x c |
| 壓縮後漏掉重要條件 | 請 agent 重新讀取進度檔與原始程式，補上缺少的限制 |
壓縮會把舊內容整理成摘要，可能省去細節。檔案裡保存的公式、參數與結果，才是下一次可以重新讀取的依據。
續作練習：保存 notes/progress.md
先完成任一個 Lab。還在同一段對話時，請 agent 整理進度：
請整理目前這個 Lab 的進度，存成 notes/progress.md。
如果已經有這個檔案，先讀它，再更新這次已改變的內容。
請包含：
- 目前目標與已決定的限制
- 已完成的程式、圖與筆記的相對路徑
- 實際成功執行的完整指令
- 已看到的關鍵結果，以及它們支持什麼結論
- 尚未完成或不能確定的部分
- 下一個可以接著做的小步驟
只根據目前確實發生的事整理。沒有執行過的步驟不能寫成完成，
也不要為了寫進度而另做實驗。打開 notes/progress.md，核對檔名與結果。特別留意 agent 有沒有把「準備做」寫成「已完成」。
接著輸入 /new，在新的對話貼上：
請先讀 AGENTS.md 與 notes/progress.md，再查看其中提到的相關檔案。
先不要修改檔案，用自己的話說明目前做到哪裡、哪一件事還不能確定，
以及你建議接下來做的第一步。新的 agent 若能根據檔案說明進度，表示你已經把工作從一段聊天變成可以接續的專案。若它說錯，先修正進度檔，再要求繼續。
完成這章時
- 我寫過一份包含目標、輸入、限制、輸出與完成判準的任務。
- 我知道程式錯誤應連同執行指令與工作資料夾一起提供。
notes/progress.md記錄了實際成果，沒有把未完成的步驟寫成完成。- 我在新對話中請 agent 讀取進度，並核對它的理解。
接著可看 MCP、skills 與 subagent，把反覆使用的流程寫成自己的 skill；或到 數學應用 挑一個新題目。