serena

Serena：シンボルレベルのコード理解

Language Server Protocol（LSP）を利用した IDE のようなセマンティック分析により、シンボルレベルでコードをナビゲートおよび操作できます。

Serena の利用方法

Serena は、次のいずれか、または両方の方法で利用できます。

オプション 1：直接 MCP ツール（オーケストレーターで設定されている場合） 利用可能なツールを確認してください。

• find_symbol、find_referencing_symbols - シンボルの検索
• rename_symbol、replace_symbol_body - リファクタリング
• insert_after_symbol、insert_before_symbol - 正確な位置への挿入
• onboarding、activate_project - プロジェクトの理解
• write_memory、read_memory - コンテキストの保存
• その他、LSP を利用した 25 種類以上のツール

これらのツールが表示される場合は、直接使用してください。Serena の機能をすべて利用できます。

オプション 2：CLI コマンド（execute_command から常に利用可能） serena コマンドは、次のように実行できます。

execute_command("uvx --from git+https://github.com/oraios/serena serena <command>")

このスキルでは、CLI の使用パターンを中心に説明します。直接 MCP ツールを利用できる場合は、連携性に優れたそちらを優先してください。

目的

serena スキルでは、テキストベースの LLM をシンボルを認識するコードエージェントに変えるコーディングエージェント用ツールキット、Serena を利用できます。従来のテキスト検索（ripgrep）や構造検索（ast-grep）とは異なり、Serena は LSP との連携を通じてコードのセマンティクスを理解します。

主な機能：

1. シンボルの検出：30 以上の言語を対象に、クラス、関数、変数、型を名前で検索します
2. 参照の追跡：シンボルが参照または使用されているすべての場所を検出します
3. 正確な編集：特定のシンボル位置にコードを高精度で挿入します

Serena はテキストや構文レベルではなく、シンボルレベルで動作するため、コードの構造、スコープ、関係性を IDE のように理解できます。

このスキルを使用する場面

シンボルレベルでコードを理解する必要がある場合は、serena スキルを使用してください。

コードのナビゲーション：

• クラス、関数、変数の定義場所を探す
• シンボルが使用されているすべての場所（呼び出し箇所、インポート、参照）を見つける
• コードの依存関係と関連性を理解する
• 関数呼び出しを通じて実行フローを追跡する

コードの理解：

• 関数やクラスへの変更が与える影響を分析する
• 継承階層と型の関係を理解する
• デッドコード（参照されていないシンボル）を特定する
• コードベース全体にわたる API の使用パターンを把握する

コードのリファクタリング：

• すべての使用箇所を追跡しながらシンボルの名前を変更する
• 特定のクラスにメソッドやフィールドを追加する
• 特定の関数呼び出しの後にエラー処理を挿入する
• 非推奨になった関数のすべての呼び出し箇所を変更する

次の場合は file-search（ripgrep/ast-grep）より serena を選んでください：

• シンボルのセマンティクス（単なるテキストパターンではなく）を理解する必要がある
• ファイルやモジュールをまたいで参照を追跡したい
• コード構造に基づいた正確な挿入位置が必要である
• 複雑な複数ファイルのコードベースを扱っている

次の場合は、引き続き file-search を使用してください：

• テキストパターン、コメント、文字列を検索する
• TODO、セキュリティ上の問題、ドキュメントを探す
• より高速でシンプルなパターンマッチングが必要である
• シンボルレベルの精度が必要ない

言語サポート

Serena はセマンティック分析に LSP サーバーを使用します。一般的な言語の多くは、すぐに利用できます。

• Python（pyright、jedi）
• JavaScript/TypeScript（typescript-language-server）
• Rust（rust-analyzer）
• Go（gopls）
• Java（jdtls）
• C/C++（clangd）
• C#、Ruby、PHP、Kotlin、Swift、Scala、その他 15 以上の言語

LSP サーバーは、作業中の言語のシンボル情報を提供します。

主な操作

1. シンボルを検索する（find_symbol）

コードベース内でシンボルが定義されている場所を特定します。

**注：**以下の例では、すべて短縮形の serena <command> を使用しています。完全なコマンドは次のとおりです。

uvx --from git+https://github.com/oraios/serena serena <command>

# Find a class definition
execute_command("uvx --from git+https://github.com/oraios/serena serena find_symbol --name 'UserService' --type class")

# Find a function definition
execute_command("uvx --from git+https://github.com/oraios/serena serena find_symbol --name 'authenticate' --type function")

# Find a variable definition
execute_command("uvx --from git+https://github.com/oraios/serena serena find_symbol --name 'API_KEY' --type variable")

使用例：

• クラスを変更する前に、その定義を特定する
• 関数の実装場所を探す
• 定数の定義場所を把握する
• 型付き言語で型定義を追跡する

出力形式：

File: src/services/user_service.py
Line: 42
Symbol: UserService (class)
Context: class UserService(BaseService):

2. 参照箇所の検索（find_referencing_symbols）

シンボルが使用、インポート、または参照されているすべての場所を特定します。

# Find all usages of a class
execute_command("serena find_referencing_symbols --name 'UserService'")

