プロジェクト構成をSerena効率化に向けたチューニング

プロジェクト構成をSerena効率化に向けたチューニング

Serenaを効率よく動作させてToken消費を抑えるため、Claudeに確認しながらより良いプロジェクト構成を目指してみました。Serenaを徹底的に使うには意外とコツが必要なようです。
2025.08.06

SerenaでのToken効率がclaude —verbose経由での目視確認でも明らかにそこまで良くなっていませんでした。原因をClaudeに確認したところ、以下の通り。

serenaのシンボル検索は Typescript/Javascript関数・クラスに最適化されており、Vue SFCでは制限があります

そこでVueファイルの分割を試みましたが、それだけではまだまだ十分な効果が得られませんでした。

今回は、Serenaメモリの特性に合わせたファイル登録によるToken節約と、Serenaシンボル検索の特性を活かした実用的な検索最適化まで、考えられる様々な対策を模索した内容をまとめています。

Vueファイルの分割

指示自体はシンプルです。

**.vueからtsとcssを分離して

ポイントは処理都合上Serenaコマンドが効かないことでしょうか。Readコマンドで全部読み込む必要があるためですが、必要経費と割り切りましょう。

Serenaメモリとの相性を考慮したファイル登録

Serenaメモリは「変更頻度が低く、参照頻度が高い」情報に限定することで最大効果を発揮します。今回対象としている、追加修正で変更が頻繁に発生するVueコンポーネントとCSSファイルは相性がよくありません。

Claudeが提示した最適なファイルとしては以下の通り。

  • package.json ✅ (設定ファイル、変更頻度低)
  • vite.config.ts ✅ (設定ファイル、安定)
  • tsconfig.json ✅ (TypeScript設定、変更稀)
  • アーキテクチャ設計文書 ✅ (概念的内容、安定)

プロジェクト内のpackage.json読み込みに約2000トークン使われていたようで、Serenaメモリに追加したことで今後は約500トークンの75%削減まで至れるようです。vite.config.tsは約800トークン → 200トークン (75%削減)となりました。

Serenaメモリ行使によるToken節約

Serenaメモリ操作でのToken消費量はClaudeによれば大体以下が目安のようです。

  1. write_memory (メモリ書き込み)
    • 低コスト (約50-200トークン)
    • テキストをストレージに送信するだけの単純な操作
    • コンテンツサイズに比例するが、書き込み処理自体は軽量
  2. read_memory (メモリ読み込み)
    • 中程度のコスト (メモリ内容に依存)
    • 小さなメモリ: 100-500トークン
    • 大きなメモリ: 1000-3000トークン
    • ファイル内容をコンテキストに読み込むため、内容量に比例

行数とバイト数から推定するトークンについては以下の表を提示されています。

行数 バイト数 推定トークン 注意レベル
~200行 ~5KB 300-800 問題なし
200-500行 5-15KB 800-2000 注意
500-1000行 15-25KB 2000-4000 要注意

幾度もClaudeには目安行数を確認していますが、分割を検討するラインとして500行を提示されています。

Serenaのシンボル検索実行方針

Serenaのシンボル検索は自身のサーバが起動していることが前提です。/mcpにて接続されているか確認します。

スクリーンショット 2025-08-05 15.37.47

また、Claudeによると、Serenaは「オンデマンド型」で必要な時にのみ実行されるようです。正確な名前や名前の一部が判明している場合、または対象ディレクトリが絞れている状況でなければ、Claude自身がGrepを実行することになります。

ディレクトリと関数名が絞れていれば、Serena経由で以下のようなプロセスが実行されるようです。

新しいコンポーネント調査時

  1. get_symbols_overview でファイル構造把握
  2. find_symbol で主要クラス・関数特定
  3. 必要部分のみ include_body=true で詳細取得

既存コード修正時

  1. find_symbol で対象メソッド特定
  2. find_referencing_symbols で影響範囲確認
  3. 修正対象のみ詳細読み込み

筆者のCLAUDE.mdには以下の記載があるため、大きなファイルを読む前には必ずシンボル検索が優先されているようです。

## Search Exclusion Rules
- ****Serena Response Management****: Use parameter limits (max*_answer_*chars=50000, include*_body=false) and phased approach (overview → targeted analysis → detailed examination)*

Serenaのシンボル検索を確実に使わせる

