🔍

【Claude Code活用】コードベース探索を任せる

に公開
AI
開発ツール
Claude
Claude Code
tech

Claude Code の探索能力

Claude Code はコードベース全体を把握してから作業を開始する習慣を持っています。

典型的な探索の流れは次のとおりです。

list_files（ディレクトリ構造の把握）
  ↓
read_file（関連ファイルの内容確認）
  ↓
search（キーワード・パターン検索）
  ↓
実装

この流れを指示しなくても自発的に行うため、「既存コードと一貫したスタイルで新しいコードを書く」という作業を自然に実行できます。

実際に任せてみた：既存コードを読んで実装する

agent01 の Step 06 では search_text（grep 相当のツール）を実装しました。

Claude Code は実装前に src/tools/file_tools.py を読み込み、同じコーディングスタイルで src/tools/search_tools.py を生成しました。具体的には以下の点が自動的に統一されました。

  • EXCLUDE_DIRS の定数定義パターン
  • Path を使ったパス操作
  • エラー時の戻り値形式（f"エラー：..." 形式）
  • docstring のスタイル（Google スタイル）
src/tools/search_tools.py
def search_text(
    query: str,
    directory: str,
    file_pattern: str = "",
) -> str:
    """ディレクトリを横断してキーワード検索する。

    Args:
        query: 検索するキーワードまたは正規表現
        directory: 検索対象のディレクトリパス
        file_pattern: 対象ファイルの拡張子フィルタ（例：".py"、空文字で全ファイル）

    Returns:
        検索結果（"ファイル:行番号: 行内容" 形式）。
        見つからない場合はその旨のメッセージ。
    """
    # ...
    results.append(f"{rel_path}:{line_num}: {line.strip()}")

file_tools.py に合わせて EXCLUDE_DIRS を定数として定義し、結果形式も ファイル:行番号: 行内容 と統一されています。

CLAUDE.md による探索の効率化

CLAUDE.md にはコーディング規約が記載されています。

CLAUDE.md
## コーディング規約

### 基本方針
- Python 3.11以上の構文を使用する
- 型アノテーションを必ず付ける
- docstringはGoogleスタイルで記述する
- 1ファイル1クラスを基本とする

### 命名規則
- 関数名・変数名：snake_case（例：`read_file`）
- 定数：UPPER_SNAKE_CASE（例：`DEFAULT_MODEL`）

この規約を CLAUDE.md に書いておくことで、Claude Code は最初に CLAUDE.md を読み、以降の実装でこの規約を遵守しました。「既存コードを参照してから書く」という探索フローと組み合わせることで、プロジェクト全体の一貫性が自然に保たれます。

気づき

「まず読んでください」の一言が重要：セッション開始時に「PROGRESS.md と AGENT_SPEC.md を読んでください」と伝えるだけで、Claude Code はプロジェクトの文脈を素早く把握します。この一言がないと、既存の設計を無視した実装が生成されることがありました。

長いセッションは新規セッションに分けた方が精度が上がる：1セッションで多くの作業を行うと、コンテキストが長くなり応答精度が落ちることがあります。Step 単位でセッションを区切り、毎回「PROGRESS.md を読む」ところから始める運用が安定していました。

探索の副産物として設計ミスが発覚する：Claude Code が既存コードを読む過程で、設計上の矛盾（ツール名の表記揺れなど）を指摘してくれることがありました。これはコードレビューの副次効果として有益でした。

まとめ

Claude Code は自発的にコードベースを探索してから実装します。CLAUDE.md に規約を書いておくことで、探索結果を活かした一貫したコードを生成できます。「読んで・理解して・書く」というサイクルを自動で回してくれるため、既存コードとのスタイル不一致が起きにくくなります。

次回

B4 では、Claude Code の差分確認・適用フローについて紹介します。既存ファイルを壊さずに変更を加えた体験をお伝えします。

シリーズリンク（Series B）

記事 タイトル
B1 Claude Codeとは・導入と初期設定
B2 ファイル読み書きを任せる
B3 コードベース探索を任せる（本記事）
B4 差分確認・適用を任せる
B5 テスト実行と結果解釈を任せる
B6 複数ファイル跨ぎの修正を任せる
B7 PROGRESS.md駆動開発
B8 Zenn記事をClaude Codeに書かせる

Discussion