python-performance-optimization

python-performance-optimization 技能總覽

python-performance-optimization 技能的作用

python-performance-optimization 技能可協助 agent 判斷 Python 程式為什麼執行緩慢、為何記憶體占用過高，並根據 profiling 證據提出有針對性的修正方案，而不是靠猜測亂改。它是為了實務上的效能優化工作而設計：找出瓶頸、區分 CPU／記憶體／I/O 問題，並挑出真正符合實際負載路徑的改善方式。

哪些人適合安裝

這個技能最適合開發者、資料工程師、後端團隊，以及需要超越泛泛「把它變快」建議的 agent 工作流程。特別是在你手上已經有一個功能正確、可正常運作的 script、service、notebook 或 pipeline，只是需要改善延遲、吞吐量或記憶體表現時，它會很有幫助。

實際要解決的工作需求

大多數使用者不是只需要一段 Big O 教學，而是需要一套可重複使用的方法，來回答這些問題：

• 到底慢在哪裡
• 該怎麼正確量測
• 應該先做哪個優化最值得
• 如何避免去改那些根本不是瓶頸的程式碼

這正是 python-performance-optimization 技能比一般 prompt 更強的地方。它會把流程導向先做 profiling，再做 optimization。

這個技能和一般做法有何不同

這個 repository 不把效能當成單一問題處理，而是涵蓋多種 profiling 模式與多層次優化方式，包括：

• CPU profiling
• memory profiling
• line-level analysis
• call-graph 思維
• 像 caching 這類實作模式
• NumPy vectorization、async I/O、parallelization 等進階路線

它在實務上的差異點，是「涵蓋面廣」加上「先 profiling、後優化」的思維方式。

最適合與不適合的使用情境

適合的情境：

• 緩慢的 Python endpoint、job、CLI tool、ETL 或資料處理流程
• 記憶體持續成長或無法解釋的 RAM 暴增
• 需要在 caching、演算法調整、vectorization 或 concurrency 之間做選擇
• 在動 production code 之前，先制定優化方案

不適合的情境：

• 真正瓶頸其實在 infrastructure、network topology 或 database schema，而且手上沒有任何量測資料的 codebase
• 團隊期待安裝後就直接拿到全自動 benchmarking script
• 你只是想做程式風格整理，而不是效能診斷

如何使用 python-performance-optimization 技能

python-performance-optimization 安裝方式與使用時機

請從 wshobson/agents repository 安裝這個技能：

npx skills add https://github.com/wshobson/agents --skill python-performance-optimization

安裝完成後，當你的 prompt 明確涉及 Python 效能診斷、profiling、記憶體使用、降低延遲、提升吞吐量或瓶頸分析時，就適合使用它。

先讀這些 repository 檔案

若想最快掌握重點，建議先看：

1. plugins/python-development/skills/python-performance-optimization/SKILL.md
2. plugins/python-development/skills/python-performance-optimization/references/advanced-patterns.md

SKILL.md 提供主要工作流程與工具分類。若第一輪診斷已經指向 vectorization、caching、記憶體調校、async I/O 或資料庫負載偏重的問題，再接著讀 references/advanced-patterns.md 會最有價值。

要讓技能發揮效果，輸入需要包含哪些資訊

python-performance-optimization usage 的品質，很大程度取決於你提供的證據。請盡量給 agent：

• 緩慢的 function、file、endpoint 或 job
• 預期工作負載規模
• 實際症狀：latency、CPU 飽和、記憶體成長、timeout、高 query count
• profiling 輸出（若有）
• 限制條件：不能新增 dependencies、必須保留 API、只能採用 production-safe 的改法等
• 環境資訊：Python 版本、framework、OS、single process 或 multi-process

若缺少這些輸入，這個技能仍能建議 profiling 步驟，但建議會比較不夠具體。

把模糊需求改寫成強 prompt

較弱的 prompt：

• 「Optimize this Python code.」

較好的 prompt：

