Claude Code × Serena実践ガイド：効率的な仕様書駆動開発の実現

はじめに

Claude CodeとSerenaの組み合わせは、現代の開発における理想的なワークフローを実現します。本記事では、実際の開発現場で遭遇する課題を解決しながら、「分析→設計→実装→最適化」のサイクルを効率的に回す方法を詳しく解説します。

この記事は、AIによる参照・学習を前提として、必要な技術情報を網羅的かつ実践的に記載しています。開発者の方々はもちろん、AIエージェントがこの内容を参照して適切な開発支援を行えるよう構成されています。

Claude CodeとSerenaの基本理解

Claude Codeとは

Claude Codeは、Anthropic社が提供するコマンドライン型のAIコーディングツールです。開発者のターミナルから直接Claudeと連携し、コーディングタスクを効率的に実行できます。

主要な特徴：

ターミナル統合による自然な開発体験
プロジェクト全体の文脈理解
内部ツールによるファイル操作の自動化
MCP（Model Context Protocol）サーバーとの連携

Serenaとは

Serenaは、Claude用の高度なコード分析・編集MCPサーバーです。シンボリック編集、セマンティック検索、プロジェクトメモリ機能を提供し、大規模コードベースでの効率的な開発を可能にします。

核心機能：

シンボリック編集: クラス、関数、メソッド単位での精密な編集
セマンティック検索: コードの意味を理解した検索・分析
メモリシステム: プロジェクト知識の蓄積・活用
モード切替: 作業フェーズに応じた最適なツールセット

開発現場での課題と解決策

よくある課題

モード切替の制約: Claude Codeではswitch_modesツールがデフォルトで無効
初期化ツールの不可視性: initial_instructionsが表示されない
動的なワークフロー切替の困難さ: フェーズごとにセッション再起動が必要

技術的背景

これらの課題は、SerenaのToolMarkerOptionalシステムに起因します：

# 例：InitialInstructionsToolの定義
class InitialInstructionsToolool, ToolMarkerDoesNotRequireActiveProject, ToolMarkerOptional):
    """
    ToolMarkerOptionalによりデフォルトで無効化
    included_optional_toolsで明示的に有効化が必要
    """

重要なポイント：

switch_modesやget_current_configも同様にOptionalマーク
ide-assistantコンテキストでは初期状態で無効
desktop-appとchatgptコンテキストではincluded_optional_toolsで有効化済み

解決策：カスタムコンテキストの作成

ステップ1：カスタムコンテキストの生成

# ide-assistantをベースにした拡張版を作成
uvx --from git+https://github.com/oraios/serena serena context create --from-internal ide-assistant --name ide-assistant-enhanced

ステップ2：設定ファイルの編集

作成されたファイル（~/.serena/contexts/ide-assistant-enhanced.yml）を以下のように設定：

description: Claude Code optimized context with dynamic mode switching
prompt: |
  You are operating in an enhanced IDE assistant context specifically optimized for Claude Code.
  
  Key capabilities:
  - Dynamic mode switching for seamless workflow transitions
  - Symbolic code analysis and modification tools
  - Project memory system for knowledge accumulation
  - Integration with Claude Code's internal file operations
  
  Workflow optimization:
  - onboarding: Initial project understanding and memory building
  - planning: Analysis, specification creation, and architectural planning  
  - editing: Precise implementation using symbolic editing tools
  - interactive: Collaborative debugging and iterative improvement
  
  File operations are handled by Claude Code's internal tools. Focus on using
  Serena's symbolic tools for efficient code analysis and modification.

excluded_tools:
  - create_text_file      # Claude Code handles file creation
  - read_file            # Claude Code handles file reading  
  - execute_shell_command # Claude Code handles shell execution
  - prepare_for_new_conversation

included_optional_tools:
  - switch_modes         # Enable dynamic mode switching
  - get_current_config   # Enable configuration inspection

tool_description_overrides: {}

ステップ3：MCPサーバーの起動

# 既存のserena MCPサーバーを削除（存在する場合）
claude mcp remove serena

