M3a：Quick Win 專案（Todo List）¶

目標：跟 Claude 一起做出一個跑得起來、被你改造過的 Todo List CLI。時長：40 min

你做完會有的東西

一個可以 add / list / done / remove todo 的命令列工具
多了你自己加的一個功能（分類、截止日、優先順序...由你挑）
「我可以叫 Claude 幫我做東西」的真實經驗

為什麼是 Todo List？¶

對零經驗學員來說，門檻低比「好用」重要： - 不需要外部 API（不會卡在註冊帳號、申請 key） - 不需要 GUI（先 CLI 確認邏輯對，看起來陽春但跑得起來） - 資料存在 todos.json（純文字檔，記事本能打開看） - 你自己會用 Todo List（驗收結果有感）

步驟 1：下載範例專案¶

範例專案放在這個訓練站的 templates/todo-list/ 資料夾。你的講師會給你一個 zip 檔，或者你可以從 GitHub repo 直接下載。

你現在要做

把 todo-list 整個資料夾複製到桌面

在終端機進入這個資料夾：

WindowsmacOS

cd $HOME\Desktop\todo-list
ls

cd ~/Desktop/todo-list
ls

你應該看到

app.py
README.md
TASKS.md
.gitignore

卡住了？

找不到 zip → 問講師、或從 GitHub repo 下載
顯示「找不到路徑」→ 確認資料夾真的在桌面、名稱真的是 todo-list

步驟 2：跑跑看（不要改任何東西）¶

先確認原始版本能跑，再開始改。

你現在要做

在終端機依序輸入（macOS 學員：python 換成 python3）：

python app.py
python app.py add "買咖啡"
python app.py add "寫週報"
python app.py list
python app.py done 1
python app.py list
python app.py remove 2
python app.py list

你應該看到

Todo List — minimal CLI
Commands:
  python app.py add "buy coffee"
  python app.py list
  python app.py done 1
  python app.py remove 2

Added: 買咖啡
Added: 寫週報
1. [ ] 買咖啡
2. [ ] 寫週報
Done: 買咖啡
1. [x] 買咖啡
2. [ ] 寫週報
Removed: 寫週報
1. [x] 買咖啡

Todo List CLI 原始版本跑起來的輸出：add 加項目、list 顯示、done 標完成

卡住了？

Windows：顯示「`'python' 不是內部或外部命令」→ 回 M1 的步驟 3「安裝 Python」重裝
macOS：顯示「command not found: python」→ 用python3不是python`
Windows 中文變亂碼 → 範例 app.py 已內建 UTF-8 強制；若還是亂碼，PowerShell 先跑 chcp 65001
macOS 通常 UTF-8 預設沒亂碼問題
完全沒反應 → 截圖貼給 Claude 看（等下會教）

步驟 3：看看資料存哪裡¶

打開 todo-list 資料夾，會多出一個 todos.json。

你現在要做

打開 todos.json 看一下長相。 - Windows：用記事本（Notepad） - macOS：用 TextEdit（按住 Ctrl 點檔案 → Open With → TextEdit）

你應該看到

[
  {
    "text": "買咖啡",
    "done": true
  }
]

這就是你的 todo 資料。是純文字 JSON 檔。你的程式不過就是「讀這個檔、改這個檔、寫回這個檔」。

為什麼讓你看這個？

讓你知道：程式不是黑盒子。你的資料就在那邊，看得到、摸得到、爛了還能用記事本修。

步驟 4：決定你要改造什麼¶

打開 TASKS.md，看裡面的改造方向。挑一個就好。

建議從 🟢 易那邊挑（10-20 min 做完）：

加分類欄位
加截止日期
加優先順序
改顯示樣式（加 emoji、加框線）

不要貪心

第一次跟 Claude 做東西，做一個小改造做完整比「樣樣都動」有成就感。剩下的下次再做。

挑一個之後，記下你的選擇，繼續下一步。

步驟 5：用 Claude Code 開啟這個資料夾¶

你現在要做

確認你還在 todo-list 資料夾，然後啟動 Claude Code：

WindowsmacOS

cd $HOME\Desktop\todo-list
claude

cd ~/Desktop/todo-list
claude

Claude 啟動後會自動讀取當前資料夾的內容。

你應該看到

Claude Code 啟動，提示符出現。

步驟 6：請 Claude 先看懂專案¶

不要一上來就叫 Claude 改。先讓它讀過、看懂這個專案。

你現在要做

跟 Claude 說

請先看 app.py 跟 README.md，告訴我這個專案是做什麼的、有幾個功能、資料怎麼存。不要改任何東西。

你應該看到

Claude 會用 Read tool 讀檔（可能跳出權限提示，選 Yes 或 always allow），然後回給你一段摘要，類似：

這是一個極簡的 Todo List CLI 工具。功能：

add — 新增一個 todo

list — 列出所有 todo（含完成狀態）

