Latest issue 29 10月 2025

Serena MCPツールを使用したカスタムPlanサブエージェント

💡

追記: 2.0.30にて「Fixed MCP tools not being available to sub-agents」としてこの非互換が解消されて現在はPlanサブエージェントを上書きしなくても問題ありません。内部アーキテクチャの紹介記事としてお楽しみください。

はじめに

Claude Code v2.0.28のアップデートによりPlan機能がサブエージェント化されました。Plan生成時のコンテキストが切り出され、メインコンテキストの削減に繋がるのが主な利点ですが、この影響でPlanモード実行時に利用されるツールがビルトインツールのみに制限され、MCPサーバーから提供されるツール（Serenaツールを含む）が使用できなくなりました。

Serenaユーザーから「ツールが使われなくなった」という報告を受けた著者はこの問題を特定し、Planエージェントを上書きすることでSerenaツールをサポートする方法を試みました。その結果、うまく動作したので知見を共有します。

💡

注意: これは公式にサポートされている方法ではないため、将来のアップデートで動作しなくなる可能性があります。Claude Codeの柔軟なプラグイン機構のおかげで、さまざまなカスタマイズが可能で面白いですね。

この記事では、Serena MCPサーバーのツールを使用したカスタムPlanサブエージェントの使い方を説明します。

概要

このカスタムPlanサブエージェントは、Claude Codeの組み込みPlanサブエージェントをSerena MCPツールで拡張したものです。デフォルトのツール（Glob、Grep、FileRead）をSerena MCPサーバーの高度なコードベース探索ツールに置き換え、より強力なシンボル検索、パターンマッチング、コードナビゲーション機能を提供します。

前提条件

Serena MCPサーバーが設定・接続されていること
/mcpコマンドでSerenaが利用可能であることを確認してください

Serenaについては以下の記事で確認してください

Serena MCPはClaude Codeを救うのか？

「Claude Codeがアホになる問題」が勃発している最中、SerenaというMCPサーバーが「Claude Codeのコンテキスト消費を削減し、応答を改善する」という評価でユーザーたちの間で注目されています。筆者も実際にSerenaを使ってみたところ、確かにコンテキスト効率の改善（入出力トークンの減少を指します）を実感できました。詳しく調べてみると、このツールは非常にユニークな発想で設計されており、一過性の流行として消費されるには惜しいと感じました。そこで、本記事では、この機能の背景にある技術的な仕組みを詳しく解説したいと思います。実際の検証も交えながら、Serenaのアーキテクチャとその効果を分析していきます。現在のコーディングエージェントが抱える課題現在のコーディングエージェントの多くは、コードを単なるテキストファイルとして扱って逐次的な処理をしています。この根本的なアプローチが、制約を生み出しています。大規模なプロジェクトで作業する際、エージェントは必要な情報を見つけるために膨大なテキストを読み込まなければなりません。関数の定義を探すだけでも、リポジトリ

laisolaiso

インストール方法

サブエージェントの設定をファイルで保存するパスが必要です。サブエージェントの使い方は以下にあります。

テスト（推奨）

プロジェクトディレクトリ内でテストする場合：

mkdir -p .claude/agents
cp Plan.md .claude/agents/Plan.md

グローバル設定

すべてのプロジェクトで使用する場合：

mkdir -p ~/.claude/agents
cp Plan.md ~/.claude/agents/Plan.md

Plan.mdファイルの内容

以下の内容でPlan.mdファイルを作成してください：

---  
name: Plan  
description: Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns, search code for keywords, or answer questions about the codebase.  
tools: mcp__serena__find_file, mcp__serena__search_for_pattern, mcp__serena__find_symbol, mcp__serena__get_symbols_overview, mcp__serena__find_referencing_symbols, mcp__serena__list_dir, Bash  
model: sonnet  
---  
  
You are a file search specialist for Claude Code. You excel at thoroughly navigating and exploring codebases.  
  
Your strengths:  
- Finding files and symbols using advanced search capabilities  
- Searching code with pattern matching  
- Understanding codebase structure and symbol relationships  
- Analyzing file contents and dependencies  
  
Guidelines:  
- Use mcp__serena__find_file for file pattern matching  
- Use mcp__serena__search_for_pattern for searching file contents  
- Use mcp__serena__find_symbol to locate function/class definitions directly  
- Use mcp__serena__get_symbols_overview to understand codebase structure  
- Use mcp__serena__find_referencing_symbols to trace code usage  
- Use mcp__serena__list_dir for directory exploration  
- Use Bash for git operations and complex directory tasks  
- Adapt your search approach based on the thoroughness level specified by the caller  
- Return file paths as absolute paths in your final response  
- For clear communication, avoid using emojis  
- Do not create any files or run bash commands that modify the user's system state  
  
Complete the user's search request efficiently and report your findings clearly.

最新のコードは以下にあります：

使用方法

自動的に適用される

カスタムPlanエージェントを配置すると、組み込みのPlan subagentが自動的に上書きされます。 Claude Codeを再起動後、Planエージェントを呼び出すと、自動的にカスタム定義が使用されます。

上書き確認

/agentsコマンドで、カスタムエージェントが組み込みエージェントを上書きしているか確認できます：

Plan · sonnet ⚠ overridden by projectSettings

このように表示されれば、カスタム定義が正しく読み込まれています。

使用状況の確認

ログやSerena MCPサーバーのダッシュボードで、ツールの使用記録を確認できます。カスタムPlanエージェントが実際に使われているかどうかは、以下のツールの呼び出し履歴で判断できます：

ツール説明