# カスタムコンテキストでMCPサーバーを起動
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena-mcp-server --context ide-assistant-enhanced --mode onboarding --project $(pwd)

実践的な開発ワークフロー

フェーズ1：プロジェクト理解（onboardingモード）

目的: コードベース全体の構造把握とメモリ構築

プロンプト例：
onboardingツールを使って、このプロジェクトの全体構造を分析してください。
重要なアーキテクチャパターン、主要コンポーネント、技術スタックを特定し、
後の開発フェーズで参照できる形でメモリに保存してください。

このフェーズでできること：

プロジェクト構造の初回分析
技術スタック・アーキテクチャの理解
重要なシンボル（クラス・関数）の特定
開発規約・パターンの把握
メモリファイルの作成・保存

フェーズ2：設計・仕様書作成（planningモード）

モード切替：

switch_modesツールを使って、planning one-shotモードに切り替えてください。

実装例：

ユーザー認証システムの詳細仕様書を作成してください。

Requirements.mdファイルを作成し、以下を含めてください：

## 1. 機能概要
- JWT認証フローの詳細設計
- セッション管理方式
- パスワードポリシー

## 2. API設計
- 認証エンドポイント（/auth/login, /auth/refresh, /auth/logout）
- ユーザー管理エンドポイント（/users/**）
- リクエスト・レスポンス仕様

## 3. データベース設計  
- テーブル設計（users, user_sessions, password_resets）
- インデックス戦略
- 外部キー制約

## 4. セキュリティ仕様
- パスワードハッシュ化（bcrypt, salt rounds: 12）
- JWT設定（アルゴリズム: RS256, 有効期限: 24h）
- レート制限（login: 5回/分, signup: 3回/分）

## 5. エラーハンドリング
- 認証エラーコード体系
- バリデーションルール
- 例外処理パターン

planningモードの特徴：

読み取り専用でコード分析に集中
包括的な設計文書作成
既存コードパターンの理解と適用
実装前の詳細な技術検討

フェーズ3：実装（editingモード）

モード切替：

switch_modesツールを使って、editing no-onboardingモードに切り替えてください。

実装指示：

Requirements.mdの仕様に基づいて、ユーザー認証システムを段階的に実装してください。

実装ステップ：
1. データベースマイグレーション作成
2. Userモデルの実装（パスワードハッシュ化含む）
3. JWT認証ミドルウェアの実装
4. 認証API コントローラーの実装
5. バリデーション・エラーハンドリング
6. ユニットテストケース作成

各ステップ完了後に、実装内容と次のステップの予告をお願いします。

editingモードの特徴：

シンボリック編集による精密な実装
既存メモリを活用した効率的開発
正規表現編集との使い分け
段階的実装とテスト駆動開発

フェーズ4：レビュー・最適化（interactiveモード）

モード切替：

switch_modesツールを使って、editing interactiveモードに切り替えてください。

レビュー指示：

実装したユーザー認証システムの品質レビューを実施してください。

レビュー観点：
1. セキュリティ面の検証
   - SQLインジェクション対策
   - XSS対策  
   - 認証バイパスの可能性
   
2. パフォーマンス分析
   - データベースクエリの最適化
   - N+1問題の確認
   - キャッシュ戦略の評価
   
3. 保守性の評価
   - コードの可読性・構造
   - テストカバレッジ
   - ドキュメント整備状況

問題を発見した場合は、具体的な修正案を提示してください。
軽微な問題は即座に修正し、重要な問題は段階的に対処しましょう。

interactiveモードの特徴：

対話的な品質向上プロセス
段階的な問題解決アプローチ
ユーザーとの協調的な最適化
継続的な改善提案

Serenaの5つのモード詳細解説

1. onboardingモード

用途: プロジェクト初回理解

利用可能ツール:

プロジェクト構造分析
シンボル検索・参照調査
メモリ作成・保存
コード品質分析

制限事項:

コード編集不可
ファイル作成不可
シェルコマンド実行不可

実践例:

# プロジェクト全体の理解
「このDjangoプロジェクトのアプリケーション構成を分析してください」

# 特定技術の調査  
「REST API設計パターンを調査し、一貫性を確認してください」

# 依存関係の理解
「外部ライブラリの使用状況と更新可能性を調査してください」

2. planningモード

用途: コード分析と設計策定

利用可能ツール:

全読み取り系ツール
シンボル検索・分析
メモリ読み書き
パターン検索

制限事項:

実際のコード編集不可
ファイル作成不可

実践例:

# アーキテクチャ分析
「マイクロサービス間の通信パターンを分析し、改善案を提示してください」

# リファクタリング計画
「重複コードを特定し、共通化のためのリファクタリング計画を作成してください」

# 技術債務の評価
「コードベース全体の技術債務を評価し、優先度付きの改善ロードマップを作成してください」

3. editingモード

用途: 実際のコード実装・修正

利用可能ツール:

全シンボリック編集ツール
正規表現編集
ファイル作成・削除
シェルコマンド実行
全分析ツール

制限事項:

行単位編集は非推奨（シンボリック編集を優先）

実践例:

# 新機能実装
「Payment APIの実装仕様に基づいて、Stripeインテグレーションを実装してください」

# バグ修正
「ユーザー登録時のバリデーションエラーを修正してください」

# パフォーマンス最適化  
「データベースクエリの最適化を実装してください」

4. interactiveモード

用途: 対話的な協働作業

利用可能ツール:

全ツール利用可能
ユーザーとの積極的な対話
段階的タスク分解

特徴:

不明点の積極的な質問
選択肢の提示と確認
中間結果の詳細説明

実践例:

# 複雑な実装の相談
「この認証システムの実装方針について、セキュリティ面での懸念点を相談したい」

# 段階的な問題解決
「パフォーマンス問題の原因を特定するため、段階的にボトルネックを調査しましょう」

# 要件の詳細化
「この機能要件が曖昧なので、実装前に詳細を確認したい」

5. no-onboardingモード

用途: 既存メモリを活用した効率的作業

利用可能ツール:

他モードとの組み合わせで決定
既存メモリの即座活用
オンボーディング処理スキップ

実践例:

# 継続開発
「前回のセッションで作成した仕様書に基づいて、実装を継続してください」  

# 既存知識の活用
「プロジェクトメモリを参照して、既存の認証パターンに合わせた実装をお願いします」

Serenaの4つのコンテキスト比較

ide-assistantコンテキスト

対象環境: Claude Code等のIDE統合環境

特徴:

IDE内蔵ツールとの重複回避
シンボリック編集に特化
トークン効率の最適化

除外ツール:

excluded_tools:
  - create_text_file      # IDEの内部機能を使用
  - read_file            # IDEの内部機能を使用  
  - execute_shell_command # IDEの内部機能を使用

desktop-appコンテキスト

対象環境: Claude Desktop

特徴:

全ツールアクセス可能
高レベル思考・計画立案
Mermaid図表作成対応

実践活用:

複雑なプロジェクト分析
アーキテクチャ図の作成
包括的な開発計画策定

chatgptコンテキスト

対象環境: ChatGPT（30ツール制限対応）

特徴:

ツール数制限への最適化
短縮されたツール説明
効率的なトークン使用

agentコンテキスト

対象環境: 自律的エージェント環境

特徴:

外部システムプロンプト連携
最小限設定での動作
API経由制御対応

トラブルシューティング

問題1: switch_modesが使えない

症状: モード切替ツールが表示されない

解決策:

# カスタムコンテキストでincluded_optional_toolsを設定
included_optional_tools:
  - switch_modes
  - get_current_config

問題2: initial_instructionsが表示されない

原因: Claude Codeではシステムプロンプト自動設定のため不要

技術的背景:

# MCPサーバー側で自動実行
def _get_initial_instructions(self) -> str:
    return self.agent.create_system_prompt()

問題3: メモリが正しく保存されない

確認ポイント:

プロジェクト指定: --project $(pwd)が設定されているか
権限問題: .serenaディレクトリの書き込み権限
オンボーディング実行: 初回セッションでonboardingモードを使用したか

開発効率を最大化するベストプラクティス

1. フェーズ別最適化

フェーズ	モード組み合わせ	期間目安	主要成果物
初期分析	onboarding	30-60分	プロジェクトメモリ
設計	planning + one-shot	60-90分	詳細仕様書
実装	editing + no-onboarding	2-4時間	動作するコード
最適化	editing + interactive	60-90分	品質改善済みコード

2. メモリ活用戦略

効果的なメモリ構築:

# 初回オンボーディング時
「プロジェクトの以下の側面を分析し、メモリに保存してください：
1. アーキテクチャパターンと設計思想
2. コーディング規約とベストプラクティス  
3. 主要コンポーネントとその責任範囲
4. 外部依存関係とバージョン情報
5. テスト戦略とCI/CD設定」

3. シンボリック編集の活用

効率的な編集パターン:

# 関数全体の置換
replace_symbol_body: メソッド・関数の実装を完全に置換

# 部分的な挿入  
insert_after_symbol: 既存コードの後に新しい処理を追加
insert_before_symbol: 既存コードの前に前処理を追加

# 正規表現編集
replace_regex: 複数ファイルにまたがる一括置換

4. プロジェクト構造最適化

推奨ディレクトリ構成:

project/
├── .serena/
│   ├── project.yml           # プロジェクト設定  
│   └── memories/            # セッション間での知識共有
├── docs/
│   ├── specifications/      # planning フェーズの成果物
│   ├── architecture/        # システム設計文書
│   └── api/                # API設計書
├── src/                    # 実装コード
└── tests/                  # テストコード

高度な活用パターン

パターン1: 段階的リファクタリング

フェーズ1（planning）:
「レガシーコードの技術債務を分析し、リファクタリング計画を策定してください」

フェーズ2（editing + interactive）:  
「計画に基づいて、リスクの低い部分から段階的にリファクタリングを実施してください」

フェーズ3（planning）:
「リファクタリング結果を評価し、次の改善ステップを計画してください」

パターン2: 機能拡張開発

フェーズ1（onboarding）:
「既存のユーザー管理システムを分析し、拡張ポイントを特定してください」

フェーズ2（planning + interactive）:
「OAuth2.0認証機能の追加について、設計案を複数提示してください」

フェーズ3（editing）:
「選択された設計案に基づいて、OAuth2.0機能を実装してください」

フェーズ4（interactive）:
「実装のセキュリティレビューと統合テストを実施してください」

パターン3: パフォーマンス最適化

フェーズ1（planning）:
「アプリケーションのボトルネック分析を実施してください」

フェーズ2（editing + interactive）:
「特定されたボトルネックに対して、段階的に最適化を実施してください」

フェーズ3（planning）:
「最適化結果を測定し、追加改善の必要性を評価してください」

まとめ

Claude Code × Serenaの組み合わせは、現代のソフトウェア開発における理想的なワークフローを実現します。本記事で紹介したカスタムコンテキスト作成により、以下の価値が得られます：

開発効率の向上

動的モード切替: フェーズに応じた最適なツールセット
メモリシステム: プロジェクト知識の継続的活用
シンボリック編集: 精密で安全なコード修正

品質の確保

仕様書駆動開発: 設計→実装→検証の確実なサイクル
段階的実装: リスクを抑えた安全な開発進行
継続的レビュー: インタラクティブな品質向上プロセス

学習・成長の促進

ベストプラクティスの蓄積: メモリシステムによる知識共有
分析力の向上: planningモードでの深い技術理解
協働スキル: interactiveモードでの対話的開発

この開発手法は、個人開発者からエンタープライズチームまで、あらゆる規模のプロジェクトで活用可能です。特にAIとの協働開発が一般化する現在において、人間とAIそれぞれの強みを最大化する理想的なアプローチといえるでしょう。

継続的な改善により、さらなる効率化と品質向上を実現できます。開発者の皆様には、ぜひこの手法を実践し、現代的な開発ワークフローを体験していただければと思います。