パフォーマンス調査のための Claude Code：測定に基づくワークフロー

なぜ測定なしだとパフォーマンス作業はうまくいかないのか

パフォーマンスの不具合は推測を招きます。誰かがページが遅いと感じたり API がタイムアウトすると、真っ先に「コードを整理する」「キャッシュを追加する」「ループを書き直す」といった動きが出ます。しかし「遅く感じる」は指標ではなく、「きれい」は必ずしも速いことを意味しません。

測定がないと、チームは的外れな部分を何時間も直してしまいます。ホットパスはデータベースやネットワーク、あるいは予期せぬ単一の割り当てにあるかもしれませんが、チームはほとんど実行されないコードを磨いていることがあります。さらに悪いのは、賢そうに見える変更がパフォーマンスを悪化させる場合です：タイトなループでの追加ログ、メモリ圧力を高めるキャッシュ、ロック競合を生む並列処理など。

推測は挙動を壊すリスクも抱えます。速くするための変更が結果、エラーハンドリング、順序、リトライ動作を変えるかもしれません。正確性と速度を一緒に再確認しないと、ベンチマークでは「勝てても」バグを密かに出荷してしまいます。

パフォーマンスを議論ではなく実験として扱ってください。ループはシンプルで再現可能です：

• 問題を表す一つの指標を選ぶ（レイテンシ、スループット、CPU、メモリ、DB時間）。
• 同じ条件でベースラインを取る。
• 1つだけ小さな変更を行う。
• 再測定して比較する。

多くの改善は控えめです：p95レイテンシを8%削る、ピークメモリを50MB減らす、データベースクエリを1つ減らすなど。それらは測定され、検証され、再現可能であれば意味があります。

ワークフロー：測定→仮説→変更→再測定

これは一回きりの「速くして」依頼ではなく、ループとして回すと効果的です。ループは行動を証拠と監視できる数値に結びつけるので自分を正直に保ちます。

明確な手順：

• 測定：1つの指標を選びベースラインを記録する。
• 仮説：何が遅いのか、なぜそう考えるかを説明する。
• 変更：仮説を検証するための最小限の変更を行う。
• 再測定：同じ計測を実行し比較する。

各ステップは別の自己欺瞞からあなたを守ります。先に測定することで「本当の問題でないもの」を直すのを防げます。文書化された仮説は同時に五つのことを変えて、どれが効いたかを推測するのを止めます。最小限の変更は挙動を壊すリスクや新しいボトルネックを作るリスクを下げます。再測定はウォームキャッシュによるプラセボ的改善や回帰を暴きます。

「完了」は感覚ではなく結果です：目標指標が正しい方向に動き、明白な回帰（エラー、高いメモリ、悪化したp95、周辺エンドポイントの遅延）がないことが確認できたら終わりです。

いつ止めるかを知ることもワークフローの一部です。改善が平坦化したとき、指標がユーザーにとって十分に良いとき、または次のアイデアが大規模なリファクタを要し見返りが小さいときに止めます。パフォーマンス作業には常に機会コストがあるので、ループは効果が出るところに時間を使う助けになります。

指標を選びベースラインを固定する

五つの指標を同時に測ると何が改善したかわかりません。今回の調査では一つの主要指標を選び、他は補助のシグナルとして扱ってください。ユーザー向けの問題では多くの場合その指標はレイテンシです。バッチ処理ならスループット、CPU時間、メモリ使用量、あるいは1実行あたりのクラウドコストが指標になります。

シナリオを具体的にします。"APIが遅い"は曖昧すぎます。"通常のカート3点での POST /checkout"は測定可能です。入力を安定させて数値に意味を持たせてください。

コードを触る前にベースラインと環境の詳細を書き留めます：データセットサイズ、マシン種別、ビルドモード、機能フラグ、同時実行、ウォームアップ。これがアンカー（基準）です。これがないと、どの変更も進歩に見えてしまいます。

レイテンシでは平均だけでなくパーセンタイルに依存してください。p50は典型的な体験を示し、p95/p99はユーザーが不満を持つ尾を露呈します。p50が改善してp99が悪化することはあり得ます。

「意味のある改善」を事前に決めておくとノイズで祝わなくて済みます：

• レイテンシ：p95で少なくとも10%の改善（または50msなどの固定閾値）
• スループット：同じエラー率で少なくとも5%のリクエスト/秒増加
• CPUまたはメモリ：スケールやクラッシュを避けられるだけの削減
• コスト：1実行または1,000リクエストあたりで測定可能な低下

