Serenaとは？ AIエージェントを劇的に強化するコーディングツールキットの全貌

Posted at 2025-10-24

はじめに

AIコーディングエージェント（Claude Code、Cursor、GitHub Copilotなど）を使っていて、こんな課題に直面したことはありませんか？

最近性能が劣化してきた: コードにバグが多くなり、修正も繰り返し行うが、最終的には直っていない・・
コンテキストがすぐに埋まる: 大きなファイルを読み込むと、すぐにトークン上限に達してしまう・・
精度が低い: grepやテキスト置換で意図しない箇所まで変更されてしまう・・
プロジェクト知識が失われる: セッションをまたぐと、前回理解した内容を忘れてしまう・・

Serenaは、こういった課題を根本から解決する、オープンソースのコーディングエージェントツールキットです。

本記事では、SerenaがどのようにAIエージェントを強化するのか、その仕組みとアーキテクチャを詳しく解説します。

Serenaとは何か

一言で言うと

Serenaは、LLM（大規模言語モデル）に「IDEのような高度なコード理解・編集機能」を与えるツールキットです。

コア価値提案

従来のエージェント:
❌ ファイル全体を読み込む
❌ grepやテキスト置換で操作
❌ 大量のトークンを消費
❌ セッションごとに知識がリセット

Serena:
✅ シンボルレベルでピンポイント操作
✅ LSPによる意味解析
✅ トークン効率96%向上
✅ プロジェクト知識を永続化
✅ 20以上の言語に対応

主な特徴

1. IDE相当の機能を提供

Serenaは、Language Server Protocol (LSP) を活用することで、IDEのようなセマンティックなコード理解を実現します。

シンボル検索: 関数名、クラス名で正確に検索
参照追跡: どこでそのコードが使われているか完全把握
定義ジャンプ: シンボルの定義箇所に即座にアクセス

2. LLM・フレームワーク非依存

特定のLLMやフレームワークに縛られず、あらゆる環境で使えます。

対応クライアント:

Claude Desktop、Claude Code
VSCode、Cursor、Windsurf
Cline、Roo Code
OpenWebUI、Jan、Agno
Codex、Gemini-CLI、Qwen3-Coder

3. 20以上のプログラミング言語に対応

Python          TypeScript/JavaScript   PHP
Go              Rust                    C/C++
C#              Ruby                    Swift
Kotlin          Java                    Clojure
Dart            Bash                    Lua
Nix             Elixir                  Erlang
Zig             AL (Dynamics 365)       R

すべての言語で同じツール・同じ操作が使えます。

4. 完全無料・オープンソース

MITライセンス
GitHub: https://github.com/oraios/serena
コミュニティによる活発な開発

Serenaの3つの主要な利点

Serenaを使うことで得られる利点を、3つの観点から詳しく解説します。

1. コンテキストの大幅な節約（トークン効率）💰

問題: 従来のエージェントは、ファイル全体を読み込むため、大量のトークンを消費します。

解決: Serenaは、シンボルレベルのピンポイント操作により、必要な部分だけを取得します。

具体例：トークン削減の効果

ケース: 10,000行のPythonファイルで特定のメソッドを編集したい

従来の方法:

1. ファイル全体を読み込む → 約15,000トークン
2. 該当メソッドを探す
3. 編集

Serenaの方法:

1. get_symbols_overview でシンボル一覧取得 → 約500トークン
2. find_symbol で目的のメソッドだけ取得 → 約100トークン
3. 編集

合計: 約600トークン

節約率: 約96% (600トークン vs 15,000トークン)

仕組み：シンボルレベル操作

従来のアプローチ:

# ファイル全体を読む
content = read_file("src/main.py")  # 15,000トークン

# テキスト検索
match = grep("def calculate", content)

Serenaのアプローチ:

# シンボル検索（言語サーバー経由）
find_symbol(
    name_path="/Calculator/calculate",  # クラス名/メソッド名
    include_kinds=[SymbolKind.Method]
)
# → そのメソッドの定義だけを取得（100トークン）
# → 型情報、ドキュメント、参照関係も含む

キャッシング戦略による高速化

Serenaは、シンボル情報を積極的にキャッシュします。

キャッシュの動作:

ファイルのMD5ハッシュを計算
ファイルが変更されていなければ、言語サーバーに問い合わせず即座に結果を返す
キャッシュは .serena/cache/ に永続化（pickle形式）

パフォーマンス指標:

