performance-engineer

performance-engineer スキルの概要

performance-engineer スキルでできること

performance-engineer スキルは、遅いシステムの診断、ボトルネックの特定、「このエンドポイントが遅い」といった曖昧な不満を測定可能な改善につなげるための、性能トラブルシューティングと最適化に特化したワークフローです。一般的なコードレビュー向けではなく、パフォーマンス最適化の作業に照準を合わせており、勘で修正するのではなく、ベースライン計測 → プロファイリング → 検証という流れを強制できる点に価値があります。

performance-engineer を使うべき人

このスキルは、すでに調査対象のシステムを持っていて、時間・メモリ・スループットのどこで損失が起きているのかを絞り込みたい開発者、SRE、バックエンドエンジニア、AI エージェント利用者に向いています。特に、再現可能な性能低下、達成したいレイテンシ目標、あるいは怪しいホットスポットがあるものの、まっさらなプロンプトから始めたくない場面で有効です。

本当に解決したい仕事

多くのユーザーが欲しいのは、単に「コードを速くすること」ではありません。実際には次のような実務上の問いに答える必要があります。

• 本当に悪化しているメトリクスは何か？
• ボトルネックは database、API、frontend、network、それとも runtime のどこか？
• コードを変える前に何を測定すべきか？
• その最適化が効いたこと、そして挙動を壊していないことをどう証明するか？

performance-engineer スキルは、こうした調査を構造化して進める用途で最も力を発揮します。

汎用プロンプトと何が違うのか

汎用プロンプトは、推測ベースの修正案にすぐ飛びがちです。performance-engineer スキルがパフォーマンス最適化で優れているのは、次の観点を明示的に中心へ置いているからです。

• ベースラインのメトリクスと目標値
• 最適化前のプロファイリング
• レイヤーごとのボトルネック特定
• 変更後の検証
• scripts/ にある軽量なレポート／プロファイリング用テンプレート

そのため、単なるアイデア出しではなく、実際のエンジニアリング作業に使いやすい構成になっています。

インストール前に確認しておきたいこと

このスキルが特に合うのは、次を用意できる場合です。

• 調査対象のコードベースまたはエンドポイント
• 再現可能な遅い処理経路
• 少なくとも 1 つの測定可能な性能目標
• profiling、logs、benchmark コマンドを実行する権限

一方で、主な課題が correctness、アーキテクチャ選定、あるいは実際の性能症状がない状態でのコスト見積もりであれば、適合度は下がります。

performance-engineer スキルの使い方

performance-engineer のインストール方法

リポジトリコレクションから次のコマンドでインストールできます。

npx skills add https://github.com/zhaono1/agent-playbook --skill performance-engineer

インストール前に中身を評価したい場合は、次を確認してください。

• skills/performance-engineer/SKILL.md
• skills/performance-engineer/README.md
• skills/performance-engineer/references/checklist.md
• skills/performance-engineer/references/monitoring.md
• skills/performance-engineer/references/optimization.md
• skills/performance-engineer/scripts/profile.py
• skills/performance-engineer/scripts/perf_report.py

performance-engineer スキルに必要な入力

performance-engineer スキルは、コードだけでなく運用文脈も渡したときに最もよく機能します。有効な入力例は次のとおりです。

• 遅い endpoint、query、page、job、または command
• 現在値と目標値の latency、throughput、memory、CPU
• language、framework、runtime、infra などの環境情報
• 問題の再現方法
• 既存の profiler 出力、trace、log
• 想定しているレイヤー: DB、API、frontend、network、caching、compute

これらがなくても、スキルは進め方自体の提案はできます。ただし推測に頼る割合が増えるため、出力品質は落ちます。

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

弱い例:

Optimize this code.

より良い例:

Use the performance-engineer skill on this Python API endpoint. Current p95 latency is 1.4s, target is under 500ms. Traffic spikes at 50 concurrent requests. We use PostgreSQL and Redis. Please identify what to measure first, likely bottlenecks, profiling commands to run, and the order of fixes to test.

これが良い理由:

• 測るべきメトリクスが明確
• 目標値がある
• ワークロードの条件が入っている
• ボトルネック候補のレイヤーを絞れている
• 思いつきの tweaks ではなく、調査の順番を求めている

実務でのおすすめワークフロー

実運用での良い performance-engineer usage パターンは次の流れです。