# Find all call sites of a function
execute_command("serena find_referencing_symbols --name 'authenticate'")

# Find all reads/writes of a variable
execute_command("serena find_referencing_symbols --name 'API_KEY'")

ユースケース：

• リファクタリング前の影響分析
• 関数のすべての呼び出し箇所の検索
• モジュール間での API 使用状況の追跡
• 未使用シンボル（参照数ゼロ）の特定
• データフローと依存関係の把握

出力形式：

Found 12 references to 'authenticate':

1. src/api/routes.py:34
   authenticate(user_credentials)

2. src/middleware/auth.py:18
   from services import authenticate

3. tests/test_auth.py:56
   mock_authenticate = Mock(spec=authenticate)
...

3. コードの正確な挿入（insert_after_symbol）

シンボルの指定位置に、極めて正確にコードを挿入します。

# Add a method to a class
execute_command("""serena insert_after_symbol --name 'UserService' --type class --code '
    def get_user_by_email(self, email: str) -> Optional[User]:
        return self.db.query(User).filter_by(email=email).first()
'""")

# Insert error handling after a function call
execute_command("""serena insert_after_symbol --name 'database_query' --code '
    if result is None:
        raise DatabaseError("Query returned no results")
'""")

# Add a field to a dataclass
execute_command("""serena insert_after_symbol --name 'User' --type class --code '
    email_verified: bool = False
'""")

ユースケース：

• 既存のクラスへのメソッドの追加
• バリデーションやエラーハンドリングの挿入
• データ構造へのフィールドの追加
• ロギングや監視コードの挿入
• 不足している機能の実装

安全機能：

• インデントとコードの書式を維持します
• 構文の妥当性を保ちます
• スコープ内の正しい位置にコードを配置します
• 既存のコード構造を維持します

ワークフローパターン

パターン 1：安全なリファクタリング

関数のシグネチャや動作を変更する場合：

# Step 1: Find the function definition
serena find_symbol --name 'process_payment' --type function

# Step 2: Find all call sites
serena find_referencing_symbols --name 'process_payment'

# Step 3: Analyze impact (review output)
# [Review all usage locations to understand impact]

# Step 4: Make changes with confidence
# [Update function and all call sites based on findings]

パターン 2：機能の追加

新しいメソッドでクラスを拡張する場合：

# Step 1: Locate the class
serena find_symbol --name 'PaymentProcessor' --type class

# Step 2: Verify no conflicts
serena find_symbol --name 'process_refund' --type function

# Step 3: Insert new method
serena insert_after_symbol --name 'PaymentProcessor' --type class --code '
    def process_refund(self, payment_id: str, amount: float) -> bool:
        # Implementation here
        pass
'

パターン 3：依存関係の把握

コード間の関係を分析する場合：

# Step 1: Find class definition
serena find_symbol --name 'DatabaseManager' --type class

# Step 2: Find all usages
serena find_referencing_symbols --name 'DatabaseManager'

# Step 3: For each usage, find what symbols use that code
# [Repeat reference tracking to build dependency graph]

パターン 4：デッドコードの検出

未使用のコードを特定する場合：

# Step 1: Find symbol definition
serena find_symbol --name 'legacy_auth_handler'

# Step 2: Check references
serena find_referencing_symbols --name 'legacy_auth_handler'

# Step 3: If zero references (except definition), mark for removal
# [If output shows only the definition, symbol is unused]

file-search との連携

Serena と file-search（ripgrep/ast-grep）は相互に補完するツールです。組み合わせて使用します：

ツールを組み合わせる場面

まず ripgrep を使い、その後 serena を使用：

# 1. Find potential matches with ripgrep (fast, broad)
rg "authenticate" --type py

# 2. Narrow to specific symbol with serena (precise)
serena find_symbol --name 'authenticate' --type function
serena find_referencing_symbols --name 'authenticate'

まず serena を使い、その後 ripgrep を使用：

# 1. Find symbol definition with serena
serena find_symbol --name 'UserService'

# 2. Search for related patterns with ripgrep
rg "UserService\(" --type py  # Find direct instantiations
rg "class.*UserService" --type py  # Find subclasses

相互補完する強み

タスク	最適なツール	理由
文字列リテラルの検索	ripgrep	テキストベースで高速
TODO やコメントの検索	ripgrep	テキストベース
シンボル定義の検索	serena	シンボルを認識
すべての参照箇所の検索	serena	意味を理解
コードパターンの検索	ast-grep	構文を認識
シンボル位置への挿入	serena	正確な位置決め
複数言語にまたがる検索	ripgrep	言語に依存しない
スコープの把握	serena	LSP の意味情報

ベストプラクティス

1. まずシンボルを特定する

必ず最初にシンボル定義を探します：

# GOOD: Find definition, then references
serena find_symbol --name 'MyClass'
serena find_referencing_symbols --name 'MyClass'

# AVOID: Searching for references without confirming definition exists

2. 具体的なシンボルタイプを指定する

可能な場合は --type を使って検索対象を絞り込みます：

# GOOD: Specific type reduces ambiguity
serena find_symbol --name 'User' --type class

