lsp-code-analysis

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 を指定します（例：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> を使用して、対象がファイル内に存在するか確認し、そのコンテキストを表示してもかまいません。

# Verify location exists
lsp locate main.py --scope 42 --find "<|>process_data"

ページネーション

reference や search など、大量の結果が返される場合はページネーションを使用します。

• --pagination-id <ID>：一貫したページネーションに必要な、一意のセッション ID です。
• --max-items <N>：1 ページあたりの項目数です。
• --start-index <N>：オフセット（0 始まり）です。

例：

# Page 1
lsp search "User" --max-items 20 --pagination-id "task_123"

# Page 2
lsp search "User" --max-items 20 --start-index 20 --pagination-id "task_123"

ガイドライン：よく使うシンボルの結果を適切なサイズのチャンクで取得するには、一意の ID を指定してページネーションを使用します。同じ ID を使い、--start-index を増やしながら結果を確認してください。

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

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

# Get main symbols (classes, functions, methods)
lsp outline <file_path>

# Get all symbols including variables and parameters
lsp outline <file_path> --all

エージェントは、不要なコンテキスト消費を避けるため、ファイルを読む前に outline を使用することを推奨します。

定義：ソースへ移動

シンボルが定義されている場所へ移動します。

# Jump to where User.get_id is defined
lsp definition models.py --scope User.get_id

# Find where an imported variable comes from
lsp definition main.py --scope 42 --find "<|>config"

# Find declaration (e.g., header files, interface declarations)
lsp definition models.py --scope 25 --mode declaration --find "<|>provider"

# Find the class definition of a variable's type
lsp definition models.py --scope 30 --find "<|>user" --mode type_definition

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

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

# Find all places where logger is referenced
lsp reference main.py --scope MyClass.run --find "<|>logger"

# Find all concrete implementations of an interface/abstract class
lsp reference api.py --scope "IDataProvider" --mode implementations

# Get more surrounding code context for each reference
lsp reference app.py --scope 10 --find "<|>my_var" --context-lines 5

# Limit results for large codebases
lsp reference utils.py --find "<|>helper" --max-items 50 --start-index 0

Doc：ドキュメントを取得

ソースへ移動せずに、ドキュメントと型情報を取得します。

# Get docstring and type info for symbol at line 42
lsp doc main.py --scope 42

# Get API documentation for process_data function
lsp doc models.py --scope process_data

ドキュメントまたは型情報だけが必要な場合、エージェントは read より doc を優先することを推奨します。

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

場所が不明な場合に、ワークスペース全体からシンボルを検索します。

# Search by name (defaults to current directory)
lsp search "MyClassName"

# Search in specific project
lsp search "UserModel" --project /path/to/project

# Filter by symbol kind (can specify multiple times)
lsp search "init" --kinds function --kinds method

# Limit and paginate results for large codebases
lsp search "Config" --max-items 10
lsp search "User" --max-items 20 --start-index 0

結果をフィルタリングしてノイズを減らすため、エージェントは --kinds を使用することを推奨します。

Symbol：シンボルのコード全体を取得

指定した位置を含むシンボルのソースコード全体を取得します。

# Get complete code of the function/class at line 15
lsp symbol main.py --scope 15

# Get full UserClass implementation
lsp symbol utils.py --scope UserClass

# Get complete method implementation
lsp symbol models.py --scope User.validate

レスポンスには、シンボル名、種類（クラス／関数／メソッド）、範囲、ソースコード全体が含まれます。

エージェントは、ファイル全体に対してreadを使用するのではなく、対象のコードブロックを読み取るためにsymbolを使用することを推奨します。

リファクタリング操作

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

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

バックグラウンドマネージャーは自動的に起動します。手動での操作は任意です。

# List running servers
lsp server list

# Start server for a project
lsp server start <path>

# Stop server for a project
lsp server stop <path>

# Shutdown the background manager
lsp server shutdown

ベストプラクティス

一般的なワークフロー

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

新しいコードベースを調査する際の推奨手順：

# Step 1: Start with outline - Get file structure without reading implementation
lsp outline <file_path>

# Step 2: Inspect signatures - Use doc to understand API contracts
lsp doc <file_path> --scope <symbol_name>

# Step 3: Navigate dependencies - Follow definition chains
lsp definition <file_path> --scope <symbol_name>

# Step 4: Map usage - Find where code is called with reference
lsp reference <file_path> --scope <symbol_name>

不明な動作のデバッグ

# Step 1: Locate symbol definition workspace-wide
lsp search "<symbol_name>"

# Step 2: Verify implementation details
lsp definition <file_path> --scope <symbol_name>

# Step 3: Trace all callers to understand invocation context
lsp reference <file_path> --scope <symbol_name>

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

# Step 1: Locate interface definition
lsp search "IUserService" --kinds interface

# Step 2: Find all implementations
lsp reference src/interfaces.py --scope IUserService --mode implementations

データフローを追跡する

# Step 1: Find where data is created
lsp search UserDTO --kinds class

# Step 2: Find where it's used
lsp reference models.py --scope UserDTO

# Step 3: Check transformations
lsp doc transform.py --scope map_to_dto

型階層を理解する

# Step 1: Get class outline
lsp outline models.py

# Step 2: Find subclasses (references to base)
lsp reference models.py --scope BaseModel

# Step 3: Check type definitions
lsp definition models.py --scope BaseModel --mode type_definition

パフォーマンスのヒント

# Use outline instead of reading entire files
lsp outline large_file.py  # Better than: read large_file.py

# Use symbol paths for nested structures (more precise than line numbers)
lsp definition models.py --scope User.Profile.validate

# Limit results in large codebases
lsp search "User" --max-items 20

# Use doc to understand APIs without navigating to source
lsp doc api.py --scope fetch_data  # Get docs/types without jumping to definition

# Verify locate strings if commands fail
lsp locate main.py --scope 42 --find "<|>my_var"

分野別ガイド

専門的なシナリオについては、以下を参照してください。

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