python-performance-optimization

python-performance-optimization スキルの概要

python-performance-optimization スキルでできること

python-performance-optimization スキルは、Python コードが遅い理由やメモリ使用量が大きい原因を診断し、勘ではなくプロファイリング結果に基づいて、狙いを絞った改善策を提案するためのスキルです。実務のパフォーマンス改善を前提にしており、ボトルネックの特定、CPU・メモリ・I/O の切り分け、そして実際の負荷経路に合った改善策の選定に向いています。

どんな人に向いているか

このスキルは、単なる「もっと速くして」という一般論では足りない開発者、データエンジニア、バックエンドチーム、エージェント運用に特に向いています。すでに機能的には動いているスクリプト、サービス、ノートブック、パイプラインがあり、レイテンシ、スループット、メモリ挙動を改善したい場面で特に有効です。

実際に解決したい仕事

多くのユーザーが必要としているのは、Big O の説明だけではありません。知りたいのは、再現可能な形で次を判断する方法です。

• どこが遅いのか
• どう測れば正しく把握できるのか
• 最初に着手すべき最適化は何か
• ボトルネックではないコードを無駄に変更しないにはどうすべきか

その点で、python-performance-optimization スキルは通常のプロンプトより強みがあります。まずプロファイリングし、その後に最適化する流れへと自然に導いてくれます。

このスキルが他と違う点

このリポジトリは、パフォーマンスをひとつの問題として雑に扱わず、複数のプロファイリング手法と最適化レイヤーを横断的にカバーしています。対象は次のとおりです。

• CPU profiling
• memory profiling
• 行単位の分析
• call-graph の考え方
• caching のような実装パターン
• NumPy vectorization、async I/O、parallelization などの高度なアプローチ

実用面での差別化ポイントは、対象範囲の広さと「まず測る」という姿勢が両立していることです。

向いているケース／向いていないケース

向いているケース:

• 遅い Python の endpoint、job、CLI tool、ETL、データ処理
• メモリ増加や原因不明の RAM スパイク
• caching、アルゴリズム変更、vectorization、concurrency のどれを選ぶべきか迷っている場合
• 本番コードに手を入れる前に最適化計画を立てたい場合

向いていないケース:

• 実際のボトルネックがインフラ、ネットワーク構成、データベース schema にあり、しかも測定値がないコードベース
• 最初から完全自動の benchmarking script を求めているチーム
• パフォーマンス診断ではなく、コードスタイル整理だけをしたい場面

python-performance-optimization スキルの使い方

python-performance-optimization の導入方法

wshobson/agents リポジトリからスキルをインストールします。

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

インストール後は、プロンプトの内容が Python のパフォーマンス診断、profiling、メモリ使用量、レイテンシ削減、スループット改善、ボトルネック分析に明確に関係しているときに使うのが効果的です。

最初に読むべきリポジトリ内ファイル

最短で全体像をつかむなら、まず次を確認してください。

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

SKILL.md には、基本ワークフローとツールカテゴリがまとまっています。references/advanced-patterns.md は、初回診断の結果として vectorization、caching、メモリ調整、async I/O、database-heavy な処理が候補に上がったときの次の一手として特に有用です。

このスキルがうまく機能するために必要な入力

python-performance-optimization usage の質は、渡す根拠情報に大きく左右されます。エージェントには次を渡してください。

• 遅い関数、ファイル、endpoint、job
• 想定している workload の規模
• 実際の症状: latency、CPU saturation、memory growth、timeout、高い query 数
• 可能であれば profiling の出力
• 制約条件: 依存関係を増やせない、API を維持する必要がある、本番安全な変更のみ、など
• 環境情報: Python version、framework、OS、single process か multi-process か

これらがなくても、スキルは profiling 手順を提案できます。ただし、提案の具体性はかなり落ちます。

曖昧な依頼を強いプロンプトに変える

弱いプロンプト:

• “Optimize this Python code.”

より良いプロンプト:

• “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.”

この依頼がうまく機能するのは、workload、症状の種類、根拠データ、求める出力形式がそろっているためです。

書き換え依頼の前に、まず診断を求める

良いワークフローは次の順番です。

1. パフォーマンス上の症状を説明する
2. コードと測定データを渡す
3. エージェントにボトルネックの分類を求める
4. その後ではじめてコード変更を依頼する

この流れにすると、早すぎるリライトを避けられます。python-performance-optimization skill は、メトリクスから介入策へつなげて考えられるときに最も力を発揮します。

出力の質を大きく上げる profiling 入力

特に有効な入力は次のとおりです。

• CPU-heavy なコード向けの cProfile サマリ
• hot function 向けの line-profiler 結果
• RAM 問題向けの memory-profiler や object growth の証拠
• I/O、DB、HTTP、serialization の境界ごとの timing breakdown
• おもちゃの入力ではなく、実運用に近い sample data

まだ測定がないなら、闇雲に最適化を依頼するより、先に profiling plan を設計させるほうが有効です。

python-performance-optimization スキルが支える典型ワークフロー

実務的な python-performance-optimization guide は、通常次の流れになります。

1. パフォーマンス目標を明確にする
2. 適切な profiling 種別を選ぶ
3. 代表的な workload で profile を取る
4. 最も熱い経路や大きな allocation を見つける
5. 低リスクかつ高インパクトな最適化を選ぶ
6. 変更前後を benchmark する
7. 正しさや可読性の回帰がないか確認する

この手順そのものが、このスキルの主要な価値です。

advanced reference を開くべきタイミング

ボトルネックが次のどれかにありそうなら、references/advanced-patterns.md を開いてください。

