Content is user-generated and unverified.

Serena + Claude Code セットアップガイド

🎯 Serenaとは？

SerenaはClaude Codeをより安く、より強力にするオープンソースツールです。

通常のClaude Codeの問題点

  • 高額なAPI料金 - 複雑なタスクで数ドル〜数十ドル
  • 限定的なコード理解 - テキストベースの解析のみ
  • 編集の精度不足 - 行数を間違えたり、正確な位置を特定できない

Serenaが解決すること

  • 💰 料金削減 - 同じタスクを約1/3〜1/10のコストで実行
  • 🧠 深いコード理解 - 言語サーバーによる構造的な解析
  • 🎯 正確な編集 - シンボル単位での精密なコード操作
  • 🔍 高速検索 - プロジェクト全体から関数・クラスを瞬時に発見

技術的な特徴

  • Language Server Protocol (LSP) を使用した本格的なコード解析
  • 13言語以上対応 - Python, TypeScript, Java, Rust, Go, PHP など
  • シンボル単位編集 - 関数名やクラス名で直接指定して編集可能
  • プロジェクト記憶機能 - 過去の分析結果を学習して効率化

🚀 セットアップ手順

ステップ1: uvのインストール

uvはPythonのパッケージマネージャーです。以下のいずれかの方法でインストールしてください：

推奨インストール方法

macOS/Linux:

bash
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

その他のインストール方法

macOS (Homebrew):

bash
brew install uv

pip経由:

bash
pip install uv

より詳しいインストール方法は uv公式インストールガイド を参照してください。

インストール後、ターミナルを再起動してください。

ステップ2: Serenaをプロジェクトに追加

プロジェクトディレクトリで以下のコマンドを実行：

bash
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena-mcp-server --context ide-assistant --project $(pwd)

これだけでセットアップ完了です！

ステップ3: 初期設定の読み込み

Claude Codeで新しい会話を始めて：

Serenaの初期設定を読み込んでください

または：

/mcp__serena__initial_instructions

📁 プロジェクトの使用

プロジェクトの有効化

Serenaでは、プロジェクトを明示的に「有効化」する必要があります。Claude Codeで以下のように指示してください：

絶対パスで指定:

プロジェクト /path/to/my_project を有効化してください

プロジェクト名で指定（過去に有効化済みの場合）:

プロジェクト my_project を有効化してください

有効化されたプロジェクトは自動的に serena_config.yml に追加され、各プロジェクトには .serena/project.yml が生成されます。

プロジェクトのインデックス化（推奨）

大きなプロジェクトでは必須です！ インデックス化により、初回のツール実行が大幅に高速化されます。

プロジェクトディレクトリで以下を実行：

bash
uvx --from git+https://github.com/oraios/serena index-project

または、別のディレクトリから：

bash
uvx --from git+https://github.com/oraios/serena index-project /path/to/project

新しいプロジェクトでの使用

新しいプロジェクトでSerenaを使う場合：

bash
cd /path/to/new/project
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena-mcp-server --context ide-assistant --project $(pwd)

重要な注意点

  • 会話開始時: 新しい会話やコンパクト後は必ず初期設定を読み込む
  • プロジェクト有効化: 各プロジェクトを明示的に有効化する必要がある
  • インデックス化: 大きなプロジェクトでは事前にインデックス化を推奨
  • プロジェクト名の重複: 異なるプロジェクトで同じ名前を使わない

🎯 基本的な使い方

📖 コードの分析

プロジェクト全体の理解:

このプロジェクトの構造を教えてください

関数・クラスの検索:

"calculate"という名前の関数を探してください
Userクラスの定義を見せてください

依存関係の分析:

この関数がどこから呼び出されているか教えてください

✏️ コードの編集

新しいメソッドの追加:

User クラスに新しいメソッド get_full_name を追加してください。
first_name と last_name を結合して返す機能です。

関数の置き換え:

calculate_price 関数の中身を、税込み計算に変更してください

コードの改善:

