codanna-codebase-intelligence

Codanna コードベースインテリジェンス

Codanna はコードベースをインデックス化し、MCP ツールを通じてセマンティック検索、呼び出しグラフ、依存関係分析を提供します。grep/find を使う前に codanna を使用してください。単なるテキストパターンではなく、コード構造を理解します。

使用する場面

• コードを探す：「認証はどこで処理していますか？」→ semantic_search_docs
• 依存関係を理解する：「この関数を呼び出しているのは何ですか？」→ find_callers
• 影響を分析する：「これを変更すると何が壊れますか？」→ analyze_impact
• シンボルを調べる：「Parser 構造体を見せてください」→ find_symbol

コアツール

検出

# Natural language search - finds code by intent, not keywords
semantic_search_docs query:"error handling patterns" limit:5

# Search symbols by name/pattern
search_symbols query:"parse" kind:"function"

# Get full details on a specific symbol
find_symbol name:"process_file"

関係

# Who calls this function? (upstream)
find_callers symbol:"validate_input"

# What does this function call? (downstream)
get_calls symbol:"process_request"

# Full dependency graph - what breaks if I change this?
analyze_impact symbol:"DatabaseConnection" depth:3

ドキュメント（RAG）

# Search indexed markdown/docs
search_documents query:"API authentication" collection:"docs"

ツール選択ガイド

タスク	ツール	例
概念からコードを探す	semantic_search_docs	「データベースのマイグレーション」
名前からシンボルを探す	search_symbols	パターン：「auth*」
シンボルの詳細を取得する	find_symbol	完全一致：「UserService」
呼び出し元を追跡する	find_callers	「これを使っているのは誰ですか？」
依存関係を追跡する	get_calls	「これが呼び出すのは何ですか？」
リファクタリングのリスクを評価する	analyze_impact	「何が壊れますか？」

ワークフローパターン

リファクタリングの前に

1. find_symbol - 現在の実装を理解する
2. find_callers - すべての使用箇所を特定する
3. analyze_impact - 影響範囲を評価する
4. その後、変更を進める

不慣れなコードを理解する

1. semantic_search_docs - 「X の仕組み」
2. find_symbol - エントリーポイントの詳細を取得する
3. get_calls - 実行フローを追跡する

コードを追加する場所を探す

1. semantic_search_docs - 「類似するパターン」
2. find_callers - 既存コードがどのように連携しているかを確認する
3. 確立されたパターンに従う

Grep より Codanna を使う理由

Grep/Find	Codanna
テキストの一致	セマンティックな理解
文字列「parse」はコメントにも一致する	find_symbol は実際の関数を見つける
手動で呼び出しを追跡する	find_callers は完全なグラフを表示する
影響を推測する	analyze_impact は依存関係を表示する

Agent-Loops との連携

Codanna は、差分ベースのレビューだけでは得られない構造的なコードインテリジェンスを提供し、agent-loops のレビュー ワークフローを補完します。

レビュー前の影響分析

specialist-review.sh を呼び出す前に、codanna を実行して変更の影響範囲を把握してください。これにより、根拠のある構造データがレビューに反映され、レビュー担当者は差分から推測するのではなく、実際の下流への影響に注目できます。

# Gather impact data for changed symbols
codanna mcp find_callers process_request --watch
codanna mcp analyze_impact DatabaseConnection --watch --json

複数の専門家によるレビューのサポート

複数の専門家によるレビューアーキテクチャ（docs/development/plans/multi-specialist-review.md を参照）では、専門家は根拠のある分析のために Read/Grep/Glob と併せて codanna ツールを使用できます。影響データは専門家のトリアージにも活用できます。コードベースのどの部分が構造的な影響を受けるかに基づいて、どのレビュー観点を有効にするかを判断できます。

インデックスの自動更新

CLI コマンドの --watch フラグは、ファイルの変更を確認し、実行前に再インデックス化するため、手動で再インデックス化しなくてもレビューセッション中に影響データを最新の状態に保てます。MCP サーバーに相当するコマンド（codanna serve --watch）も、インタラクティブセッションで同様に最新の状態を保証します。

ヒント

• semantic_search_docs で広く検索してから、find_symbol で詳細を調べます
• 共有コードに触れるリファクタリングの前には、analyze_impact を使用します
• find_callers で深さを 1 より大きくすると、推移的な呼び出し元も表示されます
• 結果にはファイルパスと行番号が含まれます。ナビゲーションに活用してください