1. 影響を受けるユーザーパスまたはシステム操作を定義する。
2. ベースラインのメトリクスを記録する。
3. 遅い経路を profile または調査する。
4. 所見をもとに、あり得るボトルネックレイヤーへマッピングする。
5. まずは影響が大きく、変更が最小の修正案を提案する。
6. 変更ごとに再計測する。
7. 所見とリグレッション確認内容を記録する。

これはスキル自体のフェーズ構造にも沿っており、最適化を常に証拠ベースで進められます。

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

最短でキャッチアップしたいなら、次の順番で読むのがおすすめです。

1. SKILL.md — 起動トリガーと分析フェーズの把握
2. references/checklist.md — 最低限守るべき調査プロセス
3. references/optimization.md — よくある最適化レバーの確認
4. references/monitoring.md — リリース後に追うべき指標
5. README.md — サンプルのターゲットと補助スクリプト

なお、scripts は profiler そのものではありません。調査結果の出力形式を揃えるためのテンプレートです。

利用を支える組み込みスクリプト

この performance-engineer guide に実務的な価値を加えているのが、次の 2 つの補助スクリプトです。

• python scripts/profile.py は、environment、workload、hotspot などの項目を含む profile テンプレートを生成します。
• python scripts/perf_report.py は、summary、ownership、baseline metrics、findings、recommendations、validation をまとめる markdown レポートを生成します。

例:

python scripts/profile.py --name "checkout latency" --tool "cProfile" --command "python app.py" --duration "60s"
python scripts/perf_report.py --name "checkout API" --owner "payments-team"

一回限りのチャット出力ではなく、再現性のある調査メモを残したいときに便利です。

performance-engineer スキルが検出しやすい問題

ソース資料では、ユーザーを次のような典型的ボトルネックへ導く設計になっています。

• N+1 queries、missing indexes、大きすぎる result sets などの database 問題
• API の over-fetching や非効率な serialization
• profiler 出力から見つかる runtime hotspot
• payload や network の非効率
• hot path 上の caching の抜け

つまりこのスキルは、「全部速くしたい」という漠然とした願望よりも、切り分けるべき実際のボトルネックがある状況でこそ価値が高いです。

より良い結果を得るための実践的なプロンプト形式

performance-engineer for Performance Optimization を呼び出すときは、次の形式が有効です。

Use the performance-engineer skill.

System:
- Service/page/job:
- Language/framework:
- Infra/dependencies:

Problem:
- Symptom:
- Current metric:
- Target metric:
- Reproduction steps:

Evidence:
- Logs/traces/profile snippets:
- Suspected bottleneck layer:

Task:
- Define measurement plan
- Identify likely root causes
- Recommend ordered fixes
- Specify how to validate improvement

この形式なら、単に “why is this slow?” と聞くより、実行可能な提案を得やすくなります。

導入時によくある障壁

performance-engineer install に頼る前に、主な制約も把握しておきましょう。

• 実際の profiler や APM ツールの代わりにはならない
• 効果を出すには測定可能な症状が必要
• workload を再現できない状況では有用性が落ちる
• benchmark の経路がないと改善効果を検証できない

要するに、このスキルが改善するのは調査の進め方であって、信頼できる測定値を魔法のように自動生成してくれるわけではありません。

通常のプロンプトで十分なケース

必要なのが、軽いコードスタイル整理、小さな script の micro-optimization、あるいは調査抜きの言語固有チューニング助言だけなら、標準的なプロンプトでも十分なことがあります。performance-engineer skill を使うべきなのは、重要度が高く、症状の把握から検証済みの修正までを構造的に進めたい場面です。

performance-engineer スキル FAQ

performance-engineer は初心者にも向いていますか？

はい、ただし初心者でも「具体的に遅い状況」をすでに持っていることが前提です。このスキルは、ベースライン → profile → ボトルネック特定 → 検証という規律ある順序を提供してくれるので、早すぎる最適化を避けやすくなります。逆に、observability や benchmarking の基礎から丸ごと教えてもらうことを期待すると、初心者向けとは言いにくい面があります。

AI に「コードを最適化して」と頼むのと比べて、performance-engineer の何が良いのですか？

最大の違いは、プロセスを制御できることです。普通のプロンプトは、caching、indexing、async 化、refactor などの提案をすぐ出しがちです。performance-engineer skill は、問題が database、API layer、memory behavior、payload size、runtime hotspot のどこにあるのかを、まず見極めたいときに特に役立ちます。