これらのルールがあれば、ゴールポストを動かさずにアイデアを試せます。

プロファイリングとシンプルな指標で証拠を集める

信頼できる最も簡単なシグナルから始めます。リクエスト周りの単一のタイミングで本当に問題があるか、どれくらい大きいかがわかることが多く、深いプロファイリングは「なぜ遅いか」を説明する必要が出てから使えば十分です。

良い証拠は通常、複数のソースの組み合わせから得られます：

• アプリログ（リクエスト時間、エラー率、遅いエンドポイント）
• APMトレース（サービス間で時間がどこに使われているか）
• プロファイラ出力やフレームグラフ（ホットな関数とコールスタック）
• データベース統計（遅いクエリ、ロック待ち、キャッシュヒット率）
• インフラ指標（CPU、メモリ、ネットワーク、コンテナ再起動）

問いが「遅くなっているか、どれだけか？」ならシンプルな指標を使い、問いが「時間がどこに行っているか？」ならプロファイリングを使ってください。deploy後にp95が倍になったなら、まずタイミングとログで回帰を確認して範囲を定めます。タイミングで遅延の大半がアプリコード内にあるなら、CPUプロファイラやフレームグラフで増えた正確な関数を指し示せます。

計測は安全に行ってください。デバッグに必要な情報を集めつつユーザーデータは集め過ぎないようにします。集計（期間、カウント、サイズ）を優先し、識別子はデフォルトでマスキングします。

ノイズは現実です。複数サンプルを取りアウトライヤーを記録してください。同じリクエストを10〜30回実行し、1回のベストランではなく中央値とp95を記録します。

変更後に再現できるように、正確なテスト手順（環境、データセット、エンドポイント、リクエストボディサイズ、同時実行数、結果の取り方）を書き留めておきます。

証拠を明確な仮説に変える

まず名前の付く症状から始めます："トラフィックピーク時にp95が220msから900msに跳ね上がる"、"CPUが2コアで95%に張り付く"、"メモリが時間あたり200MB増える"など。"遅く感じる"のような曖昧な症状はランダムな変更に繋がります。

次に測定を元に疑わしい領域を特定します。フレームグラフが大半の時間をJSONエンコードに示すかもしれませんし、トレースが遅い呼び出し経路を示すかもしれません。全体のコストの多くを説明する最小の領域（関数1つ、SQLクエリ1つ、外部呼び出し1つ）を選びます。

良い仮説は1文で、検証可能で、予測が結びついています。助けを求めるときは「ツールにすべてを速くしてくれ」と頼むのではなく、アイデアを検証する手順を求めてください。

シンプルな仮説テンプレート

次の形式を使ってください：

• (証拠)のために、(疑わしい箇所)が(症状)を引き起こしている。
• (特定の振る舞い)を変えれば、(指標)が(概算の量)改善するはずだ。
• (再測定での結果)が出ればうまくいったと判断する。

例："プロファイルがSerializeResponseにCPUの38%を示しているので、リクエストごとに新しいバッファを割り当てていることがCPUスパイクの原因だ。バッファを再利用すれば、同じ負荷でp95レイテンシが約10〜20%低下し、CPU使用率は約15%下がるはずだ。"

変更前に代替案を2〜3個書いておくと自分に厳しくできます。遅い原因は上流の依存、ロック競合、キャッシュミス率の変化、ロールアウトでペイロードが増えたことなどかもしれません。

2〜3の代替説明を書いて、その中で証拠が最も支持するものを選びます。もし変更が指標を動かさなければ、次の仮説へ進めます。

Claude Code を使うときに推測に陥らない方法

Claudeは注意深いアナリストのように扱うとパフォーマンス作業で最も有用です。あくまで測定に結びついた提案を行い、各ステップが反証可能であることを確認してください。

曖昧な説明ではなく、実際の入力（小さく焦点を絞った証拠）を渡します：プロファイルの要約、遅いリクエスト周辺のログ数行、クエリプラン、特定のコードパスなど。必ず「変更前」の数値（p95、CPU時間、DB時間）を含めてベースラインを知らせます。

データが示唆することと示唆しないことを説明させ、競合する説明を強制してください。便利なプロンプトの終わりにはこう付けます："2〜3の仮説を出し、それぞれを反証するテストを書け。" こうすれば最初に妥当に見える筋書きに固執するのを防げます。