操作	初回（キャッシュなし）	2回目以降（キャッシュあり）
プロジェクトアクティベーション	5-10秒	1-2秒
シンボル検索（単一ファイル）	500ms-1秒	50-100ms
シンボル検索（プロジェクト全体）	3-5秒	200-500ms
参照検索	1-3秒	500ms-1秒

実世界での効果

コミュニティからの評価:

Most users report that Serena has strong positive effects on the results of their coding agents. Serena is often described to be a game changer, providing an enormous productivity boost.

2. AIエージェントの精度向上🎯

問題: テキストベースの検索や置換は、意図しない箇所も変更してしまうリスクがあります。

解決: Serenaは、Language Server Protocol (LSP) による意味理解で、正確な操作を実現します。

Language Server Protocol (LSP) とは

LSPは、IDEがコードを理解するために使う標準プロトコルです。Serenaは、このLSPを活用して、セマンティックなコード理解を実現します。

主要なLSP機能:

textDocument/documentSymbol: ファイル内のシンボル一覧取得
textDocument/definition: シンボル定義へのジャンプ
textDocument/references: シンボル参照検索
textDocument/hover: シンボル情報表示

テキストベース vs シンボルベース

テキストベース検索の限界:

# grep や rg での検索
result = grep("def calculate", "*.py")
# → calculate_tax(), calculate_total(), calculate_discount()
#    すべてマッチしてノイズが多い

Serenaのシンボルベース検索:

# 言語サーバーを使った意味解析
find_symbol(
    name_path="/Calculator/calculate",
    include_kinds=[SymbolKind.Method]
)
# → Calculator クラスの calculate メソッドだけを正確に取得
# → 型情報、ドキュメント、参照関係も含む

名前パスマッチングによる精密な検索

Serenaの名前パス（name_path）は、柔軟かつ正確な検索を可能にします。

パターン例:

"method"           → 任意の階層の method にマッチ
                     ✓ method, class/method, class/nested/method

"class/method"     → class を親に持つ method にマッチ
                     ✓ class/method, nested/class/method
                     ✗ other_class/method

"/class/method"    → 絶対パス（トップレベルのみ）
                     ✓ class/method
                     ✗ nested/class/method

参照検索による影響範囲の正確な把握

find_referencing_symbols ツールは、言語サーバーの静的解析を使って、そのシンボルがどこで使われているか完全に把握します。

例:

# "authenticate" 関数がどこで使われているか検索
find_referencing_symbols(
    name_path="/authenticate",
    relative_path="src/auth.py"
)
# → すべての呼び出し箇所をファイル名・行番号付きで取得
# → 変更の影響範囲を正確に把握

これにより、リファクタリング時に「どこに影響があるか」を事前に完全把握できます。

失敗から学んだ教訓：シンボルベースへの転換

Serenaの開発過程で、重要な教訓がありました。

Editing Based on Line Numbers

Not only are LLMs notoriously bad in counting, but also the line numbers change after edit operations, and LLMs are also often too dumb to understand that they should update the line numbers information they had received before. We pivoted to string-matching and symbol-name based editing.

(lessons_learned.md より)

行番号ベースの編集が失敗した理由:

LLMは行番号のカウントが苦手
編集後に行番号がずれるが、LLMがそれを理解できない

シンボル名ベースの編集への転換 = 精度が飛躍的に向上

編集の精度：インデント保持とシンボル単位の置換

従来の文字列置換:

# 危険：意図しない箇所も置換される可能性
old_code.replace("def foo():", "def bar():")

Serenaの編集:

replace_symbol_body(
    name_path="/MyClass/foo",
    relative_path="src/main.py",
    new_body="def foo(self, x: int) -> str:\n    return str(x)"
)
# ✓ MyClass の foo メソッドだけを置換
# ✓ 正しいインデントを自動計算
# ✓ 言語サーバーに変更を通知（didChange）

精密な編集操作の流れ:

シンボルの位置を言語サーバーから取得
行番号とインデントを解析
適切なインデントで新しいコードを挿入/置換
言語サーバーに変更を通知（textDocument/didChange）

20以上の言語に対応した統一インターフェース

Serenaは、すべての言語サーバーを統一インターフェースで抽象化しています。

SolidLanguageServer (Abstract Base)
├── PythonLanguageServer (Pyright)
├── TypeScriptLanguageServer (typescript-language-server)
├── RustLanguageServer (rust-analyzer)
├── GoLanguageServer (gopls)
├── JavaLanguageServer (eclipse.jdt.ls)
├── PHPLanguageServer (Intelephense)
└── ... (他16言語)

