serena-config について
Serena のグローバル設定とプロジェクト設定を扱うスキルです。設定レイヤーの選択、言語サーバーやインデックスの問題の診断、変更内容の検証を支援します。
主な機能
- 01グローバル設定とプロジェクト設定のガイド
- 02関連する設定リファレンスの案内
- 03言語とワークスペース設定のトラブルシューティング
- 04システムプロンプトとシンボル検索による設定検証
- 05キャッシュ削除と MCP サーバー再起動の案内
活用シーン
- 01リポジトリの言語と除外ルールの設定
- 02グローバルなコンテキスト、モード、ツールセットの設定
- 03シンボル検索や言語サーバーのエラー診断
MCP 対応
Serena は `serena start-mcp-server` で MCP サーバーとして起動できます。このスキルでは起動引数の設定項目と、サーバーの再起動が必要になる場合を扱います。
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/serena-configを入力して読み込まれたか確認します。
同梱ファイルreferences/global-config.mdreferences/project-config.md
詳細
serena-config
Serena を、マシン全体のグローバル設定とリポジトリごとのプロジェクト設定という2つの層で構成します。
Serena の設定は各層で行い、上位の設定を上書きまたは拡張します。
- グローバル —
~/.serena/serena_config.yml。すべてのプロジェクトのデフォルト設定です。言語バックエンド、デフォルトのツール／モード、グローバルな無視ルール、言語サーバーの調整が含まれます。 - プロジェクト —
<repo>/.serena/project.yml。リポジトリごとの上書き設定です。言語、無視ルール、書き込みアクセス、モノレポのワークスペースフォルダー、追加モードが含まれます。 - コンテキストとモード — 組み合わせ可能なツールセット／プロンプトのプリセットです。グローバル、プロジェクトごと、または起動時に設定できます。
serena start-mcp-serverへの CLI 引数 — 上記すべてを上書きまたは拡張します。
<certain>多くのproject.ymlキーは、serena_config.ymlを拡張または上書きします。 マシン全体のデフォルト設定はグローバルファイルに、リポジトリ固有の設定のみをプロジェクトファイルに記述してください。
適切なリファレンスを選ぶ
| ユーザーがしたいこと | 参照先 |
|---|---|
単一リポジトリの調整：言語の誤り、モノレポの相互参照、vendor/／生成ディレクトリの無視、読み取り専用リポジトリ、リポジトリごとの LSP パス | references/project-config.md |
プロジェクトの作成／インデックス作成／有効化、project.local.yml によるローカル上書きの理解 | references/project-config.md |
| マシン全体のデフォルト設定：言語バックエンド、デフォルトのツール／モード、グローバルな無視設定、ログ記録 | references/global-config.md |
コンテキスト（claude-code、ide、desktop-app、…）の選択または変更 | references/global-config.md |
モード（planning、editing、no-memories、query-projects、…）の追加／上書き | references/global-config.md |
Serena の接続先としてセルフインストールした言語サーバー（ls_path）を指定する、または LSP のバージョンを固定する | references/global-config.md |
データディレクトリ（SERENA_HOME）またはプロジェクトごとの .serena フォルダーの移動 | references/global-config.md |
対応すべき場合（および対応不要な場合）
Serena は、妥当なデフォルト設定を使って両方の設定ファイルを自動作成します。グローバル設定は初回実行時に、プロジェクト設定はリポジトリの初回有効化時に作成されます。ほとんどのリポジトリでは編集は不要です。 次のいずれかに該当する場合にのみ、設定を変更してください。
| 症状 | 層 | 修正箇所 |
|---|---|---|
| LSP がパッケージ境界を越えてシンボルを解決できない（モノレポ） | プロジェクト | additional_workspace_folders |
find_symbol が誤った言語の結果を返す、または起動時に LSP エラーが発生する | プロジェクト | languages: |
vendor/、node_modules/、dist/、生成コードからのシンボル検索結果が多すぎる | プロジェクト | ignored_paths: |
| リポジトリがレビュー専用で、Serena に書き込みをさせたくない | プロジェクト | read_only: true |
| ハーネスに適さないツールセット（例：Claude Code の組み込み機能との重複） | グローバル | --context |
| プランニング専用またはメモリーなしで動作させたい | グローバル | モード |
| セルフインストールした LSP、または LSP／ランタイムのバージョンを固定する必要がある | どちらでも | ls_specific_settings |
どれにも当てはまらない場合は、設定を変更しないでください。ブートストラップの設定で問題ありません。
事前に対応する価値がある唯一の例外は、ignored_paths です。 上記の項目とは異なり、ベンダーコードや生成コード（vendor/、コミット済みの dist/、生成されたクライアント、スナップショットのフィクスチャ）を含むリポジトリでは、問題が発生する前に設定する価値があります。デフォルトで .gitignore は適用されますが、コミット済みのノイズは find_symbol／get_symbols_overview の結果を汚染し（LSP の初回インデックス作成が遅くなることもあります）。references/project-config.md の「"ignored_paths — set this in most non-trivial repos"」を参照してください。一方、ls_path はあくまで回避手段です。デフォルトではマネージド方式を優先することを推奨します（references/global-config.md を参照）。
編集の指針
- 設定ファイルをゼロから手作業で作成しないでください。 Serena に初期設定を行わせて
ください（プロジェクトの場合は
serena project create、グローバルファイルの場合は 初回実行時）。その後、編集してください。生成されたファイルにはインラインのドキュメントコメントと、 新しいバージョンで追加されたフィールドが含まれています。これらは残してください。 - 編集後に検証してください。
serena print-system-prompt "$(pwd)"で解決済みの設定を 表示し、プロジェクト名、言語のリスト、有効なモード、除外されたツールが想定どおりであることを 確認してください。次に、既知のシンボルに対してfind_symbolを呼び出し、LSP を 確認してください。エラーのない結果であれば言語の解析に成功しています。LSP の起動エラーが 発生した場合は、languages:またはls_specific_settings:が誤っています。 - 変更後に LSP の挙動がおかしい場合は、
.serena/cache/を削除して再構築を 強制してください。完全にリセットするには、MCP サーバーの再起動も必要なサーバーがあります。
参考資料
- プロジェクト設定のスキーマ（テンプレート）：https://github.com/oraios/serena/blob/main/src/serena/resources/project.template.yml
- グローバル設定のスキーマ（テンプレート）：https://github.com/oraios/serena/blob/main/src/serena/resources/serena_config.template.yml
- 言語の列挙型（有効な
languages:/ls_specific_settingsのキー）：https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py - ワークフローのドキュメント：https://oraios.github.io/serena/02-usage/040_workflow.html
- 設定のドキュメント：https://oraios.github.io/serena/02-usage/050_configuration.html