用 Claude Code 查效能瓶頸：先量度，再一次改一樣

唔好由「幫我優化」開始

頁面慢，原因可能喺圖片、網絡、伺服器、資料庫，亦可能係瀏覽器主執行緒。只貼一個 React 元件，Claude 就只能分析眼前嗰部分，未必見到真正等待時間。

先定一個具體問題，例如「手機首次開產品頁，主要圖片幾時顯示」或者「同一負載下 API 嘅 p95 延遲」。LCP、API 延遲同建置時間係唔同指標，唔應混成一個「快咗」。

1. 留低可重複嘅基準

記錄程式版本、硬件、網絡、資料量、並行請求數、快取狀態同測試步驟。盡量用相同條件重跑幾次，保留每次結果，而唔只揀最好嗰次。

Lighthouse 嘅實驗室測試唔等同真實用戶量度；一般頁面載入報告亦唔會完整反映 INP 互動情況。TBT 同 INP 唔係同一個指標。解讀時先查官方 Lighthouse 說明。

2. 先叫 Claude 解讀證據

我要調查 [具體指標] 變差。程式版本、測試條件同原始報告喺 [檔案]。

先說明報告實際量到乜、未量到乜。指出最值得查嘅幾個位置，附報告欄位或時間區段，再列需要追讀嘅原始碼。

唔好將 CPU 採樣比例直接當成整個請求嘅等待時間，亦唔好由截取片段聲稱已找到全系統最大瓶頸。暫時唔改程式。

圖表上最闊嗰格可能包含子函數時間；幾個項目亦可能重疊。加總前要先知道工具顯示嘅係總時間、自身時間、樣本比例，定估算成本。

3. 用另一份證據核對假設

例如訂單列表每張訂單都再查一次明細，查詢次數隨訂單數量增加，可以支持 N+1 假設。但一次請求有好多 SQL，亦可能係設計需要，唔一定全部都可以合併。

根據同一個請求嘅追蹤記錄、查詢次數同訂單函數，確認查詢由邊度觸發。

比較少量同較多訂單嘅查詢數及耗時，分開網絡等待、資料庫執行同程式處理。列出支持 N+1、重複查詢或索引問題嘅證據，唔足就指出下一個量度。

PostgreSQL 嘅 EXPLAIN 成本唔係毫秒；EXPLAIN ANALYZE 會實際執行查詢，唔係純唯讀解說。先喺受控環境用代表性資料試，尤其唔好對修改資料嘅 SQL 直接加 ANALYZE。順序掃描亦未必係錯，可能比索引更適合該資料量。官方 EXPLAIN 文件解釋咗估算同實測嘅分別。

4. 一次改一個可驗證因素

已確認原因及證據：[填寫]。

提出最小修正，說明預期改善邊個指標，以及可能影響嘅行為。保留排序、分頁、空結果、權限、錯誤同資料一致性要求。

先跑正確性測試，再按相同基準重新量度。唔好順手升級套件或調整其他快取設定。

例如批次載入明細，要核對空清單、大批 ID、軟刪除同租戶條件，唔只比較 SQL 次數。圖片優化亦要確認畫質、版面大小同真正 LCP 元素，唔係一律轉 AVIF 或延遲載入就更快。

5. 報告變化，同時報告限制

記錄修正前後多次量度、樣本數同波動。p95 係請求分布嘅百分位，唔等同幾次測試平均值；樣本太少時要明講。

包大小圖可以話你知輸出包含乜，但唔一定量到建置插件耗時。建置問題要另外量各階段，分清安裝、型別檢查、打包同快取命中。

如果改善仍落喺自然波動範圍，就唔好報成確定提升。目標已達成就記錄結果；未達標先重新量度下一個瓶頸，唔需要為咗追求更靚數字不斷加複雜度。