このスキルには実際のツールも含まれていますか？

一部は含まれています。リポジトリには scripts/profile.py と scripts/perf_report.py というテンプレート生成用スクリプトがあり、加えて checklist、monitoring、optimization levers に関する reference docs も用意されています。ただし、runtime profiler、logs、benchmarks、環境固有のコマンドは自分で用意する必要があります。

performance-engineer はバックエンド専用ですか？

いいえ。README には API だけでなく page-load 系メトリクスも含む performance targets があり、references でも payload と network efficiency に触れています。ただし、例示は frontend の深い rendering 分析より、アプリケーションやサービスの調査寄りです。

performance-engineer を使わないほうがよいのはどんなときですか？

次のようなケースでは見送るのが妥当です。

• まだ測定可能な performance 問題が存在しない
• 広い粒度の architecture ブレストだけをしたい
• 課題が speed ではなく reliability や correctness にある
• workload を再現できず、メトリクスも取得できない

こうした状況では、このスキルの構造化された手順が活きにくくなります。

修正後の monitoring にも performance-engineer は使えますか？

はい。references/monitoring.md では、percentiles、throughput、error rates、そして regression 向け alert を追跡するよう促しています。そのため、一度きりのチューニング支援ではなく、リリース後の妥当性確認まで含めて使いたい場合にも有効です。

performance-engineer スキルを改善する方法

長いプロンプトより、良いベースラインを渡す

performance-engineer usage を最も手早く改善する方法は、次をきちんと渡すことです。

• 現在の p50、p95、p99 latency
• throughput と error rate
• memory または CPU の症状
• 正確な benchmark または request path
• before/after の比較計画

長い背景説明を足すより、こちらのほうがはるかに価値があります。

環境情報とワークロードの形を含める

パフォーマンスの助言は、workload によって変わります。次の情報をスキルに伝えてください。

• request concurrency
• dataset size
• cache warm / cold の状態
• CPU と memory の制約
• local、staging、production のどの環境か

付属の scripts/profile.py テンプレートは、何を記録すべきかを思い出すのに役立ちます。具体的には environment、workload、command、duration、hotspots です。

優先順位付きの修正案と検証手順を求める

効果的な追加入力の例は次のとおりです。

Use the performance-engineer skill to rank the top three likely bottlenecks by expected impact and confidence. For each, give the measurement to confirm it, the smallest fix to test, and the benchmark to verify improvement.

こう依頼すると、「とにかく全部試す」型の曖昧な出力を減らし、反復のコストを下げられます。

典型的な失敗パターンを避ける

performance-engineer で弱い結果になりやすい典型例は次のとおりです。

• ベースラインメトリクスがない
• 再現可能な workload がない
• profiler や trace の証拠がない
• ボトルネックを切り分ける前に修正案を求める
• 複数システムをひとつの曖昧な依頼にまとめる

最初の結果が汎用的すぎると感じたら、たいていはこのどれかが欠けています。

checklist を品質ゲートとして使う

references/checklist.md は短いですが重要です。最低基準として扱ってください。

• baseline metrics を記録した
• bottlenecks を特定した
• fixes を benchmark で検証した
• regression tests を追加した

この checklist を運用に組み込んだとき、このスキルは単なる助言ツールではなく、実務で回せる仕組みになります。

所見を文書化して次の反復を良くする

最初の調査が終わったら、scripts/perf_report.py でレポートを生成し、その内容を次回の実行に渡してください。そうすることで performance-engineer skill は、毎回ゼロから始めるのではなく、実際の findings、ownership、validation notes を踏まえて提案を洗練できます。

証拠の抜粋を入れてプロンプトを改善する

“DB seems slow” とだけ書くのではなく、次のような短い evidence block を貼るのがおすすめです。

• query duration sample
• profiler の上位 functions
• trace span summary
• percentile ごとの endpoint timings

断片的な証拠でも、観測された hotspot と提案を結び付けやすくなるため、出力品質は大きく上がります。

診断と実装の境界を理解する

performance-engineer for Performance Optimization ワークフローが最も強いのは、diagnosis、prioritization、validation planning です。選んだ修正を実装する段階では、自分の stack に合わせた実装支援を行う第 2 フェーズと組み合わせると、より効果的になります。まずは何が本当に重要かを決めるために使い、その後で coding 支援を使って安全に変更を適用するのが適切です。