Article

Claude Codeでメモリリークやパフォーマンス問題を調査する流れ

Claude Code本体が重くなったとき、または開発中のアプリのメモリリーク・パフォーマンス問題を調査するときに踏むべき手順を整理します。`/heapdump`や`/doctor`を起点とした切り分け、測定→仮説→変更→再計測の型、AIに依頼するときの安全な渡し方までを公式仕様と現場運用の両面でまとめた、環境依存の大きい問題を切り分けたい人向けの実務ガイドです。

This article is not published in this language yet, so the Japanese version is shown instead.

Claude Codeが重い／落ちる、または開発中のアプリでメモリリークやパフォーマンス低下が出たとき、最初にやるべきは「AIに直してもらう」ではなく「測る」ことです。本記事は、測定→仮説→変更→再計測の型と、AIに渡すときの安全な情報整理を、Claude Code本体側／アプリ側の両面で整理します。

結論：先に切り分ける。Claude Code本体かアプリ側か

パフォーマンス問題は症状が似ていても、Claude Code本体の問題と、開発しているアプリ側の問題でやることがまったく違います。最初に1分使って切り分けます。

症状	切り分け先
Claude Codeの応答が遅い／重い／ハングする	本体側
Claude Codeで書いたアプリが実行時に重い／メモリが増え続ける	アプリ側
Claude Codeが落ちる（`Killed: 9`、メモリ不足エラー）	本体側（環境含む）
ビルド／テストが遅い	アプリ側（ツールチェイン含む）

本体側のことは「Claude Codeが遅いときに確認する設定・コンテキスト・ファイル量」に網羅しています。本記事は「測って原因を狭めて、AIに渡す」流れに集中します。

測定なしの修正は禁止

Anthropic公式のbest practicesも、性能問題のような「事実が必要な領域」では「verify its work」を強調しています。次のような依頼は失敗します。

「なんとなく重いので速くして」
「メモリリークが疑われるので直して」
「最適化して」

測定値・再現条件・期待値が無いと、AIは「それっぽい一般論」を書いて、効いていなくても通ってしまいます。最低限、次の3つは人間が確定させてからAIに渡します。

再現条件：どのコマンド・どの入力・どの環境で起きるか
測定値：時間／メモリの実数。前後比較のためのベースライン
期待値：「30秒以内」「ピーク500MB以内」など合格条件

Claude Code本体側：`/heapdump`と`/doctor`

Claude Code本体が重いときは、公式の診断機能から始めます。

まず/doctorで環境問題を切り分けます。次に/contextでコンテキスト消費の内訳を確認します。コンテキストが90%を超えていたら、それ自体が原因のことが多いので、対処は「Claude Codeでコンテキストウィンドウを無駄にしない運用方法」に従って/clear／/compact／Esc Escを使います。

メモリ側を見たいときは/heapdumpを使います。~/Desktopに.heapsnapshotが出力され、RSS・JSヒープ・ArrayBuffer・ネイティブ内訳の概要が確認できます。出力先と内容は公式のtroubleshootingに記載されています。

ハングして反応がないときの順序は決まっています。

Ctrl+Cで中断
反応が無ければプロセスを終了して再起動
claude --resumeで続きから再開

/rewindは会話履歴のロールバックで、メモリやハングの解決手段ではありません。混同しないようにします。

アプリ側：測定→仮説→変更→再計測の4ステップ

開発中のアプリのメモリリーク・パフォーマンス問題は、次の4ステップで回します。AIに任せていいのはステップ2と3の途中だけで、ステップ1と4は人間が手元で実行します。

ステップ1：測る（人間）

言語ごとに標準のプロファイラがあります。「測定値が手元にある」状態を作るのは人間の責任です。

領域	代表的な計測手段
Node.js	`node --inspect`＋Chrome DevTools、`--prof`、`clinic.js`
ブラウザ	Chrome DevToolsのPerformanceパネル、Memoryパネル
Python	`cProfile`、`memray`、`tracemalloc`
Go	`pprof`、`go test -bench`
Rust	`cargo flamegraph`、`heaptrack`
OS全般	`time`、`/usr/bin/time -l`（macOS）、`top`、`htop`

最低でも「処理時間」「ピークメモリ」「同じ操作を10回繰り返したときのメモリ推移」の3点を取ります。メモリリーク疑いは1回の値ではなく増加傾向で判定します。

ステップ2：仮説を出させる（AIに依頼）

測定値が揃ったら、仮説出しをAIに依頼します。Plan Modeで実装させずに3つくらい候補を挙げさせるのが効率的です。

依頼文テンプレートは次のとおりです。

症状: <操作>を繰り返すとピークメモリが500MBから1.2GBまで増え続ける（10回計測）

再現環境:
- Node.js v22.x、macOS Sonoma
- npm test の <テスト名> で再現

測定値:
- 1回目: 510MB
- 5回目: 820MB
- 10回目: 1.2GB（添付の memray-snapshot.json 参照）

関連ファイル: @src/cache/index.ts @src/api/handler.ts

依頼:
1. 上記の症状と測定値から、原因仮説を3つ出す
2. 各仮説について「直接原因／上流原因／検証方法／影響範囲」を書く
3. 実装はまだしない。Plan Modeで止める

禁止事項:
- 測定値の改ざんや前提の書き換え
- 仮説に根拠のない最適化提案を混ぜる

依頼の型は「Claude Codeに伝わるプロンプトの基本構造」、デバッグ依頼の作り方は「Claude Codeでスタックトレースを読ませてバグ原因を調べる方法」も合わせて参考になります。

ステップ3：変更する（AIに依頼／人間が承認）

仮説が固まったら、1仮説ずつ最小修正をAIに依頼します。複数仮説を同時に試すと、効いた原因が分かりません。

依頼文には必ず次の3つを含めます。

触ってよいファイル：仮説に関係するファイルだけ
触ってはいけない箇所：公開API、テストの期待値
合格条件：再計測でどう変わったら採用するか

仮説と実装が分離していないと、効かなかったときに「効かなかった」のか「実装が悪かった」のかが切り分けられません。

ステップ4：再計測する（人間）

変更後、ステップ1と同じ条件で再計測します。重要なのは「同じ条件で」やることです。次のような変更で計測条件が変わると、改善したように見えてしまいます。

ウォームアップの回数
キャッシュの初期状態
並列実行数
入力データのサイズ

AIに再計測まで任せるとここを揃え忘れがちです。再計測は手元のターミナルで人間がやります。

メモリリーク特有のパターン

メモリ「リーク」と単なる「使用量増加」は別物です。リークと判定するには、解放されるべきものが解放されていないことの根拠が必要です。

症状	多い原因
長時間稼働でじわじわ増える	イベントリスナー解除漏れ、`setInterval`のクリア忘れ
特定操作で1回ずつ増える	クロージャに大きなオブジェクトを掴ませている
HTTPリクエスト処理ごとに増える	リクエストスコープのものを長寿命キャッシュに入れている
ブラウザでタブを操作するうちに増える	DetachedなDOMノードを参照したまま

ヒープスナップショットを2点取って差分を見るのが基本です。Node.jsならprocess.memoryUsage()のheapUsedを時系列で記録し、DevToolsのComparisonビューで増えたコンストラクタを特定します。