Serenaでのシンボル検索を確実に使わせる方法としてClaudeから提案されたのはプロンプト(CLAUDE.md)での指定です。一例としては以下の通りです。

## Search Strategy Automation
 - **曖昧な指示への対応**: 「探して」「調べて」「確認して」等の指示時は以下を自動実行:
   1. `mcp__serena__get_symbols_overview({ relative_path: "." })` - プロジェクト全体概要
   2. `mcp__serena__get_symbols_overview({ relative_path: "src" })` - ソースコード概要
   3. 必要に応じて `mcp__serena__find_symbol` で詳細調査

筆者のCLAUDE.mdには英語で記述することを記載していたため、一部除いて英訳での追記となりました。

## Search Strategy Automation  
- **Ambiguous Search Commands**: When receiving ambiguous instructions like "探して", "調べて", "確認して", automatically execute:
  1. `mcp__serena__get_symbols_overview({ relative_path: "." })` - Project overview
  2. `mcp__serena__get_symbols_overview({ relative_path: "src" })` - Source code overview  
  3. Use `mcp__serena__find_symbol` for targeted investigation based on overview results

実際のSerenaのシンボル検索

ですが、セッションを試してみたところ、実際の動作とのズレがありました。

serenaコマンドのコマンド毎実行割合の計算

  • mcp__serena__get_symbols_overview - 1回(エラー)
  • mcp__serena__find_file - 2回
  • mcp__serena__search_for_pattern - 12回
  • mcp__serena__find_symbol - 0回
  • mcp__serena__replace_regex - 0回

これはSearch Strategy AutomationとしてClaudeから追記された項目が機能していなかったことになります。原因としては、記述があっても実行を促す具体的な指示が不足していたためとのこと。

これらを踏まえて提案された内容が以下の通り。

  # CLAUDE.mdに追加すべき内容

  ## Mandatory Session Initialization
  IMPORTANT: 以下のコマンドを必ずセッション開始時に実行すること

  ```bash
  # 1. プロジェクト構造の自動スキャン
  echo "🔍 Initializing project context..."
  mcp__serena__check_onboarding_performed
  mcp__serena__list_memories
  mcp__serena__list_dir({ relative_path: ".", recursive: false })

  # 2. 重要ファイルの特定
  mcp__serena__find_file({ file_mask: "package.json", relative_path: "." })
  mcp__serena__find_file({ file_mask: "*.config.*", relative_path: "." })

  Project Structure Cache

  以下の情報は初回実行後、Serenaメモリに保存すること:
  - src/components/: Vue components (use find_symbol)
  - public/js/: Legacy JavaScript modules (use search_for_pattern)
  - src/services/: API services (use find_symbol)
  ```end

  ## Symbol Search Patterns

  このプロジェクト固有のパターン:

  - Vue Components: find_symbol("ComponentName/setup")
  - Event Handlers: find_symbol("handle*")
  - API Methods: find_symbol("*Service/*")

  ## 実装推奨事項

  ### 1. **CLAUDE.mdの強化**

  ## MANDATORY: Auto-execution Rules
  以下は自動的に実行されます(ユーザーへの確認不要):

  1. **新規セッション開始時**:
     - `mcp__serena__list_memories`
     - `mcp__serena__get_symbols_overview({ relative_path: "src" })`

  2. **ファイル検索時**:
     - まず`find_symbol`を試行
     - 失敗時のみ`search_for_pattern`にフォールバック

  3. **複数の類似編集時**:
     - 3箇所以上の同様の変更は`replace_regex`を使用

セッション起動時にCLAUDE.mdを経由してSerenaへ自動処理を行うという手続きですが、「こういう事もできるんだ」といった感想でした。

