ある開発者が、隠れた npx のルックアップが Claude Code の各ターンに約10秒の遅延をもたらしていることを発見しました。ルックアップをグローバルインストールに置き換えることで、各インタラクションから6秒を短縮できました。

なぜレイテンシが問題だったのか

Claude Code は、数十のコンポーネントを含むモノレポをナビゲートし、シンボルをインデックス化し、Postgres にトランスクリプトを保存し、エラーレポートを送信します。ワークフローはスムーズに感じられますが、モデルのレスポンスが遅れ始めると問題が顕在化します。ヘルスチェックを行ったところ、いくつかの非効率な点と、コストの高い1つのネットワークコールが明らかになりました。

ヘルスチェックで判明したこと

  • 重複したインストール – ネイティブのランチャーと古い npm-global バージョンが共存していました。古いコピーを削除することで、不要なパスのルックアップを排除しました。
  • 壊れたエージェントファイル – 説明のないファイルが有効なファイルと同じ名前になっており、Claude Code がそのファイルを無視する原因となっていました。壊れたエントリを削除することで、混乱を解消しました。
  • 未使用の拡張機能 – 一度も実行されることのないプラグインと MCP サーバーを無効化し、ランタイムのフットプリントを削減しました。
  • 肥大化した「CLAUDE.md」ファイル – これらのファイルには、コード内に既に存在する情報（例：ビルドコマンド）が繰り返し記述されており、モデルに送信されるペイロードを増大させていました。内容を削ぎ落とし、不可欠なコンテキストのみを残しました。

これらのクリーンアップも効果的でしたが、最大の成果は、モデルのレスポンス後に実行される Stop hook から得られました。

隠れた npx 税

Stop hook は 6 つの個別のコマンドを実行しますが、それぞれに npx -y という接頭辞が付いています。-y フラグは、コマンドを実行する前に npx に npm レジストリで新しいバージョンがないか確認させるため、ネットワークリクエストを発生させます。各ルックアップには平均 1.6 秒 かかり、6 回の呼び出しによって、すべてのターンに 約 10 秒 が追加されていました。実際には、フック全体のレイテンシは 12 秒 と測定され、ネットワークの不調時には最大 113 秒 までスパイクが発生することもありました。

シンプルな解決策

npx の呼び出しをグローバルにインストールされたバイナリに置き換えることで、レジストリのルックアップを排除しました。

  • Before: npx -y @invariance/gps → 1 回あたり 1.6 秒
  • After: gps (グローバルインストール済み) → 1 回あたり 0.7 秒

この変更により、Stop hook の実行時間は 1 ターンあたり約 6 秒 短縮され、リモートチェックによる大幅なスパイクも解消されました。

次に注意すべき点

  • フックのタイミング – カスタムフックに計測処理を組み込み、ユーザーに影響が出る前にレイテンシを可視化してください。
  • 依存関係の衛生管理 – 重複したインストールや未使用の拡張機能を定期的に整理してください。
  • 設定ファイル – 「CLAUDE.md」は軽量に保ち、モデルが推論できない情報のみを記載するようにしてください。

教訓はシンプルです。自動化は、コストのかかる内部的な仕組みを隠してしまうことがあります。素早いヘルスチェックを行えば、スムーズな AI アシスタントを鈍重なものに変えてしまう、隠れたネットワークコールを見つけ出すことができます。

まとめ: Claude Code が遅いと感じたら、フックの実行時間を計測し、npx のルックアップを排除しましょう。グローバルインストールを活用することで、各ターンの時間を短縮し、開発フローをスムーズに保つことができます。