はじめに
初めまして。Contreaという医療系スタートアップでエンジニアをしている河野と申します。
私は普段からClaude Codeを使いながら開発をしています。
AIを使いながらのVibe Codingはとても楽しく、開発がサクサク進むような快感がありました。しかし最近、使えば使うほど「AIが思ったように動いてくれない」とフラストレーションが溜まることが多くなりました。
特に、
1. 複雑な指示や、複数ファイルにまたがる修正をお願いすると、途中から見当違いな提案をしてくる
2. 抽象度が少し高いタスクをお願いすると、突然findコマンドを連発しはじめたり、全てのファイルを読み込むような、暴走モードに突入する
といったようなことを行うと途端に精度が悪くなったように感じます。
もちろん、プロンプトが拙いこともあり、私自身にも1%ほど非があるとは思います。
しかし、これらの現象はClaude CodeだけではなくCursor、Devin、ChatGPTを使った時も同じような問題に悩まされています。
何故、このような「思ったようにAIが動かない」問題が起こってしまうのでしょうか？
この記事では、「AIが思ったように動かなくなる原因」と、それを解決するアプローチとして最近話題の Serena MCP について解説していきます。
TL;DR
- 複雑な指示が通らないのは、LLMのコンテキスト制約が原因
- プロンプト内のキーワードを与えられると、それを手がかりに、リポジトリ全体を愚直に全探索する
- その結果、情報過多となり、LLMではコンテキストの処理ができなくなる
- Serena MCPは、LLMのコード理解を飛躍的に向上させるコンテキスト検索支援ツール
- プロジェクト全体をインデックス化し、「どこに何があるか」を構造的に把握させることで、ピンポイントで正確なコード修正が可能に
- 差分更新にも対応し、コードの最新状態を効率よく保つ
- 完全ローカルで動作するため、外部通信の心配もなくセキュア
コンテキスト枯渇問題
上記のような「徐々にポンコツになる問題」と「謎に全探索しようとする問題」はLLM、RAGに関連するコンテキストの制約が原因です。
- LLM（大規模言語モデル）は、一度に保持できる文脈の量（コンテキストウィンドウ）に上限があるため、指示やファイル数が増えると、重要な情報が「押し出され」てしまう。
- RAG（検索拡張生成）は、プロンプトに含まれるキーワードを基に検索を行うが、プロジェクト全体の中で「どの部分が重要か」の判断が難しく、関係の薄いファイルまで全て検索しようとする。
このような制約があるため、複雑な指示や広範囲の検索を行った際に、AIが「自分が何をしているのか」を見失ってしまうのです。
こうしたコンテキスト制約の根本課題に対して注目されているアプローチが、Serena MCPです。
Serena MCPとは？
Serena MCPとは、AIアシスタントに「コードの文脈を失わせずに理解させる」ためのツールです。
Serenaには大きく3つの特徴があります。
1. LSP（Language Server Protocol）を活用した構造認識
LSP（Language Server Protocol） とは、VS Code などのエディタが、コードの定義ジャンプやシンボル検索、リファレンス取得を行うための標準プロトコルです。
エディタはLSPを通じて「この関数はどこで定義されている？」「この変数を参照している箇所は？」と問い合わせ、Language Serverがその情報を返すことで、IDEのような支援機能が実現されています。
Serena はこのLSPを活用し、関数やクラスの定義・参照関係・プロジェクト全体の構造情報を取得し、コードベースの文脈を正確に把握します。
この構造情報をLLMに渡すことで、必要なファイル・関数・行番号をピンポイントで特定しながら修正提案ができるようになります。
2. セマンティック解析によるコード理解
そしてSerenaでは、LSPから得た構造情報を元に、プロジェクト全体を走査し、関数・クラス・依存関係といった意味的なつながり（セマンティクス）を解析し、検索インデックスとして保存します。
その結果、「UserService.getUserを呼んでいる箇所」や「AuthErrorを継承しているクラス」など、単純な文字列検索では見つけにくい意味的に関連するコードを瞬時に特定でき、リファクタリングや一括修正も安全かつ確実に行えます。
従来の LLM はコードを文字列としてしか扱えず、文脈を取りこぼしがちでしたが、Serenaによって構造化されたコンテキストが供給されることで、プロンプトの意図通りに正確な修正が可能になります。
3. ローカルで完結する、信頼性の高いセキュリティ
Serena MCPという名前がついているので、「外部のサーバーと通信するプロトコルなんじゃないの？」と疑問に思うかもしれません。
MCPは「LLMとアプリケーション間の通信を標準化するためのプロトコルであり、外部との通信規約のみではなく、ローカル運用も可能なモデル内部的な通信規約」です。
Serenaはデフォルト構成では外部との通信を行わない設定のため、情報流出を心配することなくセキュアな環境でAIの恩恵を受けることができます。
どんな人が使うべきか？
基本的に全員使ったほうが良いかなと思います。
新規プロジェクトでも作っていくことでインデックスが作られていくので利用価値がありますし、すでに開発するプロジェクトが存在する場合には真価を発揮します。
特に、以下のような人には絶大な効果を発揮します。
-
大規模・複雑なリポジトリを扱うエンジニア
コードベースが巨大で全体像を把握するのが困難なプロジェクトであるほど、Serenaの「セマンティック解析」が光り、全体像を掴みやすくなります。 -
他人の書いたコードを読む機会が多いエンジニア
1つ目と若干被りますが、新規プロジェクトへの参加時や、引き継ぎ、コードレビューの際に、関連コードを瞬時に見つけ出せるため、キャッチアップの時間を大幅に短縮できます。
Claude CodeとSerenaを連携させる
導入手順
1. パッケージ管理ツール uvのインストール
私はMacOSでbrewを利用しているのでそちらでインストールします。
brew install uv
2. MCPサーバーの登録
ワンライナーで、.mcp.jsonファイルを作成します。
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena-mcp-server --context ide-assistant --project $(pwd)
しかしワンライナーだと pwdの部分が自身のフォルダになってしまい、チームでのGitHub管理に適さないので、私は直接MCPファイルを作成します。
もしプロジェクト管理したい場合、直下に.mcp.jsonを作成し、下記のように記載すると全員が使いやすくなります。
{
"mcpServers": {
"serena": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/oraios/serena",
"serena",
"start-mcp-server",
"--context",
"ide-assistant",
"--project",
"."
],
"cwd": "."
}
}
}
3. インデックス作成
公式ドキュメントでは、特に大きなプロジェクトの場合、最初にindexを実行しておくと良いそうなので、やっておくと良さそうです。
参考：https://github.com/oraios/serena?tab=readme-ov-file#project-activation--indexing
uvx --from git+https://github.com/oraios/serena serena project index
4. Claude起動、 MCPサーバーがあるか確認、オンボーディング
通常のようにclaudeを実行し、MCPがあるのを確認します。
claude
起動後に/mcpコマンドを実行し、下記のように出力されればOK
/mcp
──────────────────────────────────────────────────────────╮
│ Manage MCP servers │
│ ❯ 1. serena ✔ connected · Enter to view details │
5. オンボーディング（必要であれば...）
必須ではありませんが、claudeコマンド実行後に下記のコマンドを実行すると、Serenaがプロジェクトをスキャンし、フォルダ構成や全体像を.serena/memoriesフォルダ配下に追加していきます。
/mcp__serena__initial_instructions
インデックスの自動更新について
一度プロジェクトのインデックスを作成した後は、手動での更新作業は一切不要です。
Serenaは起動している間、常にプロジェクト内のファイルの変更を監視しており（ファイルウォッチャー）、コードを編集してファイルを保存すると、Serenaは変更差分を自動検知し、変更があったファイルだけを再解析して、インデックスを差分更新していきます。
ただし起動している間なので、定期的にuvx --from git+https://github.com/oraios/serena serena project indexコマンドを実行してインデックスを更新しましょう。
ほとんどSerenaのGitHubリポジトリに記載されている内容なので、ぜひ読んでみてください。
まとめ
Serena MCPがなぜ注目されているのか、その仕組みやセキュリティについて書きました。
また、直近でも「コンテキストエンジニアリングがなぜ重要なのか」という記事が出てきており、エンジニアの中でコンテキスト関連の重要性がより注目されてきています。
Serenaは上記の記事でいうところの「書き出し」「選択」を効率よく実施してくれるツールなので、よりAIをうまく利用する障壁が減るのではないでしょうか。
特に複雑なプロジェクトで役立ち、ユビキタス言語の洗い出しやコード走査で真価を発揮するでしょう。
（ただ個人的には、本来はClaude CodeやCursorにあるべき機能なので、なんで実装されてないんだろう...と不思議な気持ちがあります）
また面白い技術があれば紹介したいと思います。
Contreaは現場に向き合い課題解決をするエンジニアを募集しています！
弊社コントレアはフルスタックエンジニアを採用しております。
現場訪問も行い、現場課題を見つけるエンジニアとしての楽しみがあるContreaでぜひ一緒に働きませんか？
インフォームドコンセント支援システム「MediOS」を開発するContreaのProductチームのブログです。 様々なバックグラウンドをもつメンバーが所属し、医療の未来を作る仕事をしております。
Discussion