performance-optimization

パフォーマンス最適化スキル

API 呼び出し、データベースクエリ、データ処理パターンを分析し、パフォーマンスを最適化します。

使用する場面

• コードベースのパフォーマンスボトルネックを分析する場合
• バッチ処理を実装する場合
• N+1 クエリパターンを最適化する場合
• 独立した処理を並列化する場合
• データベースインデックスを追加する場合

プロジェクトのスコープに関するルール

• まず、コード検索の対象を現在のリポジトリに限定します。
• まず、実行時のパフォーマンス調査の対象を、現在のリポジトリでアクティブなオブザーバビリティプロジェクトに限定します。
• 明示的に依頼された場合にのみ、他のプロジェクトやリポジトリに対象を広げます。

根拠に基づくリファクタリングのための実データソース

大規模なリファクタリングや広範なアーキテクチャ変更を提案する前に、オブザーバビリティデータから実際のホットスポットを確認します。

ローカルプロファイリング、テスト、または明確な静的 N+1／逐次処理パターンによってすでに確認されている、小規模なローカル最適化では、Sentry プロジェクトの検出を省略します。

Sentry MCP（主な実行時データソース）

プロジェクトの検出後、Sentry MCP を使用して、遅いトランザクション、遅いスパン、高パーセンタイルのレイテンシを調査します。

• 実行時の動作が不明な場合、サービス間のレイテンシが疑われる場合、または大規模なリファクタリングを検討している場合は、検出を実行します。
• コード変更を提案する前に、直近の期間のデータと集計ビューを優先して根拠を確認します。

agent-tools スキル（任意の運用上の実態確認）

ボトルネックを実データで検証するためにインフラ／ログ／データベースのコンテキストが必要な場合は、agent-tools を読み込みます。

• アプリケーションログのタイミングパターンには bun run logs-tool ...
• SQL の確認や行数／カーディナリティの確認には bun run db-tool ...
• Pod の CPU／メモリのスロットリングや実行時の負荷には bun run k8s-tool ...

これらのツールを使って、ボトルネックがアプリケーションロジック、データベースの動作、インフラの制限のいずれに起因するかを確認します。

現在のエージェント／ランタイムで agent-tools を利用できない場合は、次の代替シグナルを使用します。

• リポジトリ内のログとデバッグ用計測を使用します
• テストフィクスチャと再現可能なベンチマークスクリプトを使用します
• データベースのクエリプランと実行時間の出力を使用します（利用できる場合は EXPLAIN (ANALYZE, BUFFERS)）
• インフラレベルのデータを収集できない場合は、不確実性を明記します

分析ワークフロー

1. ボトルネックを特定する

コードベースで、次のような影響の大きいパターンを検索します。

• API／DB 呼び出しを含む N+1 ループ
• 並列実行できる独立した呼び出しの逐次実行
• ループ内での個別の挿入／更新／削除
• アップサートに置き換えられる、繰り返し発生する読み取り後の書き込み処理

2. 最適化を適用する

• inArray と検索用マップを使って読み取りをバッチ化します
• 書き込みをバッチ化します（insert(values[])、update ... where inArray、delete ... where inArray）
• カーディナリティとレイテンシが改善する場合は、JOIN／サブクエリで複数クエリの処理を集約します
• Effect.all／Effect.forEach(..., { concurrency }) と Promise.all を使って、独立した処理を並列化します
• アップサートパターンを使って、書き込み前の読み取りによるラウンドトリップを回避します

SKILL.md のサイズを抑え、エージェント間の移植性を保つため、完全なコード例はリファレンスに記載します。

データベースインデックスのガイドライン

インデックスを追加するタイミング

1. 単一列クエリ：1 つの列によるフィルタリングが頻繁に行われる場合
2. 複合クエリ：複数の列を組み合わせたフィルタリングが行われる場合
3. ORDER BY 列：ある列による並べ替えが頻繁に行われる場合
4. 外部キー：PostgreSQL は外部キー列にインデックスを自動作成しません。外部キー列が JOIN、フィルタリング、または削除／更新のカスケード処理で使われる場合は、明示的にインデックスを作成します

検証と計測のワークフロー

1. ベースラインを確立する

• 対象の処理経路について、p50／p95 レイテンシ、クエリ数、スループットを記録します。
• 該当する場合は、メモリとエラー率のシグナルも記録します。
• ベースラインの計測期間とワークロードの前提を記録します。

2. 影響の大きい変更を最小限で実装する

• 一度に変更するホットスポットの種類は 1 つに限定します（N+1、独立した呼び出しの逐次実行、バッチ化されていない書き込み、インデックスの不足）。
• 機能上の動作と既存のエラー処理の仕様を維持します。

3. 正しさを検証する

• チェック（bun run check）と関連テストを実行します。
• エラー処理とログが引き続き適切であることを確認します。
• 外部 API の同時実行数の上限を確認します。

4. 同等の負荷で再測定する

• p50／p95 レイテンシ、クエリ数、スループット、リソース使用量をベースラインと比較します。
• 改善が統計的に有意であり、単なるノイズではないことを確認します。

5. リグレッションを防ぐ

• ベンチマークまたはトレースの証拠を変更とともに保管します。
• 動作がリグレッションする可能性がある場合は、重要な最適化パスに対する対象を絞ったテストを追加します。
• インフラレベルでの検証が必要な、残っているボトルネックを記録します。

参考資料

• Effect の並列化パターンと同時実行数に関するガイダンスについては、references/effect-parallel-patterns.md を参照してください。
• Drizzle のバッチ操作、結合、事前取得マップ、アップサートのパターンについては、references/drizzle-batch-patterns.md を参照してください。