How to use this curriculum — 每次只改一件事

這份學習地圖不是考試。你不用先抄一份空白檔案，也不用把完整程式重新默寫一次。 最簡單的學法是：先跑起來，再改一件小事，最後用測試看差別。

先認識 starter.py

每個練習 folder 裡的 starter.py 是一份可以直接執行的起點。它不是空白作業紙， 也不是只能偷看的答案。它的工作是先給你一個「真的會動」的小系統，讓你有東西可以改。

你第一次打開一題時，只做這些事：

cd examples/stage-3/03-react-from-scratch
python test.py
python starter.py

如果這題另有 test_anthropic.py 或 README 指定的離線測試，也照 README 的第一個動作執行。 先確認原版能跑，再開始改；這樣出錯時，你知道問題來自剛剛那個小改動。

六步學習循環

1. 看成果：先讀 README 的「你會做出什麼」和成功條件。
2. 直接執行：複製第一組命令，讓原版測試通過。
3. 選一個小改動：只改一個輸入、規則、工具或停止條件。
4. 先猜結果：用一句話寫下「我覺得會發生什麼」。
5. 再跑測試：看實際結果是否和猜的一樣；不一樣就讀錯誤訊息。
6. 說出原因：用自己的話解釋這一行為什麼會改變系統。

這個循環可以一直重複。一次只改一件事，像一次只換一塊積木；倒了時才知道是哪一塊造成的。

可以改什麼？

先選最小、可回復的變化：

• 把一個測試輸入換成空字串、很長的文字或未知值。
• 新增一個工具參數，然後補一個會失敗的測試。
• 把 max_iter 調小，看看 Agent Loop 怎麼停止。
• 暫時拿掉一個欄位，觀察 schema 驗證會回報什麼。
• 改一條 prompt 規則，再用同一組案例比較前後結果。

不要一次換模型、改 prompt、加工具又改測試。四件事一起動，失敗時很難知道原因。

每題做完問自己三句話

1. 為什麼要這樣寫？ 例如 Agent Loop 為什麼要把 tool result 放回 messages？
2. 拿掉它會怎樣？ 例如沒有 max_iter、schema 或 approval gate 會發生什麼？
3. 真實環境還缺什麼？ 通常要再補 auth、eval、observability、retry 或人工核准。

測試通過只表示目前檢查的行為正確。你能回答這三題，才表示你知道系統為什麼會動。

章節怎麼接

• Stage 3 先學 Agent Loop：模型叫工具、工具回結果、模型再決定下一步。
• Stage 4（Workflow Graph／Agent Framework）：把多個步驟、分支與人工核准接起來。
• Stage 6 學 RAG 與 Memory：讓系統找到證據，並保存真的需要保留的狀態。
• Stage 7 學 production control：用 Harness、Eval、觀測與復原讓長任務更可靠。

不用等到每題都完美才往下走。如果下一章的第一個核心詞看不懂，就回上一章挑一題再做一次。

⏱️ 查看練習時間安排

不要用固定小時判斷自己學得好不好。先留一個不被打斷的小時，完成一輪「執行 → 小改動 → 測試 → 解釋」。如果一題太大，就只做第一個成功條件；下次再接著做。

時間很少時，每個 Stage 先選一題完整走完，其餘題目先看成果與成功條件。完整做完一題， 通常比匆忙讀過五題更有用。

如果卡住

依序做：

1. 看終端機最上面第一個真正的錯誤，不要只看最後一行。
2. 用 git diff 看自己剛改了什麼；先手動還原最後一個小改動，再跑一次測試。
3. 讀 README 的成功條件、常見問題與該題測試名稱。
4. Tool calling 問題可看 examples/stage-5/tool-calling-tutor/。
5. 還是不懂就開 issue，附上使用的命令、錯誤訊息、環境版本與最小 diff；不要貼 API key。

卡住不表示你不會。它只表示「預期」和「實際結果」不同；把差別縮小到一個改動，就能繼續查。

給維護者

每個練習的可見入口要提供可直接複製的第一個動作、成功條件與「只改一件事」。不要再要求 讀者建立空白文字檔、改名藏起完整範例或整份重寫。若未來新增 TODO template，它必須是 額外選項；現有可執行 starter 與離線測試仍要保留。