LSP コード分析

重要: 前提条件

このスキルを使用するには、以下の手順に従う必要があります:

1. アップデートを確認: 更新スクリプト を実行して、最新バージョンのツールを使用していることを確認してください。
2. プロジェクトのサポートを確認: lsp server start <project_path> を実行して LSP サーバーを起動し、プロジェクトがサポートされていることを確認してください。

これらの手順を実施しない場合、このスキルを使用することは許可されません。

概要

このドキュメントは、lsp-code-analysis スキルの運用要件とベストプラクティスを規定します。Language Server Protocol (LSP) を介したコードベースのナビゲーション、分析、リファクタリングへのセマンティックインターフェースを提供します。

概要

コード分析とナビゲーションのための lsp CLI ツールが提供されます。ほとんどのコード理解タスクでは read や grep より優先して使用すべきです。

使用例:

• セマンティック ナビゲーション: 定義へジャンプ、参照を検索、実装を見つける - テキストパターンだけでなくコード構造を理解します。
• 言語認識: 変数、関数、クラス、型を区別 - テキスト検索からの誤検知を排除します。
• クロスファイル インテリジェンス: 依存関係を追跡、コードベース全体で安全にリファクタリング - 何が何をインポートしているかを認識します。
• 型認識: 実装コードを読まずに正確な型情報、シグネチャ、ドキュメントを取得します。

ツール選択

ガイドライン: コード ナビゲーションと分析には LSP コマンドを優先すべきです。エージェントは、セマンティック分析が適用できない場合（例えば、コメントやリテラル文字列を検索する場合）のみ read や grep を使用できます。

タスク	従来のツール	推奨 LSP コマンド
定義を検索	grep, read	definition
使用箇所を検索	grep -r	reference
ファイルを理解	read	outline
ドキュメント/型を表示	read	doc
リファクタリング	sed	リファクタリング ガイド を参照

コマンド

すべてのコマンドは -h または --help をサポートします。

シンボルの検索

ほとんどのコマンドは、--scope と --find オプションを使用して統一されたロケーション構文をサポートしています。

引数: <file_path>

オプション:

• --scope: シンボル本体または行範囲に検索を限定します。
• --find: スコープ内で検索するテキストパターン。

スコープ フォーマット:

• <line>: 単一行番号（例: 42）。
• <start>,<end>: 行範囲（例: 10,20）。終了を 0 にすると EOF まで（例: 10,0）。
• <symbol_path>: ドット区切りのシンボルパス（例: MyClass.my_method）。

検索パターン (--find):

--find オプションは、ターゲットを選択したスコープ内のテキストパターンに限定します:

• スコープは --scope により決定されます（行/範囲/シンボル）。--scope が指定されない場合、ファイル全体がスコープになります。
• パターン マッチングは空白を無視: スペース、タブ、改行の違いは無視されます。
• カーソル マーカー <|> をパターン内に含めて、マッチ内の正確な位置を指定することができます（例えば、変数名、キーワード、または演算子）。
• --find が省略された場合、コマンドはスコープの開始（またはツール固有のデフォルト）を ナビゲーション対象として使用します。

カーソル マーカー (<|>):

<|> マーカーはシンボル解決の正確な位置を示します。これは右隣の文字を表します。特定の要素を指すためにファインド パターン内で使用します（例: user.<|>name で name プロパティをターゲット）。

例:

• lsp doc foo.py --find "self.<|>" - ファイル全体で self. を検索、ドット後の文字に位置指定（通常はメンバーアクセス補完用）
• lsp doc foo.py --scope 42 --find "return <|>result" - 行 42 で return result を検索、result の r に位置指定
• lsp doc foo.py --scope 10,20 --find "if <|>condition" - 行 10-20 で if condition を検索、condition の c に位置指定
• lsp doc foo.py --scope MyClass.my_method --find "self.<|>" - MyClass.my_method 内で self. を検索、ドット後に位置指定
• lsp doc foo.py --scope MyClass - MyClass シンボルを直接ターゲット

