using-typescript-lsp

TypeScript LSP の使用

概要

typescript-lsp プラグインは、TypeScript と JavaScript のセマンティックなコードインテリジェンスを提供します。セマンティックな正確性が必要な場合は、grep/read ではなく LSP ツールを使用してください。LSP は TypeScript の型システム、継承、インターフェース、シンボル間の関係を理解します。

LSP とテキスト検索の使い分け

digraph lsp_decision {
    "Need code info?" [shape=diamond];
    "Semantic accuracy needed?" [shape=diamond];
    "Use LSP tool" [shape=box];
    "Use Grep/Read" [shape=box];

    "Need code info?" -> "Semantic accuracy needed?" [label="yes"];
    "Need code info?" -> "Use Grep/Read" [label="no - text patterns"];
    "Semantic accuracy needed?" -> "Use LSP tool" [label="yes"];
    "Semantic accuracy needed?" -> "Use Grep/Read" [label="no"];
}

LSP を使用するケース：

• リファクタリング前にすべての使用箇所を見つける
• 型情報を取得する（推論された型または明示的な型）
• 定義に移動する（node_modules を含む）
• 型エラーを確認する
• インターフェースの実装を把握する

Grep を使用するケース：

• テキストパターン（コメント、文字列、設定ファイル）
• 複数の言語にまたがる検索
• JSON、YAML、Markdown のコンテンツ
• LSP が利用できない場合

LSP 操作のクイックリファレンス

タスク	LSP 操作	代わりに使用するもの
関数の呼び出し元をすべて見つける	findReferences	関数名で Grep
関数／変数の型を取得する	hover	ファイルを読み取って解析
定義に移動する	goToDefinition	Grep + Read
型エラーを確認する	getDiagnostics	tsc CLI を実行
ファイル構造を表示する	documentSymbol	ファイル全体を読み取る

主なパターン

リファクタリング前：すべての参照を検索する

誤った方法：

Grep for "formatDuration" -> may miss renamed imports, get false positives from comments

正しい方法：

LSP findReferences on symbol -> gets ALL semantic usages, no false positives

型情報の取得

誤った方法：

Read file -> find function -> manually trace type inference

正しい方法：

LSP hover on symbol -> instant type signature with inferred types resolved

型の正しさの確認

誤った方法：

Bash: npx tsc --noEmit (slow, external process)

正しい方法：

LSP getDiagnostics on changed files -> instant, no subprocess

インターフェースの実装を見つける

誤った方法：

Grep for "implements InterfaceName" -> misses duck-typed objects

正しい方法：

LSP findReferences on interface -> finds all implementations including structural matches

よくある間違い

間違い	問題となる理由	修正方法
名前変更の前にシンボルを Grep で検索する	エイリアス付きのインポートや再エクスポートをテキスト検索では見落とします	findReferences を使用する
型を 1 つ確認するためにファイル全体を読み取る	コンテキストを浪費し、時間がかかります	hover を使用する
変更のたびに tsc を実行する	時間がかかり、外部ツールも必要です	getDiagnostics を使用する
定義を見つけるために Grep を使う	誤った一致（同じ名前で別のモジュールにあるもの）が見つかる場合があります	goToDefinition を使用する
インターフェースの使用箇所を Grep で検索する	構造的部分型やダックタイピングを見落とします	findReferences を使用する

LSP ツールの仕組み

LSP は bash コマンドではなく、Claude Code に組み込まれたツールです。typescript-lsp プラグインが有効になっている場合、Claude Code は以下の操作を自動的に提供します。

• goToDefinition - シンボルが定義されている場所に移動する
• findReferences - シンボルの使用箇所をすべて見つける
• hover - 型シグネチャとドキュメントを取得する
• getDiagnostics - ファイルの型エラーを取得する
• documentSymbol - ファイル内のすべてのシンボルを一覧表示する

これらの操作は bash ではなく、Claude のツールシステムを通じて呼び出します。 LSP が利用できない場合は grep/read に切り替えますが、その制約を明記してください。

サポートされているファイルの種類

.ts、.tsx、.js、.jsx、.mts、.cts、.mjs、.cjs

前提条件

1. プラグインが有効であること： ~/.claude/settings.json に typescript-lsp@claude-plugins-official が設定されている
2. 言語サーバーがインストールされていること： npm install -g typescript-language-server typescript
3. プロジェクトが設定されていること： tsconfig.json または jsconfig.json が存在する（正確性を高めるため推奨）

LSP が利用可能か確認する

必ず最初に LSP を試してください。 LSP ツールが利用できない場合は、エラーが返されます。確信が持てないというだけで、先回りして grep に切り替えないでください。

1. Attempt LSP operation (e.g., findReferences)
2. If tool error → fall back to grep/read with documented limitation
3. If success → use the semantic results

フォールバック戦略

LSP が利用できない場合（ツールが見つからない、サーバーが起動していないなど）：

1. 制約を明記する - 「LSP を利用できないため、代わりにテキスト検索を使用しています」と明示してください
2. Grep は注意して使用する - エイリアス付きのインポートや再エクスポートを見落とす可能性があることを理解してください
3. 手動で検証する - リファクタリングでは、結果がセマンティックに妥当であることを再確認してください
4. 解決方法を提案する - typescript-language-server がインストールされ、プラグインが有効になっていることを確認するようユーザーに伝えてください

黙ってフォールバックしないでください。 LSP の代わりにテキスト検索を使用している場合は、制約を理解してもらえるよう、必ずユーザーに伝えてください。

注意点 — LSP を使う

次のような考えが浮かんだときは、grep ではなく LSP を使ってください。

考え	実際には
「この関数を grep で検索しよう」	シンボルなら、findReferences を使ってください
「型を見つけるためにファイルを読もう」	型情報をすぐに確認できる hover を使ってください
「確認のために tsc を実行しよう」	より高速でサブプロセスを起動しない getDiagnostics を使ってください
「これがどこで定義されているか検索しよう」	意味的に正確な goToDefinition を使ってください
「ちょっと検索するなら grep のほうが速い」	意味的なクエリには LSP のほうが高速です
「すべての実装を見つける必要がある」	構造上の一致も検出する findReferences を使ってください

LSP が役に立たない場合

• typescript-language-server のバイナリがインストールされていない
• jsconfig.json のない純粋な JavaScript を扱っている（型推論が限定的）
• 言語をまたぐ参照（例：TypeScript から WASM 経由で Rust を呼び出す）
• コメントや文字列リテラルの検索
• 設定ファイル（JSON、YAML など）
• Node モジュールがインストールされていない（最初に npm install が必要）