Claude Code｜快速讀懂陌生專案

接手陌生專案時，先建立可核對的地圖，比立刻要求重構更有幫助。本篇會用 Claude Code 找出入口、資料流程、工具命令與測試缺口，最後產出一份簡短導覽。你會學會要求檔案證據，也能分清楚已確認事實與仍需追查的推測。

請使用練習專案，把它當成第一次看到的程式庫。整篇先採只讀方式，不需要跑 /init 或修改規則檔。若是團隊真實專案，先閱讀已有的 CLAUDE.md、README 與任務協議，保留既有變更，避免探索時順手改動別人的工作。

第一輪只回答專案怎麼組成

閱讀完整文字說明

快速讀懂陌生專案，以流程和文件圖形呈現教學重點。

請 Claude 先列主要目錄與入口，不必把每個檔案逐行解釋。你需要知道這是什麼應用、如何啟動、主要資料存在哪裡，以及測試在哪裡。每項結論都應附可供開啟的檔案位置，不能只憑檔名猜框架。

請只讀分析目前專案，先閱讀 README.md、package.json 與主要入口。
整理技術組成、啟動方式、核心檔案與測試位置。
每項結論附實際檔案依據，推測的部分請標明。
先不要修改、安裝套件或執行資料變更命令。

本練習的合理結果應是原生 HTML、CSS、JavaScript 加 Node.js 本機伺服器，而不是套用常見框架模板。若它說有資料庫，要求指出連線設定或存取程式；找不到證據就應把這項結論撤回。學習看證據，比背工具生成的架構名詞重要。

沿一個使用者操作追查

選擇「新增待辦」這個可見行為，從 index.html 的表單開始，追到 app.js 的 submit 事件，再到 model.js 的 addTodo，最後回到 DOM 呈現。這條流程能把靜態檔案清單變成真正可理解的程式行為。

請追蹤使用者按下新增後的完整路徑。
指出表單、事件監聽、資料函式與 render 各在哪裡。
說明空白文字被拒絕時，畫面如何通知使用者。
請用實際函式名稱與檔案佐證，先不修改。

讀回覆時核對每個箭頭是否真的有呼叫關係。函式名稱相似不一定互相連接，註解也可能過期。必要時自己打開兩個相鄰檔案看輸入與回傳值，確認資料從哪裡來、在哪裡被更新，以及畫面何時重畫。

確認執行命令的真實含義

package.json 中的 scripts 是命令入口，但名稱不能保證作用。先讀 npm start 實際呼叫的 server.mjs，知道它監聽哪個位置；再看 npm test 找哪些測試檔。真實專案可能在啟動時執行遷移、下載或資料更新，應先理解再執行。

請說明 package.json 每個 script 實際執行什麼。
檢查是否需要外部服務、環境變數或資料庫，列出證據。
若 npm test 只執行本地測試且不修改外部資料，請執行並回報結果。

測試通過後記錄數量與涵蓋範圍，不要直接宣稱網站所有行為都正確。本練習的 model 測試主要涵蓋資料操作，未必涵蓋實際瀏覽器中的焦點、按鈕版面或螢幕閱讀器資訊。這些應列為後續手動或瀏覽器驗證項目。

找出狀態與邊界

詢問目前資料保存在哪裡、重新整理後會怎樣，以及輸入如何驗證。起始版 items 保存在頁面記憶體，因此重新整理會清空；參考完成版另有 localStorage。先辨認自己拿到哪份材料，才能把現象判斷成設計、限制或錯誤。

再檢查切換與刪除使用 id 還是畫面索引。這會影響之後加入篩選的正確性：顯示順序變了，資料識別仍應穩定。陌生專案導覽的價值就在於找到這類會影響下一個需求的條件，而不是只列出程式行數。

產出短而可更新的導覽

接手時也要列出外部依賴的邊界，即使答案是「目前沒有」。例如本練習沒有登入、資料庫或遠端 API，所有資料操作都在瀏覽器；這會直接影響你能測試哪些情境。真實專案則可能需要後端、佇列或第三方帳號，應分別指出設定位置與是否已實際連線，不能把設定檔存在當成服務可用。

另一個值得確認的是錯誤如何呈現。輸入空白待辦時，model 回傳原資料，app 再顯示提示；這個約定連起兩個模組。若日後改成丟出例外，就需要同步處理呼叫端。理解這種模組契約，能幫你在新增功能時預測可能受到影響的地方。

請用五段整理專案導覽：
1. 應用用途與技術組成。
2. 一次新增待辦的資料流程。
3. 啟動與測試命令及實際結果。
4. 已知限制與尚未驗證的部分。
5. 若要加入篩選，建議先閱讀的檔案。
每段保留必要檔案連結，不複製整份原始碼。

先審查這份導覽，再決定是否保存到文件。若只是自己一次性的理解筆記，不必立刻變成所有 session 都載入的 CLAUDE.md。長期指引應只保留穩定、必要的規範；容易由程式取得的細節，維護時重新查證通常更可靠。

常見錯誤與小練習

常見錯誤包括讀錯專案根目錄、只根據 README 判斷現況、把沒有跑過的命令寫成已通過，以及為了理解程式先做大規模改寫。遇到這些情況，回到只讀問題、檔案證據與執行紀錄，逐項修正結論。

小練習是把同樣流程改用「刪除待辦」再走一次，檢查不同標題相同、識別碼不同的兩筆資料會怎麼處理。完成判準是你能自己沿著入口、事件、資料與畫面解釋一次操作，並指出測試與未驗證範圍。接下來就能進入新增小功能。

回 Claude Code 教學總目錄

• AI 工具
• 教學
• Claude Code