スコープ対 ファインド ガイドライン:

• --scope <symbol_path>（例: --scope MyClass、--scope MyClass.my_method）を使用してクラス、関数、またはメソッドをターゲットにしてください。これはシンボルをターゲットにする最も堅牢で推奨される方法です。
• 変数または特定の位置をターゲットにするには --find を使用してください（多くの場合 --scope と組み合わせて）。ターゲットが一意に命名されたシンボルでない場合、またはコード ブロック内の特定の使用箇所を指定する必要がある場合に使用します。

エージェントは lsp locate <file_path> --scope <scope> --find <find> を使用して、他のコマンドを実行する前にターゲットがファイルに存在するか確認し、そのコンテキストを表示することができます。

# ロケーションが存在することを確認
lsp locate main.py --scope 42 --find "<|>process_data"

ページネーション

reference や search など、大規模な結果セットにはページネーションを使用します。

• --pagination-id <ID>: (必須) 一貫したページング用の一意セッション ID。
• --max-items <N>: ページサイズ。
• --start-index <N>: オフセット（0 ベース）。

例:

# ページ 1
lsp search "User" --max-items 20 --pagination-id "task_123"

# ページ 2
lsp search "User" --max-items 20 --start-index 20 --pagination-id "task_123"

ガイドライン: 一般的なシンボルに対して一意の ID でページネーションを使用し、結果を管理可能なチャンクで取得します。同じ ID を使用して --start-index をインクリメントしてブラウズします。

アウトライン: ファイル構造

実装を読まずに階層シンボル構造を取得します。

# メインシンボル（クラス、関数、メソッド）を取得
lsp outline <file_path>

# 変数とパラメータを含むすべてのシンボルを取得
lsp outline <file_path> --all

エージェントは、ファイルを読む前に outline を使用して、不要なコンテキスト消費を避けるべきです。

定義: ソースへのナビゲーション

シンボルが定義されている場所にナビゲートします。

# User.get_id が定義されている場所にジャンプ
lsp definition models.py --scope User.get_id

# インポートされた変数の出所を検索
lsp definition main.py --scope 42 --find "<|>config"

# 宣言を検索（例: ヘッダーファイル、インターフェース宣言）
lsp definition models.py --scope 25 --mode declaration --find "<|>provider"

# 変数の型のクラス定義を検索
lsp definition models.py --scope 30 --find "<|>user" --mode type_definition

参照: すべての使用箇所を検索

シンボルが使用または実装されている場所を検索します。

# logger が参照されているすべての場所を検索
lsp reference main.py --scope MyClass.run --find "<|>logger"

# インターフェース/抽象クラスのすべての実装を検索
lsp reference api.py --scope "IDataProvider" --mode implementations

# 各参照に対してより多くの周辺コード コンテキストを取得
lsp reference app.py --scope 10 --find "<|>my_var" --context-lines 5

# 大規模なコードベースの結果を制限
lsp reference utils.py --find "<|>helper" --max-items 50 --start-index 0

ドキュメント: ドキュメントを取得

ソースへのナビゲーションなしにドキュメントと型情報を取得します。

# 行 42 のシンボルのドキュメント文字列と型情報を取得
lsp doc main.py --scope 42

# process_data 関数の API ドキュメントを取得
lsp doc models.py --scope process_data

エージェントはドキュメントまたは型情報のみが必要な場合、read より doc を優先すべきです。

検索: グローバル シンボル検索

ロケーションが不明な場合に、ワークスペース全体でシンボルを検索します。

# 名前で検索（デフォルトは現在のディレクトリ）
lsp search "MyClassName"

# 特定のプロジェクトで検索
lsp search "UserModel" --project /path/to/project

# シンボルの種類でフィルター（複数回指定可能）
lsp search "init" --kinds function --kinds method

# 大規模なコードベースの結果を制限してページネーション
lsp search "Config" --max-items 10
lsp search "User" --max-items 20 --start-index 0