何かを変更する前に、主要仮説を検証できる最小の実験を求めてください。素早く可逆なもの：関数周りにタイマーを1つ追加する、プロファイラフラグを1つ有効にする、EXPLAINで1回クエリを実行する、などです。

出力を厳密な構造にしたければ、次を要求してください：

• 証拠が示すこと（と信頼度）
• 2〜3の仮説とそれぞれの反証テスト
• トップの仮説を検証するための最小のコード／設定変更
• 再測定すべき正確な指標と期待される方向性

もし具体的な指標、場所、期待結果を出せないなら、それはまた推測に戻っているという合図です。

最小限で可逆な変更を行う

証拠と仮説があるなら、「全部きれいにする」衝動を抑えてください。パフォーマンス作業は小さく元に戻せる変更の方が信頼しやすいです。

1度に1つだけ変えます。クエリを調整し、キャッシュを追加し、ループをリファクタを同じコミットでやると何が効いたかわかりません。単一変数の変更なら次の測定が意味を持ちます。

コードを触る前に、期待する変化を数値で書いておきます。例："p95を420msから300ms未満に下げ、DB時間を約100ms削る"。目標を外したら仮説が弱かったか不完全だったと速く学べます。

可逆性を保つ方法：

• きれいにロールバックできる小さな差分にする。
• シンプルなフラグの背後に入れてすぐにオフにできるようにする。
• 名前変更やフォーマット変更とロジック変更を混ぜない。
• 範囲は狭く：1エンドポイント、1ホットパス、1つの高コスト呼び出し。
• 期待する前後のメトリクスをコミットメッセージに短く書く。

「最小限」は「取るに足らない」を意味しません。フォーカスされた改善：高コストな関数結果を1つキャッシュする、タイトなループの繰り返し割り当てを1つ除去する、あるいは不要な処理をあるリクエストで止める、などです。

疑わしいボトルネック周辺に軽いタイミングを入れて、何が動いたかを見られるようにします。呼び出し前後にタイムスタンプを1つ入れるだけ（ログかメトリクスとして）で、変更が本当に遅い箇所に効いたか確認できます。

再測定して次を決める

変更後はベースラインと同じシナリオを正確に再実行します：同じ入力、同じ環境、同じ負荷形状。キャッシュやウォームアップが必要ならそれを明示しないと偶然の改善を見つけてしまいます。

同じ指標と同じパーセンタイルで結果を比較します。平均値は痛みを隠すので、p95/p99、スループット、CPU時間を見ます。数回繰り返して数値が収束するか確認します。

祝う前に、ヘッドラインの数値に出ない回帰をチェックします：

• 正確性：レスポンスは期待通りか
• エラー率：タイムアウトや5xx、リトライは増えていないか
• メモリ：ピークや継続的増加がないか
• テールレイテンシ：p99が悪化していないか
• リソースコスト：CPUやDB負荷が急増していないか

その後、証拠に基づいて判断します。改善が実在し回帰がなければ採用します。結果が混在しているかノイジーならロールバックして新しい仮説を立てるか、変更をさらに隔離します。

Koder.aiのようなプラットフォームで作業しているなら、実験前にスナップショットを取っておくことでロールバックがワンステップになり、大胆なアイデアを安全に試しやすくなります。

最後に学んだことを短く書き残します：ベースライン、変更点、新しい数値、結論。これが次のラウンドで同じ行き止まりを繰り返さない助けになります。

時間を無駄にする一般的なミス

パフォーマンス作業が横道にそれるのは、測定したものと変更したものの関連を失うときです。証拠の連鎖を保ち、何が良くなったか／悪くなったかを自信を持って言えるようにしてください。

よくある失敗：

• 間違ったターゲットを直す：中央値(p50)が速くなったが尾(p95/p99)は悪いまま
• 一度に多くのことを変える：リファクタ、キャッシュ、クエリ調整を同じコミットで行う
• ノイジーな1回の実行を信じる：ローカルベンチがラン間で20%振れるなら証拠にならない
• 単一プロファイルを全てとみなす：フレームグラフがJSON解析を示しても実際はDBがボトルネックかもしれない
• 条件を揃えずに比較する：データセット、フラグ、ハード、同時実行を変えて結論を出す

小さな例：エンドポイントが遅く見えるのでシリアライザを調整したら小さいデータセットで速くなったように見えた。しかし本番のp99は悪化し続けた。原因はDBがボトルネックのままで、変更がペイロードを増やしてしまったためです。