• NumPy の恩恵を受けそうな数値ループ
• functools.lru_cache が効きそうな pure-function の繰り返し処理
• async pattern が効きそうな高 I/O ワークロード
• multiprocessing が役立つかもしれない高コストで並列化可能な処理
• database optimization の観点が必要な query-heavy アプリケーション

ただし、カテゴリが見えていない段階で最初から飛びつくのはおすすめしません。まずは測定されたボトルネックから入るべきです。

典型ケース別の良いプロンプト例

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、コード簡素化のトレードオフ説明

一方で、コードも workload の形も測定値もない場合は、結果の精度は落ちます。

python-performance-optimization スキル FAQ

Performance Optimization 用の python-performance-optimization は普通のプロンプトより良い？

多くの場合は yes です。特に、その場しのぎの提案ではなく、構造化された診断が欲しいときに向いています。通常のプロンプトは、すぐに「caching を使う」「NumPy を使う」といった提案に飛びがちです。python-performance-optimization スキルは、その前に CPU、メモリ、I/O、アルゴリズム上の問題を切り分けやすいのが強みです。

初心者でも使いやすい？

はい。コードと症状を共有できるなら、初心者でも使いやすいスキルです。最初から profiling の専門知識は不要です。ただし、具体的な根拠を渡し、修正案の前に「そのボトルネックがなぜ重要か」を説明させると、初心者でも結果の質がかなり上がります。

使う前に profiling 出力は必須？

必須ではありません。ただし、python-performance-optimization usage の質は profiling 出力があると大きく向上します。まだ測定していないなら、何をどのツールカテゴリで profile すべきかをエージェントに具体的に聞くのがおすすめです。

どんなときはこのスキルを使わないほうがいい？

問題が明らかに Python アプリケーションロジックの外にある場合は、優先度を下げるべきです。たとえば:

• リソース不足のインフラ
• ネットワーク障害
• app-level の証拠がない database server の misconfiguration
• Python backend の実行とは無関係な frontend latency

こうしたケースでも調査の切り口整理には役立ちますが、主要な解決ツールとしては適していません。

速度だけでなくメモリも見られる？

はい。リポジトリでは CPU profiling や実行時間分析だけでなく、memory profiling と memory optimization も明示的に扱っています。そのため、「速さだけ」に偏ったプロンプトより実用的です。

データ処理ワークロードにも使える？

はい。特に、改善手段として vectorization、batching、caching、Python ループのオーバーヘッド削減が候補になる場面で有効です。数値計算やデータ処理コードでは、advanced reference が特に役立ちます。

python-performance-optimization スキルをさらに活かす方法

ソースコードだけでなく benchmark の根拠も渡す

python-performance-optimization の結果を最も大きく改善する方法は、ソースコードだけでなく次も渡すことです。

• 変更前後の timings
• profiling summaries
• sample input sizes
• throughput または latency の目標値

ソースコードだけだと、エージェントは仮説止まりです。測定値があれば、優先順位まで判断しやすくなります。

疑っているボトルネック種別を明示する

確信がなくても、「何が怪しいと思っているか」は書いてください。

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

これだけでも、スキルは適切な診断経路を選びやすくなり、一般論に流れにくくなります。

現実的な制約を含める

最適化の提案は、制約条件で大きく変わります。次のような条件は明示してください。

• public API は変えられない
• NumPy は追加できない
• junior team でも読める形を維持したい
• AWS Lambda 上で動かす必要がある
• deterministic ordering を保つ必要がある
• multi-tenant の memory ceiling は固定

「最高性能で」とだけ頼むより、こうした前提のほうが意思決定の質を上げます。

提案を順位付きで出すよう依頼する

強いプロンプトでは、提案を次の軸で順位付けするよう求めます。

1. 期待インパクト
2. 実装工数
3. 正しさへのリスク
4. 依存コスト

こうすると、単純に繰り返し処理を減らす、非効率な query を直すといった手堅い改善より先に、複雑すぎる変更を勧めてしまう失敗を防ぎやすくなります。

よくある失敗パターンに注意する

python-performance-optimization skill の効果は、次のような状況で弱まりがちです。

• hot path ではないコードを最適化してしまう
• 本番 workload と合っていない microbenchmark を使う
• 保守しやすいコードより clever code を過大評価する
• I/O や GIL の性質上不向きなのに multiprocessing を適用する
• invalidation やメモリコストに触れずに caching を勧める

各最適化案について、「測定されたボトルネックに対してなぜ有効なのか」を説明させると精度が上がります。

1回目の回答の後に反復する

2ラウンド目の良いプロンプト例は次のような形です。

• “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.”

こうすることで、このスキルは一発の書き換え提案ではなく、継続的な最適化ループとして使えるようになります。

リポジトリ読解の導線を戦略的に使う

最初の回答がまだ抽象的なら、次のファイルに根拠を置いて考えるよう明示してください。

• profiling のカテゴリとワークフローは SKILL.md
• vectorization、caching、memory management、parallelization、async I/O、benchmarking の実装選択肢は references/advanced-patterns.md

こう伝えるだけで、出力の具体性が上がることが多いです。

導入前で手が止まっているなら measurement plan を求める

「何から始めればよいかわからない」が障害なら、最小限の計測計画を作らせるのが有効です。たとえば次を聞いてください。

• 最初に何を測るべきか
• どの profiler category が合うか
• timer をどこに置くべきか
• どんな workload を再現すべきか
• 成功指標を何にするか

これは、プロセス初期のチームにとって python-performance-optimization guide の最も価値が高い使い方のひとつです。