すべての言語で同じツール・同じ操作が使える = 一貫した高精度な編集が可能

3. プロジェクト知識の永続化（メモリシステム）🧠

問題: セッションをまたぐと、前回理解したプロジェクト構造や規約を忘れてしまいます。

解決: Serenaは、Markdown形式の人間にも読めるメモリシステムで、プロジェクト知識を永続化します。

メモリシステムの仕組み

Serenaは、プロジェクト固有の知識を .serena/memories/ ディレクトリにMarkdown形式で保存します。

メモリの保存先:

project_root/
└── .serena/
    └── memories/
        ├── project_structure.md      # プロジェクト構造
        ├── how_to_test.md            # テスト実行方法
        ├── how_to_build.md           # ビルド方法
        ├── architecture.md           # アーキテクチャ概要
        ├── coding_conventions.md     # コーディング規約
        └── task_progress.md          # タスク進捗（継続作業用）

メモリの特徴:

人間にも読める: Markdown形式なので、直接編集も可能
プロジェクト固有: 各プロジェクトごとに独立して保存
セッションをまたぐ: 新しいセッションでも過去の知識を活用
LLMが自動管理: 読み書きを自動で行う

オンボーディングプロセスによる自動理解

Serenaは、プロジェクトを初めて扱う際に、オンボーディングプロセスを実行します。

オンボーディングフロー:

1. プロジェクト構造の分析
   ↓
2. 主要ファイル・ディレクトリの特定
   ↓
3. ビルド・テスト方法の推定
   ↓
4. アーキテクチャ概要の生成
   ↓
5. メモリファイルへの保存
   ↓
6. オンボーディング完了フラグ設定

詳細なフロー:

1. onboarding ツール呼び出し（自動 or 手動）
   ↓
2. プロジェクト構造分析
   ├─ ディレクトリツリー取得
   ├─ 重要ファイル特定（README, package.json等）
   └─ ソースファイル数・種類カウント
   ↓
3. 重要ファイル読み取り
   ├─ README.md
   ├─ package.json / requirements.txt / Cargo.toml
   ├─ .gitignore
   └─ 主要設定ファイル
   ↓
4. エントリーポイント推定
   ├─ main.py, index.ts, main.rs等
   └─ シンボル概要取得
   ↓
5. テスト方法推定
   ├─ テストディレクトリ検出
   ├─ テストフレームワーク特定（pytest, jest等）
   └─ テストコマンド推定
   ↓
6. ビルド方法推定
   ├─ ビルドツール特定（cargo, npm, gradle等）
   └─ ビルドコマンド推定
   ↓
7. アーキテクチャ理解
   ├─ 主要モジュール/パッケージ特定
   ├─ 依存関係分析
   └─ デザインパターン推定
   ↓
8. メモリ作成
   ├─ project_structure.md
   ├─ how_to_test.md
   ├─ how_to_build.md
   ├─ architecture.md
   └─ key_symbols.md

セッションをまたいだ知識の活用

シナリオ：長期的なプロジェクト作業

Day 1:

User: "このプロジェクトの構造を教えて"
Agent: オンボーディングを実行
       → architecture.md, project_structure.md を作成

Day 2 (新しいセッション):

User: "認証機能を追加して"
Agent: list_memories で利用可能なメモリを確認
       → architecture.md を読み込み
       → 既存の構造を理解した上で実装

推奨される使い方:

Whenever Serena starts working on a project, the list of memories is provided, and the agent can decide to read them. We found that memories can significantly improve the user experience with Serena.

コンテキスト枯渇時の継続性

長いタスクでコンテキストが一杯になった場合の対処法:

1. prepare_for_new_conversation ツールを実行
   → 現在の進捗状況をサマリ化

2. write_memory で "task_progress.md" に保存
   内容:
   - 完了した作業
   - 現在の状態
   - 次にやるべきこと
   - 重要な決定事項

3. 新しいセッションを開始

4. read_memory("task_progress.md") で前回の状態を復元

5. 作業を継続

利点:

トークン制限を回避
文脈を失わずに作業継続
複数日にわたる作業も可能
サマリー化による情報損失を最小限に

メモリの実際の活用例

# .serena/memories/api_design_principles.md

## API設計原則

このプロジェクトでは以下の原則に従ってAPIを設計：