# LESS PRECISE: May match User function, User variable, etc.
serena find_symbol --name 'User'

3. 挿入前に確認する

コードを挿入する前に、必ずシンボルを探します：

# GOOD: Verify target exists first
serena find_symbol --name 'PaymentService' --type class
# [Review output to confirm correct class]
serena insert_after_symbol --name 'PaymentService' --code '...'

# RISKY: Inserting without verification
serena insert_after_symbol --name 'PaymentService' --code '...'

4. 参照数を確認する

影響分析のため、参照の出力を確認します：

# Find references and assess impact
serena find_referencing_symbols --name 'deprecated_function'
# If 50+ references, plan careful migration
# If 0 references, safe to remove

5. git diff と組み合わせる

挿入後に変更を確認します：

serena insert_after_symbol --name 'MyClass' --code '...'
git diff  # Review actual changes before committing

対応言語

Serena は LSP 統合により、30 以上の言語をサポートしています：

ティア 1（十分にテスト済み）：

• Python、JavaScript、TypeScript、Rust、Go、Java、C/C++

ティア 2（コミュニティによるテスト済み）：

• C#、Ruby、PHP、Kotlin、Swift、Scala

ティア 3（実験的）：

• Haskell、Elixir、Clojure、Erlang、Julia、R など

対応言語の完全な一覧とセットアップ手順については、Serena の言語サポートに関するドキュメントを参照してください。

制限事項

Serena を使用しない場面

1. テキストやコメントの検索：代わりに ripgrep を使用します

   # WRONG TOOL: Serena doesn't search comments
   serena find_symbol --name "TODO"
   
   # RIGHT TOOL: Use ripgrep for text
   rg "TODO"
   

2. 生成コード：LSP が自動生成ファイルをインデックス化しない場合があります

   • ビルド成果物や生成コードには ripgrep を使用します

3. 非常に大規模なコードベース：シンボルのインデックス化に時間がかかる場合があります

   • 最初の広範な検索には ripgrep を使用します
   • その後の正確な検索には serena を使用します

4. 型のない動的言語：意味情報が限られます

   • 型ヒントのない Python では、精度が低下します
   • TypeScript を使用していない JavaScript では、保証が少なくなります

既知のエッジケース

• 曖昧なシンボル：同じ名前のシンボルが複数ある場合、手動での識別が必要になることがあります
• マクロ生成コード：C/C++ のマクロが LSP の処理に影響する場合があります
• 循環依存：参照追跡の精度に影響する場合があります
• 不完全なプロジェクト：依存関係が欠落していると、LSP の有効性が低下する場合があります

パフォーマンスに関する考慮事項

トークン効率

Serena は、トークン効率の高いコードナビゲーションを実現するよう設計されています：

# Traditional approach (inefficient)
execute_command("cat entire_file.py")  # 1000+ tokens
# [Search for symbol manually in output]

# Serena approach (efficient)
serena find_symbol --name 'MyClass'  # 50 tokens
# [Get precise location immediately]

速度特性

• シンボル検索：ほぼ瞬時（LSP でインデックス化）
• 参照検索：高速（インデックス化により O(log n)）
• コード挿入：瞬時（ファイルを直接変更）

他の選択肢との比較：

• Ripgrep：テキスト検索ではより高速（セマンティックな理解はありません）
• AST-grep：同程度の速度（構文とセマンティクスの違い）
• Serena：初回起動は遅め（LSP のインデックス化が必要）ですが、精度の高いクエリはより高速です

トラブルシューティング

シンボルが見つからない

find_symbol が結果を返さない場合：

1. シンボルが存在することを確認：ripgrep を使用して確認します

   rg "class MyClass" --type py
   

2. 言語サーバーを確認：その言語の LSP が設定されていることを確認します

   serena status  # Check LSP server status
   

3. 大文字と小文字の違いを試す：シンボル名では大文字と小文字が区別されます

   serena find_symbol --name 'myclass'  # Try different cases
   

4. インデックスを再構築：LSP にインデックスを強制的に再作成させます

   serena reindex  # Rebuild symbol index
   

参照が多すぎる

find_referencing_symbols が数百件の結果を返す場合：

1. まずファイル検索を使用：ripgrep で範囲を絞り込みます

   rg "MyClass" src/services/  # Limit to specific directory
   serena find_referencing_symbols --name 'MyClass' --path src/services/
   

2. 参照タイプでフィルタリング：特定の使用パターンに絞り込みます

   # Look for imports only
   rg "from .* import.*MyClass" --type py
   

3. 最近の変更を優先：まず git の履歴を確認します

   git log --all -p -S 'MyClass' --since="1 week ago"
   

挿入に失敗する

insert_after_symbol が失敗する場合：

1. シンボルが存在することを確認：まずシンボルを見つけます
2. 構文を確認：挿入するコードが有効であることを確認します
3. インデントを確認：周囲のコードスタイルに合わせます
4. 段階的にテスト：まず小さな変更を挿入します

リソース

• Serena GitHub
• Serena ドキュメント
• LSP 仕様
• Solid-LSP（Serena の基盤）