done — 標記某個 todo 為完成

remove — 刪除某個 todo

資料存在 todos.json，是一個 list of dict，每個 dict 有 text 和 done 兩個欄位。沒有外部相依套件，只用 Python 標準庫。

為什麼這步重要？

讓 Claude 先理解現狀再動手，可以大幅減少它「猜錯方向」的機率。類似你交辦事情給新同事，要先讓他看完背景再開始做。

步驟 7：請 Claude 做你選的改造¶

舉例：假設你選了「加分類欄位」。

你現在要做

跟 Claude 說（範例 — 加分類）

我想加一個新功能：每個 todo 可以有「分類」欄位（例如「工作」「生活」「學習」）。

規格： - add 指令多一個選擇性參數 --category 或 -c，例如： python app.py add "買咖啡" -c 生活 - 如果沒指定分類，預設「其他」 - list 指令的輸出要顯示分類，格式像： 1. [ ] (生活) 買咖啡 - todos.json 結構維持向後相容（舊資料沒有 category 欄位的，視為「其他」）

請改 app.py。改完跟我說你動了哪幾行、為什麼。

你應該看到

Claude 會： 1. 跳一個 Edit tool 權限提示（顯示 diff，讓你看它要改什麼）→ 你選 Yes 2. 回給你它的修改摘要，例如「我改了 cmd_add 接受 -c 參數、cmd_list 顯示 category、新增 todo 時預設 category=其他」

Claude 顯示 Edit tool diff，加 category 參數的紅刪綠加，下方權限提示

卡住了？

Claude 改完後你不確定它做對了什麼 → 問它：「請貼出修改後的 app.py 完整內容」
Claude 一口氣改太多 → 告訴它：「請先只改 cmd_add，其他先別動」
Claude 自己加了一堆你沒要求的功能 → 告訴它：「請回到只做我要求的功能、刪掉你自己加的東西」

其他改造方向的 prompt 範例

全部都在 TASKS.md 裡，你選哪個就用對應的那段。

步驟 8：驗證改造後還能跑¶

改完不一定對。要實際跑一次。

你現在要做

在終端機（另開一個視窗，或退出 Claude Code 後）跑：

WindowsmacOS

cd $HOME\Desktop\todo-list
# 先把舊的 todos.json 砍掉，從乾淨狀態測
rm todos.json -ErrorAction SilentlyContinue
python app.py add "測試項目" -c 工作
python app.py list

cd ~/Desktop/todo-list
rm -f todos.json
python3 app.py add "測試項目" -c 工作
python3 app.py list

你應該看到

類似（看你做了什麼改造而定）：

Added: 測試項目
1. [ ] (工作) 測試項目

卡住了？常見錯誤怎麼修

症狀	怎麼問 Claude
`SyntaxError` / `IndentationError`	「跑 app.py 出現這個錯誤：[貼整段]，請幫我修」
`KeyError: 'category'`	「我有舊的 todos.json 沒有 category 欄位，跑起來爆 KeyError，請加向後相容處理」
跑起來但結果不對	「實際輸出是 X，我預期是 Y，請看 app.py 哪裡寫錯」
完全沒反應	「我跑 python app.py [...] 沒有任何輸出，請檢查」

訣竅：錯誤訊息整段貼給 Claude，不要只貼最後一行。錯誤訊息頭上的 traceback 才是 Claude 要的線索。

步驟 9：玩一玩你的成品¶

加幾筆真的會用到的 todo，感受一下。

你現在要做

（macOS 學員：python 換成 python3）

python app.py add "週五交報表" -c 工作
python app.py add "預約牙醫" -c 生活
python app.py add "看完 Claude Code 教學" -c 學習
python app.py list

你應該看到

你自己的 todo list，跑在你自己改造的程式上。

改造後跑 todo list 顯示三筆 todo，括號標記彩色分類

這就是 quick win。🎉

M3a 完成檢查¶

原始版本跑得起來（python app.py list 不會爆）
你挑了一個改造方向、跟 Claude 對話完成
改造後跑得起來，看到你新加的欄位/功能
你大概理解 Claude 改了 app.py 哪幾個地方

✅ 全部 → 你可以選：

想多玩：去 M3b 進階探索試 GUI 或打包 .exe
直接結業：跳到 M4 專案級 CLAUDE.md

學到的訣竅 — 之後做別的小工具也用得上¶

先讓 Claude 讀懂、再動手：給 prompt 之前，要它先看現狀
規格寫得越具體越好：給範例輸入、範例輸出、邊界條件
錯誤訊息整段貼：不要只貼一行，traceback 越完整 Claude 越好修
每改一段、跑一次：不要連續改 5 個地方才跑，會分不清哪邊壞掉
不確定就問：「你剛剛改了什麼？為什麼這樣改？」

← M2 ｜ M3b（選修） → ｜跳到 M4 →