このコードにエラーハンドリングを追加してください

🧪 テストと実行

テストの実行:

テストを実行してください

デバッグ:

このエラーの原因を調べて修正してください：
[エラーメッセージをペースト]

📄 ファイル操作

新しいファイルの作成:

新しいファイル utils.py を作成して、共通のユーティリティ関数を追加してください

設定ファイルの編集:

package.json に新しい依存関係を追加してください

🔍 よく使う応用例

1. プロジェクト理解

このプロジェクトの主要な機能と、ファイル構造を説明してください。
使用している技術スタックと、エントリーポイントも教えてください。

2. バグ修正

以下のエラーを修正してください：

TypeError: 'NoneType' object is not subscriptable
File "main.py", line 42, in process_data

3. 新機能の実装

ユーザー認証機能を実装してください：
- ログイン/ログアウト
- パスワードハッシュ化
- JWT トークン生成
- 認証ミドルウェア

4. リファクタリング

この関数は長すぎて複雑です。
複数の小さな関数に分割してリファクタリングしてください

5. パフォーマンス最適化

この処理が遅いです。ボトルネックを特定して最適化してください

⚙️ プロジェクト設定

.serena/project.yml の作成

プロジェクト固有の設定を行いたい場合、.serena/project.yml を作成：

yaml
project_name: "my-project"
language: python  # python, typescript, java, rust, go, php など
read_only: false  # trueにすると読み取り専用
ignored_paths:
  - "node_modules/*"
  - "*.log"
  - "__pycache__/*"
  - ".git/*"
encoding: "utf-8"

対応言語一覧

言語設定値状態
Pythonpython✅ 完全サポート
TypeScript/JavaScripttypescript✅ 完全サポート
Javajava✅ 完全サポート
C#csharp✅ 完全サポート
Rustrust✅ 完全サポート
Gogo✅ 完全サポート
PHPphp✅ 完全サポート
Elixirelixir✅ 完全サポート
Clojureclojure✅ 完全サポート
C/C++cpp⚠️ 一部制限あり

🛠️ トラブルシューティング

よくある問題と解決方法

1. セットアップが失敗する

症状: claude mcp add コマンドが失敗

解決方法:

bash
# uvのインストール確認
uv --version

# Claudeコマンドの確認
claude --version

# プロジェクトディレクトリの確認
pwd

2. 初期設定が読み込めない

症状: Serenaのツールが表示されない

解決方法:

  • 新しい会話で再度試す
  • コンパクト後は必ず初期設定を読み込み直す
  • /mcp__serena__initial_instructions コマンドを使用

3. 言語サーバーが起動しない

症状: コード解析ができない

解決方法:

bash
# プロジェクトに対応言語のファイルがあるか確認
ls *.py *.ts *.js *.java

# .serena フォルダの作成
mkdir -p .serena

4. プロジェクトが認識されない

症状: 「プロジェクトが見つからない」エラー

解決方法:

bash
# プロジェクトディレクトリで再実行
cd /correct/project/path
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena-mcp-server --context ide-assistant --project $(pwd)

💡 効果的な使い方のコツ

1. 具体的な指示を出す

❌ 悪い例: "コードを良くして" ✅ 良い例: "この関数にエラーハンドリングとログ出力を追加して"

2. 段階的に進める

大きなタスクは小さく分割：

  1. まず構造を理解
  2. 具体的な実装
  3. テストとデバッグ

3. プロジェクトの記憶機能を活用

このプロジェクトの重要な設計方針をメモリに保存してください

4. 定期的にテストを実行

変更後にテストを実行して、既存機能が壊れていないか確認してください

🎉 まとめ

SerenaをClaude Codeと組み合わせることで：

  • 開発コストを大幅削減
  • より正確で効率的なコード編集
  • プロジェクト全体の深い理解
  • 高品質なコードの自動生成

これらが実現できます。

参考リンク:

Content is user-generated and unverified.
    Serena セットアップ＆使い方ガイド | Claude