• 「Use the python-performance-optimization skill to analyze this Django view. P95 latency is 1.8s under ~200 requests/min. CPU is high, memory is stable. Here is the view code and a cProfile summary. Identify the top bottlenecks, explain whether the issue is Python execution, DB access, or serialization, and propose fixes ranked by expected impact and implementation risk.」

這樣效果更好，因為它同時提供了工作負載、症狀類型、證據與輸出格式。

先要求診斷，再要求改寫

一個好的工作流程通常是：

1. 描述效能症狀
2. 提供程式碼與量測資料
3. 請 agent 判定瓶頸類型
4. 再要求提出程式碼修改

這能避免太早進入改寫階段。當 python-performance-optimization skill 能從 metrics 推導到對應的介入方式時，價值會高得多。

哪些 profiling 輸入會明顯提升輸出品質

最有幫助的輸入包括：

• CPU-heavy 程式碼的 cProfile 摘要
• hot functions 的 line-profiler 結果
• RAM 問題的 memory-profiler 或 object growth 證據
• I/O、DB、HTTP、serialization 邊界的 timing breakdown
• 具代表性的 sample data，而不是 toy inputs

如果你目前還沒有量測資料，請先要求 agent 設計 profiling 計畫，而不是盲目直接做優化。

這個技能支援的典型工作流程

一份實用的 python-performance-optimization guide 通常會長這樣：

1. 先定義效能目標
2. 選擇正確的 profiling 類型
3. 對具代表性的工作負載進行 profiling
4. 找出最熱路徑或最大配置來源
5. 選出風險最低、影響最大的優化方案
6. 比較優化前後 benchmark
7. 留意 correctness 與 readability 是否回退

這個流程順序，就是此技能的核心價值。

什麼時候該看進階參考文件

當瓶頸很可能落在以下類型時，再打開 references/advanced-patterns.md：

• 可能可從 NumPy 受益的數值迴圈
• 可能適合用 functools.lru_cache 的重複 pure-function 計算
• 可能受益於 async pattern 的高 I/O 工作負載
• 成本高但可平行化、適合考慮 multiprocessing 的工作
• query 密集、需要用資料庫優化角度思考的應用

除非你已經知道問題類別，否則不要一開始就直接跳到這份文件。先從已量測到的瓶頸出發。

常見情境下的好 prompt 寫法

針對 CPU-bound 程式碼：

• 「Use the python-performance-optimization skill to review this function and cProfile output. Focus on algorithmic complexity, repeated work, and Python-level loop overhead.」

針對記憶體問題：

• 「Use the python-performance-optimization skill to inspect this batch job. RSS climbs from 400MB to 3GB. Suggest likely retention causes, profiling steps, and memory-safe refactors.」

針對 I/O-heavy 服務：

• 「Use the python-performance-optimization skill on this async API client. Requests are slow despite low CPU. Determine whether the bottleneck is blocking I/O, connection handling, serialization, or concurrency limits.」

可以期待哪些結果

這個技能最擅長的是：

• 選對 profiling 方法
• 解讀常見效能模式
• 依優先順序提出合理的優化方案
• 說明 caching、vectorization、parallelization 與簡化程式碼之間的取捨

如果你沒有提供程式碼、工作負載型態與量測資料，輸出效果就會明顯變弱。

python-performance-optimization 技能 FAQ

在 Performance Optimization 場景下，python-performance-optimization 比一般 prompt 更好嗎？

通常是的，尤其當你需要的是結構化診斷，而不是零散建議時。一般 prompt 常常會直接跳到「用 caching」或「用 NumPy」。python-performance-optimization 技能則更可能先區分 CPU、記憶體、I/O 與演算法層面的問題。

這個技能對初學者友善嗎？

是的，只要你能提供程式碼與症狀就可以開始。你不需要一開始就是 profiling 專家。不過對初學者來說，如果能提供具體證據，並要求 agent 先解釋「為什麼這個瓶頸重要」，再提出修正方案，結果通常會好很多。

