Claude CodeのCodSpeedプラグインでベンチ結果とフレームグラフを読む

CodSpeedプラグインは、ベンチマークの実行結果とフレームグラフをClaude Codeに読ませるためのプラグインです。/plugin install codspeed@claude-plugins-official の1行で、CodSpeedのMCPサーバーとエージェントスキルが一緒に入ります。Claudeは計測、フレームグラフの解析、修正、再計測を繰り返し、速くならなくなるまで詰めていきます。

この記事では導入から、計測の土台になるCLI、3つの計測モード、フレームグラフの読み方、CLAUDE.mdへの書き方までを順に扱います。

プラグイン1本でMCPサーバーとスキルが入る

CodSpeedは「性能テストのツールキット」です。プラグインはCodSpeed社が提供し、マーケットプレイスの説明には、ベンチ結果・フレームグラフ・性能比較をClaudeに渡し、ボトルネックの特定と改善の反復を任せる、とあります。

入れるものは次の2つです。

• CodSpeedのMCPサーバー(https://mcp.codspeed.io/mcp でCodSpeedがホスト)
• エージェントスキル(codspeed-optimize と codspeed-setup-harness)

claude plugin install codspeed@claude-plugins-official

Claude Codeのセッション内では /plugin install codspeed@claude-plugins-official を使います。この場合はすぐには入らず、/plugin パネルがプラグインの詳細で開きます。フックやMCPサーバーを含み得るので、中身を見てからスコープを選ぶ流れです。

プラグインを使わずMCPサーバーだけ足す方法もあります。

claude mcp add --transport http CodSpeed https://mcp.codspeed.io/mcp

ただしスキルは入りません。スキルはMCPサーバーの設定が前提で、MCPが「データへの入り口」、スキルが「どう動くかの手順」という役割分担です。

認証はOAuthです。初回接続でブラウザが開き、CodSpeedにログインして許可すると、トークンはクライアントが保存して更新します。APIキーを管理する必要はありません。見えるのはCodSpeedアカウントがアクセスできるリポジトリのデータです。

MCPサーバーが公開するツールは7つあります。

導入後に毎セッション足されるトークン量が気になるときは、claude plugin detailsでの測り方が使えます。組織の管理設定でMCPの追加が止められている環境では、claude mcp addが失敗する原因も確認してください。

計測の土台を先に作る: CLIとexec・run

Claudeが読むのは、CodSpeedに記録されたrunです。記録するには、手元かCIでベンチを回す必要があります。そのためのCLIは次のように入れます。

curl -fsSL https://codspeed.io/install.sh | bash
codspeed auth login

CLIが公式にサポートするのはUbuntu 22.04、24.04、26.04とDebian 12です。ほかのLinuxは動く場合があるものの、サポート対象外とされています。macOSやWindowsのネイティブ環境は、この一覧にありません。手元がmacOSなら、Linuxのコンテナや開発機で回す前提で組むことになります。

ベンチの回し方は2通りです。

コマンド単体を測るなら exec です。

# コマンド単体
codspeed exec -- ./my-binary --arg1 value
 
# スクリプト
codspeed exec -- python my_script.py
 
# 計測モードを指定
codspeed exec --mode walltime -- node app.js

既存のスイートに通すなら run を使い、言語別のハーネスと組み合わせます。

# Rust(criterion)
codspeed run cargo codspeed run
 
# Python(pytest)
codspeed run pytest ./tests --codspeed
 
# Node.js(vitest)
codspeed run pnpm vitest bench

対応する言語とフレームワークは、Rustがdivan・criterion.rs・bencher、C/C++がgoogle-benchmark、Pythonがpytestプラグイン、Node.jsがvitest・tinybench・benchmark.js、Goが標準のtestingパッケージです。

複数のコマンドを設定ファイルで束ねる方法もあります。プロジェクト直下に codspeed.yml を置きます。

options:
  warmup-time: "0.2s"
  max-time: 1s
 
benchmarks:
  - name: "Fast operation"
    exec: ./my_binary --mode fast
    options:
      max-rounds: 20
  - name: "Script benchmark"
    exec: python scripts/benchmark.py

実行は codspeed run --mode walltime です。

ベンチがまだ無いプロジェクトでは、codspeed-setup-harness スキルが出番になります。プロジェクトを分析して言語に合うフレームワークを選び、代表的なベンチを書き、CodSpeed CLIで動くところまで確かめる役です。最適化スキルはベンチが無いとこのスキルを自動で呼び出します。

3つの計測モードの選び分け

フレームグラフが出るのは、CPUシミュレーション、ウォールタイム、メモリの3つのモードです。何を測りたいかで選びます。

メモリモードの対象は、Rust、C/C++、Python(3.12以降)、Node.jsのうち、libc・jemalloc・mimalloc経由で割り当てるプログラムです。

ウォールタイムには注意書きがあります。従来型のVMやホスト型ランナーで使うと、データが安定しません。CodSpeedは、計測の安定性を調整した専用のマクロランナーを勧めています。

Claudeに「速くなったか」を判断させるとき、ここが分かれ目です。CIの共有ランナーでウォールタイムを取ると、同じコードでも値が揺れて、Claudeは揺れを改善や悪化として読むかもしれません。回帰の検出はsimulationで、I/Oを含む実時間はwalltimeでと、目的ごとに分けると読み違いが減ります。

Claudeに最適化ループを任せる

codspeed-optimize スキルは、4つの段階を繰り返します。

CodSpeedのドキュメントには、次のような依頼文の例が載っています。

• 「parse_input 関数を速くして」
• 「bench_serialize のボトルネックを見つけて直して」
• 「feat/parser ブランチで回帰が出ている。調べて」
• 「bench_serialize のフレームグラフを main と feat/new-encoder で比べて、何が変わったか説明して」

MCPサーバーはコーディングエージェントの中で動くので、フレームグラフのホットスポットと実際のソースを突き合わせられます。ここが、ブラウザでグラフを眺める使い方との違いです。ただし、Claudeが提案した変更が本当に速いかどうかは、再計測の数字で決まります。プロンプトの最後に「変更ごとに同じベンチを回し、数字を貼って」と足しておくと、判断材料が会話に残ります。

フレームグラフはSelf timeから読む

query_flamegraph が返すのは画像ではなく、テキストの要約です。自己時間の大きい関数の上位、総時間の大きい呼び出し、スレッドの一覧が表で返ります。人間が読むときも、Claudeの要約を検算するときも、見る順番は同じです。

フレームグラフの基本は、公式の説明で次のとおりです。

• 四角は関数を表し、幅が広いほどその関数に時間がかかっている
• 縦方向は呼び出しの深さを表す
• 同じ関数が複数回呼ばれても、時間は1つのブロックに合算される

Self timeとTotal timeを分けて読むのが最初の関門です。Self timeは関数本体だけの時間、Total timeは子の呼び出しを含む時間です。Total timeが大きい関数は、子に時間を使っているだけかもしれません。直す候補はSelf timeの大きい関数です。

PythonやNode.jsでは、インタプリタの時間もSelf costに入ります。何もしない関数にもSelf costが出るのは、このためです。

CodSpeedのフレームグラフには、色の切り替えがあります。

• By Origin: ユーザーコード、ライブラリ、システム、不明で色分け。自分のコードと依存を分けて見られる
• Differential: ベースとヘッドを比べ、遅くなった・速くなった・追加・削除で色分け
• By Bottleneck: 命令・キャッシュ・メモリ・システムのどれが律速かで色分け
• By Function: 関数ごとに同じ色。呼び出し元が違っても同じ関数を見つけやすい

PythonやNode.jsからC/C++/Rustを呼ぶ構成では、外部関数のデバッグシンボルを出力しておきます。無いと、フレームグラフ上でその関数が読めません。query_flamegraph の要約に Unknown symbol (0x188a80) のような行が出たら、まずシンボルの有無を疑います。

要約が大きすぎるときは、filters で絞ります。pid と tid でプロセスやスレッドを選び、root_function_name で特定の関数を根にして掘り下げます。スレッドの番号は list_threads で調べます。マルチスレッドのプログラムでは、先にスレッド別の時間を見てから絞る順番が自然です。

回帰の調査: 2つのrunを比べさせる

compare_runs は、2つのrunを比べたMarkdownのレポートを返します。改善、回帰、新規、欠落のベンチが並び、CPUやOS、ランタイムのバージョンが違えば、先頭に「Environment Differences」の節が付きます。

この節は見落とさないでください。環境が違うrun同士の差は、コードの差ではなく環境の差かもしれません。CodSpeedのレポート自身が、そう警告しています。回帰を調べるプロンプトには「Environment Differencesがあれば、結論の前に触れて」と入れておくと、Claudeの説明が慎重になります。

CIで継続的にrunを溜める場合は、GitHub Actionsの公式アクションを使います。Pythonの例は次の形です。

permissions:
  contents: read
  id-token: write
 
jobs:
  benchmarks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install -r requirements.txt
      - uses: CodSpeedHQ/action@v5
        with:
          mode: instrumentation
          run: pytest tests/ --codspeed

id-token: write は、OIDCで認証するための権限です。GitLab CIやCircleCIでは、codspeed run --mode simulation -- pytest tests/ --codspeed の形で呼びます。CircleCIはGitHubでホストするリポジトリが対象で、フォークから来たPRはOIDCトークンを取れないため、CODSPEED_TOKEN を環境変数に設定します。

CIで溜めたrunは、MCPサーバーから list_runs と compare_runs で引けます。PRのブランチとmainを比べさせれば、回帰の調査に使えます。

CLAUDE.mdに計測の約束事を書く

Claudeに毎回同じ計測をさせるには、コマンドと判断基準をCLAUDE.mdに書いておくのが近道です。次はPythonプロジェクトの例で、コマンドはREADMEの例に合わせています。

## 性能計測
 
- ベンチは `codspeed run pytest ./tests --codspeed` で実行する
- 最適化の前後で同じコマンドを回し、差は CodSpeed MCP の compare_runs で比べる
- フレームグラフは Self time の大きい関数から直す。Total time だけで決めない
- 変更ごとに再計測の結果を貼る。数字なしで「速くなった」と書かない
- walltime はホスト型ランナーの値を判断に使わない(simulation を使う)

最後の2行が、前節までのつまずきに対応しています。

つまずきやすい点

• macOSやWindowsで動かない: CLIの公式サポートはUbuntuとDebianです。手元がmacOSなら、Linuxの環境で codspeed を動かします
• スキルが働かない: スキルはMCPサーバーの設定が前提です。プラグインを入れていれば両方入りますが、claude mcp add だけで始めた場合はスキルがありません
• データが見えない: MCPで見えるのは、自分のCodSpeedアカウントがアクセスできるリポジトリだけです。list_repositories で見えなければ、先にCLIかCIでrunを作ります
• ウォールタイムが揺れる: 共有ランナーでは安定しません。simulationに切り替えるか、専用ランナーを使います
• 関数名が読めない: 外部関数のデバッグシンボルを出力します
• プラグインが読み込まれない: インストール後の不具合は、packages are not installedの対処や /plugin のErrorsタブから切り分けます

プラグインでスキルとMCPを同時に配る設計は、ほかのプラグインにも共通します。MCPサーバーを自分で作る側の話は、mcp-server-devプラグインの記事にあります。

まとめ

CodSpeedプラグインの価値は、計測結果をClaudeが自分で取りに行ける点にあります。人がグラフのスクリーンショットを貼る代わりに、Claudeがrunを比べ、ホットスポットを引き、ソースと突き合わせます。

ただし、その精度は計測の質で決まります。コマンドの形、simulation と walltime の使い分け、Environment Differencesの扱いを先に決めておくと、Claudeの「速くなりました」を数字で検証できます。