メインコンテンツへスキップ
BayashiLab LogoBayashiLab(バヤシラボ)
ブログ一覧

Claude Code LSPツールで大規模コードベースのナビゲーションと修正を劇的に高速化する

Claude CodeLSPコードナビゲーションリファクタリング開発効率化

大規模なコードベースでClaude Codeを使っていて、「関数の定義元を探すのに時間がかかりすぎる」「Grepの結果が多すぎて的外れな修正をされた」という経験はないだろうか。2025年12月にリリースされたClaude Code v2.0.74のLSP（Language Server Protocol）統合は、この問題を根本から解決する機能だ。

本記事では、LSPツールのセットアップから実践的なワークフローまでを、TypeScript・Python・Goの3言語で解説する。

LSPツールが解決する問題

従来のClaude Codeは、コードベースの探索にGrep（テキスト検索）を使っていた。これは小規模プロジェクトでは十分だが、数百ファイルを超えるプロジェクトでは深刻なボトルネックになる。

たとえば getUserById という関数の呼び出し箇所をすべて見つけたいとする。Grepは「テキストとしての一致」しか見ないため、コメント内の記述、文字列リテラル、別モジュールの同名関数まで拾ってしまう。結果、Claudeは大量のノイズを処理することになり、時間もトークンも浪費する。

LSPはこの問題を構造的に解決する。IDEが内部で使っているのと同じシンボル解析エンジンを通じて、Claude Codeが「コードの意味」を理解できるようになる。

操作 Grep検索 LSP
関数の全呼び出し箇所の特定 約45秒 約50ms
トークン消費量（100ファイル規模） 約2,000トークン 約500トークン
型エラーの即座検出 不可 可能
同名関数の区別 不可 可能

正直、最初にこの速度差を体感したときは「今まで何をしていたんだ」という気持ちになった。

セットアップ手順（5分で完了）

ステップ1: LSPツールの有効化

シェルの設定ファイルに環境変数を追加する。

bash
# ~/.zshrc または ~/.bashrc に追加
export ENABLE_LSP_TOOL=1

設定を反映する。

bash
source ~/.zshrc

ステップ2: プラグインマーケットプレイスの追加

Claude Code内で以下のコマンドを実行し、LSPプラグインのマーケットプレイスを登録する。

code
/plugin marketplace add Piebald-AI/claude-code-lsps

この操作は一度だけ行えばよい。セッションをまたいで永続化される。

ステップ3: 言語別プラグインのインストール

使用する言語に応じてプラグインをインストールする。

code
# TypeScript / JavaScript
/plugin install vtsls@claude-code-lsps

# Python
/plugin install pyright@claude-code-lsps

# Go
/plugin install gopls@claude-code-lsps

ステップ4: 言語サーバーバイナリの準備

プラグインとは別に、実際の言語サーバーがシステムにインストールされている必要がある。

bash
# TypeScript
npm install -g typescript typescript-language-server

# Python
pip install pyright

# Go（Go本体をインストール済みなら）
go install golang.org/x/tools/gopls@latest

動作確認

セットアップ後、Claude Codeに「getUserById の定義元を教えて」と聞いてみよう。Grepではなく、具体的なファイルパスと行番号が即座に返ってくれば、LSPが正しく動作している。

LSPが提供する5つの操作

LSPツールは以下の5つのコア操作をClaude Codeに追加する。

1. goToDefinition — 定義ジャンプ

シンボルの定義元に直接ジャンプする。インポート先を追いかけるためにGrepで検索する必要がなくなる。

2. findReferences — 参照検索

関数や変数のすべての使用箇所を、意味的に正確に列挙する。リファクタリング時の影響範囲の特定に不可欠だ。

3. hover — 型情報の取得

シンボルの型情報やドキュメントを取得する。推論された型も確認できるため、TypeScriptやGoでの型の不整合を素早く発見できる。

4. documentSymbol — ファイル構造の把握

ファイル内のクラス、関数、変数などの構造を一覧で取得する。大きなファイルの全体像を把握するのに役立つ。

5. getDiagnostics — リアルタイム診断