使用前一定要先有 profiling 輸出嗎？

不一定，但有 profiling 輸出會讓 python-performance-optimization usage 品質提升很多。如果你目前還沒有量測資料，可以請 agent 明確告訴你該 profile 哪些項目，以及該用哪一類工具。

什麼情況下不該用這個技能？

如果問題明顯不在 Python application logic，就應該跳過它，例如：

• infrastructure 資源明顯不足
• 網路問題
• 資料庫伺服器設定錯誤，且沒有任何 app-level 證據
• 與 Python backend 執行無關的 frontend latency

在這些情況下，這個技能仍可協助你整理調查方向，但不應作為主要工具。

它只處理速度問題，還是也包含記憶體？

兩者都包含。這個 repository 明確涵蓋 memory profiling 與 memory optimization，以及 CPU profiling 與執行時間分析，所以比只會談「速度」的 prompt 更實用。

它能幫上資料工作負載嗎？

可以，尤其當改善方向可能涉及 vectorization、batching、caching，或減少 Python loop overhead 時更有幫助。對數值運算與資料處理程式碼來說，進階參考文件特別值得看。

如何提升 python-performance-optimization 技能的使用效果

提供 benchmark 證據，不要只貼原始碼

想讓 python-performance-optimization 輸出更好，最有效的方式就是提供：

• 前後對照 timings
• profiling 摘要
• sample input size
• throughput 或 latency 目標

只有原始碼時，agent 只能提出假設；有量測資料時，它才能排出優先順序。

明確說出你懷疑的瓶頸類型

即使你不完全確定，也請說出你目前的判斷：

• CPU-bound
• memory-bound
• database-bound
• network/I/O-bound
• startup-time 問題
• batch throughput 問題

這能幫助技能選對診斷路徑，避免落入泛泛而談的建議。

納入真實限制條件

優化建議會因限制條件而有很大差異。請直接說清楚：

• 不能修改 public API
• 不能加入 NumPy
• 必須維持對 junior team 也容易閱讀
• 必須能跑在 AWS Lambda
• 必須保留 deterministic ordering
• multi-tenant 的記憶體上限固定

這些資訊對決策品質的幫助，往往比單純要求「最佳效能」還大。

要求輸出排序過的建議

一個好的 prompt，會要求 agent 按下列面向排序建議：

1. 預期影響
2. 實作成本
3. correctness 風險
4. dependency 成本

這能避免常見失誤：第一個答案就先推薦複雜改動，卻忽略像是減少重複計算或修正低效 query 這種更容易先拿到成果的改善。

留意常見失敗模式

以下情況會削弱 python-performance-optimization skill 的效果：

• 優化了根本不在 hot path 上的程式碼
• 使用與 production workload 不符的 microbenchmark
• 過度重視花俏技巧，忽略可維護性
• 在其實受 I/O 或 GIL 行為限制的情況下硬套 multiprocessing
• 建議使用 caching，卻沒有討論 invalidation 或記憶體成本

請要求 agent 針對每個優化建議，都說明它與已量測瓶頸之間的對應關係。

收到第一輪答案後持續迭代

一個有力的第二輪 prompt 會像這樣：

• 「Here is the updated code and new benchmark. The runtime dropped from 2.4s to 1.5s, but memory increased by 35%. Re-run the python-performance-optimization analysis and suggest the next best change with minimal memory growth.」

這能把技能用成一個持續優化迴圈，而不是一次性的改寫工具。

有策略地指定 repository 閱讀路徑

如果第一輪回答仍然太泛，請明確要求 agent 以這些檔案為推理依據：

• SKILL.md：profiling 類別與工作流程
• references/advanced-patterns.md：vectorization、caching、memory management、parallelization、async I/O、benchmarking 等實作選項

這通常能明顯提高輸出的具體程度。

如果卡在不知從何開始，就先要求量測計畫

如果你的阻礙是「不知道該怎麼開始」，可以先要求一份最小可行計