Claude Codeに修正案を出させるときは短く絞って使ってください。既に集めた証拠に合う1〜2の最小変更を求め、パッチを受け入れる前に必ず再測定計画を要求してください。

「速くなった」と言う前の簡単チェックリスト

テストがあいまいだと速度の主張は崩れます。祝う前に、何をどう測ったか、どう測ったか、何を変えたかを説明できるようにしてください。

始めに1つの指標を決め、ベースラインの結果を書き留めます。数値を変えうる要素（マシン、CPU負荷、データセットサイズ、ビルドモード、機能フラグ、キャッシュ状態、同時実行）を含めること。明日再現できないセットアップならベースラインはないのと同じです。

チェックリスト：

• 指標とベースラインが環境メモとともに記録されている（ハード、設定、データ、ウォーム／コールド）
• テスト手順が書かれ再現可能である
• 1つの仮説と予測がある（例えば「N+1クエリを除去すればp95は約30%下がる」）
• 1つの小さく可逆な変更を行い、何が動いたかを正確に記録した（ファイル、関数、クエリ、設定）
• 複数サンプルで再測定し同条件で比較した

数値が良くなったら短い回帰チェックを行います：出力の正確性、エラー率、タイムアウトを確認し、メモリ増加、CPUスパイク、起動遅延、DB負荷増加といった副作用を観察します。p95が良くてもメモリが倍増するならトレードオフとして間違っています。

例：遅いAPIエンドポイントの段階的調査

チームが GET /orders は開発環境では問題ないが、ステージングで中程度の負荷になると遅くなると報告しました。ユーザーはタイムアウトを訴えますが平均レイテンシは「まあまあ」に見える、これは典型的な落とし穴です。

まずベースラインを設定します。同じデータセット・同じ同時実行・同じ期間の負荷テストで記録した結果：

• p95レイテンシ: 1.8s（目標は < 600ms）
• API CPU: 約70%（時折スパイク）
• DB: あるクエリが900–1100msかかっており、リクエストあたりの総クエリ時間は約1.3s

証拠を集めると、エンドポイントは注文を取得するメインクエリを実行した後、注文ごとに関連アイテムをループで取りに行っていることがわかりました。JSONレスポンスは大きいですが、DB時間が支配的です。

これを仮説リストに変えます：

• 遅いクエリにインデックスが必要だ。
• N+1クエリがDB時間を増幅している。
• シリアライズが巨大なペイロードで遅い。
• ロック競合で読み取りが書き込み時に停滞している。

最も強い証拠に一致する最小の変更を求めます：注文IDでキーをまとめて一度にアイテムを取得する（または遅いクエリプランがフルスキャンを示すなら欠けているインデックスを追加する）。可逆でフォーカスしたコミットにします。

同じ負荷テストで再測定した結果：

• p95: 1.8s → 720ms
• 総DB時間: ~1.3s → ~420ms
• CPU: やや低下、しかしスパイクは残る

判断：明確な勝ちなので修正を出荷し、残るギャップとCPUスパイクに次のサイクルで取り組みます（DBはもはや主要制約ではない）。

次のステップ：このワークフローを日常化する

改善が早くなる最も簡単な方法は、各ランを小さな再現可能な実験として扱うことです。一貫したプロセスにすれば、結果は信頼しやすく、比較や共有が楽になります。

簡単な1ページテンプレート：

• 指標 + 計測方法（ツール、コマンド、データセット）
• ベースライン（数値、環境、取得時刻）
• 仮説（1文、検証可能）
• 変更（小さな差分、触った箇所）
• 結果（前／後、判断）

これらのノートの置き場所を決めて消えないようにしてください。共有場所は完璧なツールよりも重要です：サービス横のリポジトリ、チームドキュメント、チケットノートなど。誰かが数ヶ月後に「キャッシュ変更後のp95スパイク」を見つけられることが重要です。

安全な実験を習慣化してください。スナップショットと簡単なロールバックで大胆なアイデアを恐れず試せます。Koder.aiで開発しているなら、Planning Modeは計測計画を書き、仮説を定義し、変更範囲を狭めてからタイトな差分を生成して再測定する流れに便利です。

ペースを決めてください。インシデントを待つ必要はありません。新しいクエリやエンドポイント、大きなペイロード、依存関係アップグレードの後に10分程度のベースラインチェックを加えるだけで、後で1日の推測作業を節約できます。