実際に記載した内容は次の通りです。

   ## MANDATORY: Project Structure Discovery Protocol

   ### Auto-execution at Session Start
   The following commands MUST be executed automatically at the beginning of each session:

   ```bash
   # 1. Check existing knowledge
   mcp__serena__check_onboarding_performed
    mcp__serena__list_memories

   # 2. Project structure scan
   mcp__serena__list_dir({ relative_path: ".", recursive: false })
   mcp__serena__get_symbols_overview({ relative_path: "src" })

   # 3. Configuration files
   mcp__serena__find_file({ file_mask: "package.json", relative_path: "." })
   mcp__serena__find_file({ file_mask: "*.config.*", relative_path: "." })
   ```end

   ### Project-Specific Symbol Patterns
   - **Vue Components**: Use `find_symbol("ComponentName/setup")` for Composition API
   - **Legacy JS (public/js/)**: Use `search_for_pattern` for function literals
   - **Services**: Use `find_symbol("*Service/*")` for service methods
   - **Event Handlers**: Use `find_symbol` with patterns like "handle*", "on*"

   ### Serena Tool Priority
   1. **For symbol/function search**: Always try `find_symbol` first
   2. **For text/string search**: Use `search_for_pattern`
   3. **For multiple replacements**: Use `replace_regex` when changing 3+ similar patterns

   ## First Session Memory Creation
   On first project interaction, create these Serena memories:
   - `project_structure.md`: Directory layout and file purposes
   - `symbol_patterns.md`: Project naming conventions
   - `tech_stack.md`: Technologies and configurations

対象ファイルの比率が必ずしも同一とは言えませんが、変更後の影響としては以下の通り。

  • mcp__serena__check_onboarding_performed - 1回
  • mcp__serena__read_memory - 2回
  • mcp__serena__search_for_pattern - 8回
  • mcp__serena__replace_regex - 19回

検索用ファイルパス最適化

Claude及びSerenaのコマンド実行結果がexceeds maximum allowed tokens (25000)となって進まないシーンの対処としては検索用のファイルパスを絞ることです。

serenaによるファイル検索向けに、JSとCSSのディレクトリを設置して検索パスの効率化を図るのはToken節約になる?

再構成案と、どの程度節約できるのか、具体的なメリットと効果に応じた段階的プロセスを提案を提案されるので、それを実施するかどうかになります。

かなりの長文レポートを出されたので幾つかピックアップすると以下の通り。

// 現在(非効率)
mcp__serena__search_for_pattern({
	substring_pattern: "Tagify",
	relative_path: "src"
})//90ファイルをスキャン

// 分離後(効率的)
mcp__serena__search_for_pattern({
	substring_pattern: "Tagify",
	relative_path: "src/scripts"
})//30ファイルのみスキャン

概算では以下の数字を提示されました。

操作 現在のToken数 分離後Token数 節約率
JS検索 〜15,000 〜5,000 67%
CSS検索 〜12,000 〜4,000 67%
混合検索 〜25,000 〜8,000 68%

CSSの定義共通化によるtokenの消費節約

恐らく意識して整理しないとTokenが持っていかれるであろう一番の要因でしょう。Serenaのsearch処理は問題なく動くのですが、検索結果量が過剰になりすぎてClaudeが消費Token過多となりほぼ使えません。

生成されたCSSを見ると気がつくかもしれませんが、特にルール付けのないまま指示をおこなうと、類義語やClass名を構成している単語の順番が違う等色々なパターンが出来あがります。

CSSの無理のない定義共通化によるtokenの消費量節約概算をして

試算させてみると、今回は以下の通り。

  • 現在: 重複検索で平均12,000 tokens/セッション
  • 共通化後: 変数参照で平均800 tokens/セッション
  • 節約効果: 約93%のtoken削減

共通化しない場合、Max 100プランにしていても枯渇するまでそこまで掛からないはずです。

改善提案された内容は以下3段階。3段階目はMCPサーバや外部ツール探しとなるため、まずは1段階〜2段階目といったところでしょう。

  • 🔥 Phase 1 - 高頻度値の変数化(即座に実装可能)
    • Border-radius 上位5値
    • Background-color 上位10値
    • Padding 上位8値
    • 期待効果: 80%のtoken節約
  • 🟡 Phase 2 - ユーティリティクラス導入
    • よく使用される組み合わせのクラス化
    • 期待効果: さらに10%のtoken節約
  • 🟢 Phase 3 - 段階的置換
    • 各CSSファイルの段階的更新
    • 自動化ツールの導入検討

あとがき

記事中のチューニング指示を実施する際は、事前にSerenaを必ず導入してください。Serenaのコマンド経由で実行しない場合、Max 200プランであっても、すぐにTokenの上限に達してしまう可能性が高いでしょう。

この記事をシェアする

facebookのロゴhatenaのロゴtwitterのロゴ

© Classmethod, Inc. All rights reserved.