エージェントは --kinds を使用して結果をフィルターし、ノイズを削減すべきです。

シンボル: 完全なシンボル コードを取得

ロケーションを含むシンボルの完全なソースコードを取得します。

# 行 15 の関数/クラスの完全なコードを取得
lsp symbol main.py --scope 15

# 完全な UserClass 実装を取得
lsp symbol utils.py --scope UserClass

# 完全なメソッド実装を取得
lsp symbol models.py --scope User.validate

応答には以下が含まれます: シンボル名、種類（クラス/関数/メソッド）、範囲、および完全なソースコード。

エージェントはファイル全体に対して read を使用する代わりに、symbol を使用してターゲットのコード ブロックを読むべきです。

リファクタリング操作

名前変更、抽出、その他の安全なリファクタリング操作についてはリファクタリング ガイドを参照してください。

サーバー: バックグラウンド サーバーの管理

バックグラウンド マネージャーは自動的に起動します。手動制御はオプションです。

# 実行中のサーバーをリスト表示
lsp server list

# プロジェクト用のサーバーを起動
lsp server start <path>

# プロジェクト用のサーバーを停止
lsp server stop <path>

# バックグラウンド マネージャーをシャットダウン
lsp server shutdown

ベストプラクティス

一般的なワークフロー

不慣れなコードを理解する

新しいコードベースを探索するための推奨シーケンス:

# ステップ 1: アウトラインから開始 - 実装を読まずにファイル構造を取得
lsp outline <file_path>

# ステップ 2: シグネチャを検査 - doc を使用して API コントラクトを理解
lsp doc <file_path> --scope <symbol_name>

# ステップ 3: 依存関係をナビゲート - 定義チェーンを辿る
lsp definition <file_path> --scope <symbol_name>

# ステップ 4: 使用状況をマップ - reference でコードがどこで呼び出されているか検索
lsp reference <file_path> --scope <symbol_name>

不明な動作をデバッグする

# ステップ 1: ワークスペース全体でシンボル定義を見つける
lsp search "<symbol_name>"

# ステップ 2: 実装の詳細を確認
lsp definition <file_path> --scope <symbol_name>

# ステップ 3: すべての呼び出し元を追跡して呼び出しコンテキストを理解
lsp reference <file_path> --scope <symbol_name>

インターフェース実装を検索

# ステップ 1: インターフェース定義を見つける
lsp search "IUserService" --kinds interface

# ステップ 2: すべての実装を検索
lsp reference src/interfaces.py --scope IUserService --mode implementations

データ フロー を追跡

# ステップ 1: データが作成される場所を検索
lsp search UserDTO --kinds class

# ステップ 2: それが使用される場所を検索
lsp reference models.py --scope UserDTO

# ステップ 3: 変換を確認
lsp doc transform.py --scope map_to_dto

型階層を理解

# ステップ 1: クラス アウトラインを取得
lsp outline models.py

# ステップ 2: サブクラスを検索（ベースへの参照）
lsp reference models.py --scope BaseModel

# ステップ 3: 型定義を確認
lsp definition models.py --scope BaseModel --mode type_definition

パフォーマンス ヒント

# ファイル全体を読む代わりに outline を使用
lsp outline large_file.py  # より良い方法: read large_file.py

# ネストされた構造に対してシンボル パスを使用（行番号より正確）
lsp definition models.py --scope User.Profile.validate

# 大規模なコードベースの結果を制限
lsp search "User" --max-items 20

# ソースにナビゲートせずに API を理解するには doc を使用
lsp doc api.py --scope fetch_data  # 定義にジャンプせずにドキュメント/型を取得

# コマンドが失敗した場合は locate 文字列を確認
lsp locate main.py --scope 42 --find "<|>my_var"

ドメイン特有のガイド

特殊なシナリオについては、以下を参照してください:

• モノレポ: monorepo.md
• フロントエンド: bp_frontend.md
• バックエンド: bp_backend.md