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

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

## 先認識 `starter.py`

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

先在專案根目錄進入練習資料夾：

```powershell
cd examples/stage-3/03-react-from-scratch
```

依[該題 README](../examples/stage-3/03-react-from-scratch/README.md) 安裝需求，下載並啟動 Ollama 模型。準備好後，先跑離線測試，再跑程式：

```powershell
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、觀測與復原讓長任務更可靠。

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

<details markdown="1">
<summary>⏱️ 查看練習時間安排</summary>

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

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

</details>

## 如果卡住

依序做：

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

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

## 給維護者

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