1. RESTful な URL 構造
2. すべてのエンドポイントは `/api/v1/` プレフィックス
3. 認証は JWT トークンを使用
4. エラーレスポンスは RFC 7807 形式

## 新規エンドポイント追加手順

1. `src/api/routes/` に新しいルートファイルを作成
2. `src/api/__init__.py` にルートを登録
3. `test/api/` にテストを追加
4. ドキュメントを `docs/api/` に追加

## 既存のエンドポイント

- `/api/v1/users` - ユーザー管理
- `/api/v1/auth` - 認証・認可
- `/api/v1/products` - 商品管理

→ この知識があれば、LLMは一貫性のあるコードを生成できる

3つの利点の相乗効果

ここまで見てきた3つの利点は、単独でも強力ですが、組み合わさることで真価を発揮します。

大規模プロジェクトでの効率的な作業

コンテキスト節約 × 精度向上 × 知識の永続化
= 大規模コードベースでも迷わず正確に作業

具体例:

知識の永続化: architecture.mdからプロジェクト構造を理解
精度向上: find_symbolで目的のクラスを正確に特定
コンテキスト節約: 該当メソッドだけを取得（全文不要）
編集実行

トークン制限への対処

各操作でトークン最小化 + 無駄な試行錯誤削減 + メモリで文脈保存
= 長時間作業でもコンテキスト枯渇しない

長期的なプロジェクトでの一貫性

毎回ファイル全体を読まない + 意図した変更だけ実施 + 規約を記憶
= 一貫性のある高品質なコード生成

人間の介入を最小限に自律的に作業

効率的な情報収集 + 高い成功率 + 過去の学習活用
= 自律的かつ正確な作業

Serenaのアーキテクチャ

ここからは、Serenaがどのように設計されているか、技術的な側面を解説します。

システム全体像

デュアルレイヤー設計

Serenaは、2つの主要レイヤーに分かれています。

Application Layer (Serena Agent):

LLMからのリクエストを受け取り、適切なツールを実行
プロジェクト固有の設定や状態を管理
メモリシステムで知識を永続化

Infrastructure Layer (SolidLSP):

複数の言語サーバーを統一インターフェースで扱う
シンボル情報を積極的にキャッシュして高速化
言語サーバーのライフサイクルを管理

レイヤー構造の詳細

Serenaは、6つのレイヤーで構成されています。

Layer 1: クライアントインターフェース層

責務: LLMクライアントとの通信

対応クライアント:

Claude Desktop, Claude Code
VSCode, Cursor, Windsurf
Cline, Roo Code
OpenWebUI, Jan, Agno
Codex, Gemini-CLI, Qwen3-Coder

通信プロトコル:

MCP (Model Context Protocol)
OpenAPI

Layer 2: Serena MCP Server層

責務: リクエストのルーティングとバリデーション

リクエストのルーティング
パラメータバリデーション
タイムアウト制御
ロギングとダッシュボード機能

Layer 3: SerenaAgent - コアオーケストレーション層

責務: システム全体の中核となるオーケストレーター

主要な機能:

プロジェクトのアクティベーションと管理
ツールレジストリとディスパッチ
コンテキスト・モード管理
メモリ管理
言語サーバーのライフサイクル管理

Layer 4: Tool実行層

責務: 各種操作の実装

ツールカテゴリ:

シンボルツール: find_symbol, find_referencing_symbols, get_symbols_overview
ファイルツール: read_file, write_file, search_for_pattern
コマンドツール: execute_shell_command
メモリツール: write_memory, read_memory, list_memories
設定ツール: activate_project, switch_modes
ワークフローツール: onboarding, prepare_for_new_conversation

Layer 5: SolidLSP層（言語サーバー抽象化）

責務: 言語サーバーとの通信とキャッシング

主要機能:

言語サーバーとの通信
シンボル情報のキャッシング
ドキュメント同期管理
エラーハンドリングと自動リトライ

Layer 6: 言語サーバープロセス層

責務: 各言語専用の言語サーバー実行

言語サーバー階層:

PythonLanguageServer (Pyright)
TypeScriptLanguageServer (typescript-language-server)
RustLanguageServer (rust-analyzer)
GoLanguageServer (gopls)
JavaLanguageServer (eclipse.jdt.ls)
PHPLanguageServer (Intelephense)
... (他16言語)

主要ツールの解説

Serenaは、27個のデフォルト有効ツールと9個のオプションツールを提供しています。

シンボルツール

find_symbol: シンボル検索

