principle-explain-the-number | 先解釋數字再採取行動

本頁以 pstack-claude 0.9.126 為基準。原文標示 user-invocable: false，通常由 poteto-mode 按需讀取。範例以自然語言要求套用原則，不是獨立命令。

定位與適用情境

量測之前，以及信任、報告或根據量測採取行動之前，都應先解釋數字。速度、吞吐量（Throughput）、延遲（Latency）與模型評估（Eval）結果，都可能測到預期之外的東西。

例如團隊修改匯出序列化邏輯，想知道是否值得合併。較短的完成時間可能來自真正加速，也可能來自漏處理資料、錯誤提早退出、快取，或負載產生器本身已經飽和。光看兩次執行的耗時無法區分。

準備

保留基準版與候選版、相同輸入、版本資訊及執行設定。
確認有既存量測工具，能保存每次執行結果與輸出完整性。不要假設分析器已安裝。
準備執行期間的效能剖析（Profile）或系統計數器，能把限制因素對回來源碼。
先寫明什麼結果會改變合併決策，以及如何辨認雜訊底限（Noise Floor）。門檻應來自實際需求與環境，不能臨時挑一個有利數字。

操作步驟

先寫決策，再啟動量測。 定義要比較端到端匯出，還是其中一段轉換。記錄足以改變決策的差距、預計執行次數與波動判讀方式。若執行間波動大於欲判定的效果，就停止下結論。
確認兩側真的完成相同工作。 比較逐筆輸出、錯誤與實際走到的程式路徑。記錄快取條件與調校設定，排除一側少處理資料、提早失敗或仍使用未調校預設值等情況。
問為何結果不能再好一倍。 從執行中的剖析或系統計數器找出限制，例如核心、鎖、磁碟、網路或負載產生器，再對回來源碼。只讀程式後猜測「應該卡在磁碟」不算證據。
反查其他解釋與端到端關聯。 逐項排除跳過工作、快取、未執行程式、設定不對等及雜訊。若只有小區段變快，確認它在整體工作中是否重要。聲稱節省的時間若大於原區段耗時，先查量測而非慶祝。
把證據與數字一起交付。 保存各次執行值、執行次數、分布或波動、限制因素及對應來源位置。說明哪些替代解釋已排除，哪些仍未查明，再依最初決策條件判讀。

可直接使用的提示詞

套用 principle-explain-the-number。
我們要比較基準版與候選版的匯出序列化改動，尚未量測。
先寫出會改變合併決策的結果、雜訊底限判讀方式與執行計畫。
確認兩版處理相同輸入且輸出完整，再安排量測。
從執行中的 profile 或系統計數器找出限制因素，對回來源碼，回答為何不能再好一倍。
逐項排除錯誤、漏做工作、快取、路徑未執行、設定不對等與雜訊。
報告必須附各次結果、次數、波動與證據位置。資料不足就寫無法判定，不補造數字。
效能量測另依 benchmark-checklist 的完整程序進行。
沒有核准工具或環境時先回報缺口，不安裝依賴或對正式服務壓測。

預期結果與驗收

預期交付一份能重建判讀過程的紀錄，而不是只有「變快了」的摘要。讀者應能找到兩版實際完成的工作、所有執行值、波動、限制因素與決策依據。

驗收時，檢查限制因素是否來自執行期間的證據，而非程式碼閱讀猜測。若缺執行次數、分布或具體限制因素，就還不能把數字當成可靠結論。本頁不提供任何實測速度或示範提升比例。

常見誤用是先跑出漂亮數字才選門檻，或把單次微型量測直接推成整個產品的提升。模型評估也不能只報成功率，還要確認每次試驗都做了任務、差距跨試驗與模型是否成立，以及情境是否有意義。

限制與權限

效能數字仍須配合 benchmark-checklist 的完整程序，本頁不取代該檢查。缺乏適用工具時，應明示未量測或未能判定，不能把預估稱為實測。

實驗只能在核准環境與負載範圍內進行。安裝分析器、連線外部服務或執行正式環境壓測，不因套用原則就自動取得授權。量測輸入與紀錄也應避免洩漏敏感資料。

延伸閱讀與來源

匯出序列化是本頁教學情境。來源提供的是數字的查核要求，不是已完成的量測結果。