ファイル編集直後に型エラーや構文エラーを検出する。これにより、Claude Codeが「編集 → ビルド → エラー確認 → 修正」のサイクルを回す前に、問題を即座に把握できる。

実践ワークフロー: 3言語での使用例

TypeScript: インターフェース変更の影響範囲を特定する

APIレスポンスの型を変更する場面を想定する。

typescript
// types.ts - 変更前
export interface UserResponse {
  id: string;
  name: string;
  email: string;
}

// types.ts - 変更後（ネストされたprofileを追加）
export interface UserResponse {
  id: string;
  profile: {
    name: string;
    email: string;
  };
}

LSPなしの場合、Claudeは UserResponse をGrepで検索し、インポート文やコメントも含めた大量の結果を処理する。LSPありなら、findReferences で実際に UserResponse.name や UserResponse.email にアクセスしている箇所だけを正確に特定し、それぞれを UserResponse.profile.name に書き換える。

Python: 関数のリネームを安全に行う

python
# utils/auth.py - リネーム対象
def verify_token(token: str) -> dict:
    """JWTトークンを検証して、ペイロードを返す"""
    ...

Claude Codeに「verify_token を validate_jwt_token にリネームして」と依頼する。LSPの findReferences がすべてのインポート文、呼び出し箇所、テストコードを列挙し、漏れなくリネームが完了する。さらに getDiagnostics が変更後の型エラーを即座に検出するため、見落としがない。

Go: インターフェース実装の追跡

go
// repository.go
type UserRepository interface {
    FindByID(ctx context.Context, id string) (*User, error)
    Save(ctx context.Context, user *User) error
}

Goでは、インターフェースの実装が暗黙的なため、Grepでは実装箇所を見つけにくい。LSPの goToDefinition と findReferences を組み合わせることで、UserRepository を実装しているすべての構造体を正確に特定できる。これはモノレポで複数の実装が存在する場合に地味に便利だ。

カスタムLSP設定（.lsp.json）

マーケットプレイスのプラグインではカバーできない要件がある場合、プロジェクトごとにカスタム設定を作成できる。

json
{
  "name": "my-project-lsp",
  "lspServers": {
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"],
      "extensionToLanguage": {
        ".ts": "typescript",
        ".tsx": "typescriptreact"
      }
    },
    "python": {
      "command": "pyright-langserver",
      "args": ["--stdio"],
      "extensionToLanguage": {
        ".py": "python",
        ".pyi": "python"
      }
    },
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

よくあるハマりポイント

「No LSP server available」と表示される

最も多い原因は、言語サーバーのバイナリがPATHに含まれていないこと。特にNode.jsをnvm/fnm経由で管理している場合、Claude Codeのプロセスからはグローバルインストールしたバイナリが見えないことがある。フルパスでの指定を試そう。

bash
which typescript-language-server
# 出力されたパスを.lsp.jsonのcommandに直接指定する

LSPの起動が遅い

初回起動時に言語サーバーがプロジェクトのインデックスを構築するため、大規模プロジェクトでは数十秒かかることがある。2回目以降はキャッシュが効くため高速になる。

モノレポでの言語サーバーのスコープ

モノレポの場合、言語サーバーがルートディレクトリから起動されると、不要なパッケージまでインデックスに含まれることがある。initializationOptions でワークスペースのルートを適切に設定すると改善する。

まとめ

Claude CodeのLSP統合は、テキスト検索からシンボル解析への移行という、コード理解の質的な変化をもたらす。セットアップは5分程度で完了し、効果はプロジェクトの規模が大きいほど顕著になる。

特に以下のケースでは導入の優先度が高い:

  • 100ファイル以上のプロジェクトで日常的にClaude Codeを使っている
  • リファクタリングや関数リネームを頻繁に行う
  • モノレポや複数言語のプロジェクトを扱っている
  • Claude Codeのトークン消費を削減したい

まだ設定していないなら、ENABLE_LSP_TOOL=1 を追加してプラグインを入れるところから始めてみてほしい。探索精度とレスポンス速度の違いは、すぐに実感できるはずだ。

もっと読む他の技術記事も読む