特定のシンボル（関数、クラス、メソッドなど）を検索します。

find_symbol(
    name_path="/MyClass/myMethod",  # シンボルパス
    depth=1,                         # 子要素の深さ
    include_body=True,               # ボディを含む
    include_kinds=[5, 6]             # クラス、メソッドのみ
)

シンボルカインド（LSP標準）:

5=class, 6=method, 12=function, 13=variable,
14=constant, 10=enum, 11=interface

find_referencing_symbols: 参照検索

シンボルがどこで使われているかを検索します。

find_referencing_symbols(
    name_path="/authenticate",
    relative_path="src/auth.py"
)
# → すべての呼び出し箇所をファイル名・行番号付きで取得

get_symbols_overview: シンボル一覧

ファイル内の全シンボルの概要を取得します。

get_symbols_overview(relative_path="src/main.py")
# → クラス、関数、変数などの一覧を取得

replace_symbol_body: シンボル置換

シンボルの定義を置換します。

replace_symbol_body(
    name_path="/MyClass/foo",
    relative_path="src/main.py",
    new_body="def foo(self, x: int) -> str:\n    return str(x)"
)
# ✓ MyClass の foo メソッドだけを置換
# ✓ 正しいインデントを自動計算

insert_after_symbol / insert_before_symbol: シンボル挿入

シンボルの前後にコードを挿入します。

insert_after_symbol(
    name_path="/MyClass",
    relative_path="src/main.py",
    content="    def new_method(self):\n        pass"
)

ファイルツール

read_file: ファイル読み取り

read_file(relative_path="src/main.py", max_lines=100)

create_text_file: ファイル作成

create_text_file(
    relative_path="src/new.py",
    content="def hello():\n    print('Hello')"
)

search_for_pattern: 正規表現検索

search_for_pattern(
    pattern=r"def\s+\w+",
    include_glob="**/*.py",
    context_lines=2
)

メモリツール

write_memory: メモリ保存

write_memory(
    memory_name="api_conventions.md",
    content="# API設計原則\n..."
)

read_memory: メモリ読み取り

read_memory(memory_file_name="api_conventions.md")

list_memories: メモリ一覧

list_memories()
# → ["architecture.md", "how_to_test.md", ...]

ワークフローツール

onboarding: プロジェクトオンボーディング

onboarding()
# 自動でプロジェクトを分析してメモリ作成

prepare_for_new_conversation: 新規会話準備

prepare_for_new_conversation()
# 進捗サマリーを生成

典型的な実行フロー

実際に「クラスFooのメソッドbarを見つけて編集する」というタスクを例に、Serenaの動作を見てみましょう。

このフローで重要なのは、キャッシュによる高速化と言語サーバーによる正確な位置特定です。

まとめ

Serenaの主要な強み

セマンティックコード理解: シンボルレベルでのコード操作
LLM・フレームワーク非依存: どんな環境でも利用可能
トークン効率: 必要な部分だけを読み取り、コスト削減（96%削減）
20+言語対応: 幅広いプロジェクトで使用可能
柔軟な統合: MCP、OpenAPI、ライブラリとして利用可能
オープンソース: 完全無料、カスタマイズ自由

推奨ユースケース

✅ 大規模コードベースの探索

シンボルベース検索で効率的にナビゲート

✅ 精密なコード編集

インデント保持、シンボル単位の正確な操作

✅ プロジェクトオンボーディング

自動的な理解とドキュメント化

✅ コスト削減

トークン効率の向上により API コスト削減

✅ 長期的なプロジェクト作業

メモリシステムで文脈を保持

コミュニティからの評価

Serena is often described to be a game changer, providing an enormous productivity boost.

始め方

# Claude Desktop での設定例
# ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/oraios/serena",
        "serena", "start-mcp-server"
      ]
    }
  }
}

詳細は公式ドキュメントを参照してください：

GitHub: https://github.com/oraios/serena
ドキュメント: README.md, ARCHITECTURE.md

おわりに

Serenaは、AIコーディングエージェントの3つの根本的な課題を解決します：

コンテキスト節約: 96%のトークン削減
精度向上: LSPによる意味理解と正確な編集
知識の永続化: メモリシステムでセッションをまたいだ作業

これらが組み合わさることで、大規模プロジェクトでも迷わず、正確に、効率的に作業できるAIエージェントが実現します。

あなたのコーディングエージェントにSerenaを追加して、生産性の飛躍的な向上を体験してみてください！

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up