benchmark-checklist | 查核效能數字是否可信
本頁以 pstack-claude 0.9.126 為基準。本次不執行基準測試，也沒有實測的加速數字。
定位與適用情境
基準測試 (benchmark) 的快，不一定是使用者真正完成工作的快。此技能在回報或採用效能數字前，查核工作是否真的執行、是否出錯、比較是否公平，以及瓶頸能否解釋差異。
情境是團隊修改 CSV 匯出器，準備比較舊版 A 與新版 B 在同一份六萬列資料上的表現。輸入是兩個版本、量測腳本、資料集及執行環境。目標不是預設新版比較快，而是決定現有證據能否支持結論。
準備
- 先寫預計主張的句子，例如「在指定六萬列資料上，端到端匯出延遲降低」。數字要等量測後再填。
- 讀量測腳本，確認計時區間、資料筆數、輸出正確性、錯誤與忽略項目。
- 原文用
uptime與nproc觀察系統負載和核心數。平台若無這些指令，先找等價觀察工具並說明差異，不假裝已取得數據。
Claude Code 使用 /pstack:benchmark-checklist。Codex 插件選單插入 $pstack:benchmark-checklist，skills-only 使用 $benchmark-checklist。自然語言提示詞也可指定使用此技能，不是通用 slash 語法。
操作步驟
- 確定計時的工作。 確認匯出請求到達程式、六萬列確實產生、輸出內容正確，且結果被讀取或保存。檢查未等待的非同步工作、未走訪的產生器與只排入佇列就停止計時的情況。
- 先定位瓶頸，再公平設定。 用額外的一輪效能剖析 (profiling) 找出 CPU、I/O 或負載產生器限制，對照來源。剖析輪不列入正式數字。兩側都採實際生產設定，包括 release 建置、批次、快取狀態、版本與資料，不能拿一側預設設定宣布勝負。
- 算物理上限並計錯。 比對每秒資料量與磁碟或網路能力，檢查節省時間是否超過被修改部分原有耗時。若該部分只占全程 10%，完全移除後的最大速度提升約為 11%。每輪計算失敗、逾時、重試與輸出錯誤，不能把快速拒絕當成加速。
- 交錯重複量測。 A、B 交替，各至少 5 次，報告中位數 (median) 與範圍。機器持續有其他負載時，記錄干擾與交錯策略。差距小於輪次變異就不宣稱可量測差異，接近時再用秩和檢定 (rank-sum test) 或工具統計。
- 回到使用者等待的路徑。 若測的是單一序列化函式，還要量真實資料量與併發下的完整匯出。先給「較快」「較慢」「無可量測差異」或「無法判定」，再提供單位、輪數、範圍、瓶頸及證據。
可直接使用的提示詞
用 pstack:benchmark-checklist 查核這次 CSV 匯出器 A/B 比較。
資料固定為我提供的六萬列資料集，不連線正式服務。
先讀量測腳本，核對計時區間、錯誤計數及輸出內容。
列出工具與版本，分開做瓶頸剖析，不把剖析輪當正式數字。
兩側都使用相同且合理的生產設定，A/B 交替，各至少五次。
同時查核序列化微量測與使用者等待的完整匯出耗時。
回報中位數、範圍、瓶頸、錯誤與實際工作量證據。
無法確認瓶頸、調校公平性、正確性或工作是否完成時，結論寫無法判定。預期結果與驗收
- 數字可追溯至每輪輸入、版本、指令與原始輸出。報告有單位、每側輪數、中位數、範圍及瓶頸，而非只有一個百分比。
- 錯誤數與工作完成證據可直接核對。輸出檔存在還不夠，內容必須正確。
- 只要主張差異卻無法指出瓶頸、一側未合理調校，或無法查核錯誤及工作是否完成，就應標示
inconclusive，並寫明缺口。 - PR 正文保留一個主要數字，完整輪次與證據放在可連結的附件或筆記，不省略支持結論的資料。
限制與權限
只有使用者明確要粗估時，原文才允許一次執行，仍必須檢查錯誤與工作是否發生，並標示只有一輪。選工具或比較方案不屬於粗估例外。
此技能不保證取得乾淨環境，也不授權終止他人程序、安裝剖析器或對外施壓。負載、成本與資料範圍要先界定。微量測改善不能直接推論端到端提升，換平台、資料或快取條件也不能沿用原結論。