はじめに

新しいプロジェクトに参画したとき、最初にぶつかる壁は「コードベースの理解」です。ドキュメントが不十分だったり、既存メンバーが多忙で質問しづらかったり、そもそも何を質問すればよいかわからないこともあります。

Claude Codeは、このオンボーディングの課題を解決する強力なツールです。公式サイトでは以下のように説明されています。

Claude Code maps and explains entire codebases in a few seconds. It uses agentic search to understand project structure and dependencies without you having to manually select context files.

本記事では、Claude Codeを使って新しいプロジェクトへ素早くキャッチアップするための実践的なテクニックを解説します。この記事を読むことで、以下のことができるようになります。

  • プロジェクト全体の構造とアーキテクチャを短時間で把握する
  • コードベースに関する的確な質問を行い、理解を深める
  • 依存関係やファイル間の関連性を効率的に調査する
  • ドメイン固有の用語やビジネスロジックを理解する

実行環境

  • オペレーティングシステム: macOS 10.15以上、Ubuntu 20.04以上/Debian 10以上、Windows 10以上（WSL 1/2またはGit for Windows）
  • ハードウェア: 4GB以上のRAM
  • Node.js 18以上（npmインストールの場合のみ必要）
  • インターネット接続（認証およびAI処理に必要）
  • シェル環境: Bash、Zsh、またはFish推奨

前提条件

  • コマンドライン操作の基礎知識
  • Gitの基本操作（clone、commit、push等）
  • プログラミングの基礎知識（言語は問わない）
  • Claude.aiまたはAnthropic Consoleアカウント
  • Claude Codeのインストールと認証が完了していること

コードベース理解のワークフロー

新しいプロジェクトのコードベースを理解する際は、以下の順序で進めることを推奨します。

flowchart TD
    A[プロジェクトをクローン] --> B[Claude Codeを起動]
    B --> C[プロジェクト全体の概要を質問]
    C --> D[ディレクトリ構造の理解]
    D --> E[アーキテクチャパターンの把握]
    E --> F[主要コンポーネントの関係性を理解]
    F --> G[ドメイン用語・ビジネスロジックの確認]
    G --> H[特定機能の実装詳細を調査]

このワークフローに沿って、各ステップでの具体的なClaude Codeの活用方法を解説していきます。

プロジェクト全体の概要を把握する

新しいプロジェクトに参画したら、最初にプロジェクトの全体像を把握することが重要です。Claude Codeのエージェンティックサーチ機能を使えば、数秒でコードベース全体をスキャンし、概要を説明してもらえます。

基本的な概要の質問

まず、プロジェクトディレクトリに移動してClaude Codeを起動します。

1
2

cd your-project
claude

起動したら、シンプルにプロジェクトの概要を質問します。

1

> このプロジェクトの概要を説明してください。何を目的としたアプリケーションで、どのような技術スタックを使用していますか？

Claude Codeはプロジェクト全体をスキャンし、以下のような情報を提供してくれます。

  • プロジェクトの目的と主要機能
  • 使用している言語、フレームワーク、ライブラリ
  • プロジェクトの規模感（ファイル数、コード行数など）
  • 依存関係の概要

より詳細な概要を得る

技術的な深掘りが必要な場合は、具体的な観点を指定して質問します。

1
2
3
4
5

> このプロジェクトについて、以下の観点から詳しく教えてください：
> 1. 主要な機能と責務
> 2. 使用しているフレームワークとそのバージョン
> 3. 外部サービスやAPIとの連携
> 4. ビルドとデプロイの仕組み

README.mdがない・不十分な場合

ドキュメントが不足しているプロジェクトでも、Claude Codeはコードから情報を推測できます。

1

> README.mdが見当たりません。コードを分析して、このプロジェクトの概要ドキュメントを作成してください。

この質問により、Claude Codeがコードベースを分析し、README.mdの下書きを生成してくれます。生成されたドキュメントは、自分自身の理解を確認するためにも、チームへの共有にも活用できます。

ディレクトリ構造の理解

プロジェクトの概要を把握したら、次はディレクトリ構造を理解します。ディレクトリ構造はプロジェクトの設計思想を反映しており、コードの配置ルールを理解することで、必要なファイルを素早く見つけられるようになります。

ディレクトリ構造の説明を依頼

1

> このプロジェクトのディレクトリ構造を説明してください。各ディレクトリの役割と、どのようなファイルが配置されているかを教えてください。

Claude Codeは、以下のような構造化された回答を返してくれます。

  • トップレベルディレクトリの役割
  • 各サブディレクトリの責務
  • 設定ファイルやビルド関連ファイルの配置

特定のディレクトリについて深掘り

特に重要なディレクトリについては、さらに詳しく質問できます。

1

> @src/components/ ディレクトリの構成について詳しく教えてください。コンポーネントはどのような方針で分類されていますか？

@記法を使用することで、特定のディレクトリやファイルを明示的に参照できます。これにより、Claude Codeは該当ディレクトリの内容を確実にコンテキストに含めて回答します。

設定ファイルの理解

プロジェクトには様々な設定ファイルが存在します。それぞれの役割を把握しておくと、環境構築やトラブルシューティングが容易になります。

1

> プロジェクトルートにある設定ファイル（.env、tsconfig.json、package.json等）の役割と、主要な設定項目を説明してください。

アーキテクチャパターンを理解する

プロジェクトのアーキテクチャを理解することは、コードの全体像を把握し、新機能の実装やバグ修正を効率的に行うために不可欠です。

採用されているアーキテクチャの質問

1

> このプロジェクトで採用されているアーキテクチャパターンを教えてください。レイヤー構成、データフロー、主要なデザインパターンについて説明してください。

Claude Codeは、コードベースを分析して以下のような情報を提供します。

  • 全体的なアーキテクチャスタイル（MVC、Clean Architecture、Hexagonal等）
  • レイヤー間の依存関係
  • 採用されているデザインパターン（Repository、Factory、Observer等）

データフローの可視化

アプリケーションのデータフローを理解することは重要です。

1

> ユーザーがログインする際のデータフローを説明してください。リクエストがどのように処理され、どのコンポーネントを通過するか、図で示してください。

Claude Codeは、Mermaid記法でシーケンス図やフローチャートを生成してくれます。

1

> APIリクエストが処理される一般的なフローをシーケンス図で示してください。

生成された図の例：

sequenceDiagram
    participant Client as クライアント
    participant Controller as コントローラー
    participant Service as サービス層
    participant Repository as リポジトリ
    participant DB as データベース

    Client->>Controller: HTTPリクエスト
    Controller->>Service: ビジネスロジック呼び出し
    Service->>Repository: データアクセス
    Repository->>DB: クエリ実行
    DB-->>Repository: 結果返却
    Repository-->>Service: エンティティ返却
    Service-->>Controller: 処理結果
    Controller-->>Client: HTTPレスポンス

状態管理の理解

フロントエンドアプリケーションの場合、状態管理の仕組みを理解することが重要です。

1

> このアプリケーションの状態管理はどのように実装されていますか？グローバルステート、ローカルステート、サーバーステートの管理方法を説明してください。

関連ファイルの検索と依存関係の理解

特定の機能やモジュールに関連するファイルを効率的に見つけ、それらの依存関係を理解することは、コードの変更影響範囲を把握するために重要です。

機能に関連するファイルの検索

特定の機能を実装しているファイルを見つけたい場合は、機能名や概念を指定して検索できます。

1

> ユーザー認証に関連するすべてのファイルを一覧で教えてください。各ファイルの役割も簡潔に説明してください。

1

> 決済処理のロジックはどこに実装されていますか？関連するファイルとその依存関係を教えてください。

モジュール間の依存関係を調査

1

> @src/services/UserService.js がインポートしているモジュールと、このファイルをインポートしているモジュールを教えてください。

Claude Codeは、ファイルの依存関係を分析し、以下のような情報を提供します。

  • インポートしているモジュール（依存先）
  • インポートされているモジュール（依存元）
  • 循環参照の有無

依存関係図の生成

複雑な依存関係を理解するために、図で可視化することもできます。

1

> @src/modules/ 配下のモジュール間の依存関係を図で示してください。

生成される依存関係図の例：

graph TD
    A[UserModule] --> B[AuthModule]
    A --> C[DatabaseModule]
    B --> C
    D[OrderModule] --> A
    D --> E[PaymentModule]
    E --> C

変更影響範囲の調査

既存のコードを修正する前に、影響範囲を把握しておくことが重要です。

1

> @src/utils/dateFormatter.js を修正した場合、影響を受ける可能性があるファイルを教えてください。

ドメイン用語の解説を依頼する

業務システムやドメイン固有の知識が必要なプロジェクトでは、コード内で使用されている専門用語やビジネスロジックを理解することが重要です。

用語集の作成を依頼

1

> このプロジェクトで使用されているドメイン固有の用語（変数名、クラス名、関数名など）をリストアップし、それぞれの意味を説明してください。

Claude Codeは、コード内で使用されている専門用語を分析し、用語集を作成してくれます。例えば：

用語 説明
SKU Stock Keeping Unit（在庫管理単位）。商品を一意に識別するコード
Fulfillment 注文の受注から配送完了までのプロセス
Backorder 在庫切れ時の入荷待ち注文

特定の概念の詳細説明

特定のドメイン概念について深く理解したい場合は、具体的に質問します。

1

> このプロジェクトにおける「サブスクリプション」の概念を説明してください。どのようなデータ構造で管理され、どのような状態遷移がありますか？

ビジネスルールの理解

1

> 注文のキャンセルに関するビジネスルールを教えてください。どのような条件でキャンセルが可能/不可能で、キャンセル時にどのような処理が行われますか？

Claude Codeは、コード内のバリデーションロジックやワークフローを分析して、ビジネスルールを説明してくれます。

命名規則の理解

プロジェクトの命名規則を理解することで、コードの一貫性を保ちながら新機能を実装できます。

1

> このプロジェクトの命名規則を教えてください。変数名、関数名、クラス名、ファイル名、ディレクトリ名のそれぞれについて、どのような規則が使われていますか？

特定機能の実装詳細を調査する

プロジェクトの全体像を把握したら、具体的な機能の実装詳細を調査していきます。

機能の実装場所を特定

1

> ファイルアップロード機能はどこに実装されていますか？エントリーポイントから処理の流れを追って説明してください。

コードの詳細説明を依頼

特定のファイルやクラスについて、詳細な説明を依頼できます。

1

> @src/services/NotificationService.js の実装を詳しく説明してください。各メソッドの責務と、使用しているデザインパターンを教えてください。

複雑なロジックの解説

理解が難しい複雑なロジックについては、段階的に説明を依頼します。

1

> @src/utils/pricing.js のcalculateDiscount関数のロジックを、入力から出力までステップバイステップで説明してください。

テストコードから仕様を理解

テストコードは、機能の仕様を理解するための優れた資料です。

1

> @src/services/__tests__/OrderService.test.js を分析して、OrderServiceがどのような振る舞いを期待されているか説明してください。

Plan Modeの活用

コードベースを理解する際は、意図しない変更を避けるためにPlan Modeを活用することを強く推奨します。

Plan Modeとは

Plan Modeは読み取り専用のモードで、Claude Codeがコードを分析して計画を立てることはできますが、実際のファイル編集やコマンド実行は行いません。

Plan Modeへの切り替え

Shift+Tabキーでモードを切り替えることができます。現在のモードはプロンプトに表示されます。

1

> [Plan Mode] このプロジェクトの認証フローを分析して、セキュリティ上の懸念点があれば指摘してください。

Plan Modeの利点

コードベース理解のフェーズでPlan Modeを使用する利点は以下の通りです。

  • 意図しないファイル変更を防止できる
  • 安全にコードを調査できる
  • 分析に集中できる

通常の開発作業に移行する際は、再度Shift+TabでAccept ModeまたはAuto-Accept Modeに切り替えます。

効果的な質問のテクニック

Claude Codeから的確な回答を得るためには、質問の仕方も重要です。

コンテキストを明確に伝える

1
2
3
4
5
6
7
8
9

# 悪い例
> 認証はどうなってる？

# 良い例
> このプロジェクトのユーザー認証の仕組みを教えてください。
> 特に以下の点について知りたいです：
> 1. 認証方式（JWT、セッション等）
> 2. 認証の有効期限と更新の仕組み
> 3. 権限管理の実装

段階的に深掘りする

一度に多くの情報を求めるのではなく、段階的に質問を重ねていきます。

1
2
3
4
5
6
7
8

# ステップ1: 全体像の把握
> このプロジェクトのAPI設計について概要を教えてください。

# ステップ2: 特定領域の深掘り
> API認証の仕組みについて詳しく教えてください。

# ステップ3: 具体的な実装の確認
> @src/middleware/auth.js の実装を説明してください。

比較を活用する

類似の概念との比較を依頼すると、理解が深まります。

1

> このプロジェクトのUserServiceとAccountServiceの違いは何ですか？それぞれの責務と使い分けを説明してください。

オンボーディングチェックリスト

新しいプロジェクトに参画した際のオンボーディングで確認すべき項目をチェックリストとしてまとめます。

基本情報の確認

  • プロジェクトの目的と主要機能を理解したか
  • 使用技術スタック（言語、フレームワーク、ライブラリ）を把握したか
  • 開発環境のセットアップ手順を確認したか
  • ビルド・デプロイの仕組みを理解したか

アーキテクチャの理解

  • ディレクトリ構造とファイル配置のルールを把握したか
  • 採用されているアーキテクチャパターンを理解したか
  • 主要コンポーネント間の依存関係を把握したか
  • データフローの概要を理解したか

ドメイン知識の習得

  • 主要なドメイン用語の意味を理解したか
  • ビジネスルールの概要を把握したか
  • 命名規則とコーディング規約を確認したか

開発プロセスの確認

  • ブランチ戦略とマージルールを把握したか
  • コードレビューのプロセスを理解したか
  • テスト戦略と実行方法を確認したか
  • CI/CDパイプラインの概要を理解したか

これらの項目をClaude Codeに質問しながら確認していくことで、効率的にオンボーディングを進められます。

理解した内容を記録する

Claude Codeとの対話で得た知識は、将来の参照や他のメンバーへの共有のために記録しておくことをお勧めします。

CLAUDE.mdへの記録

プロジェクトのCLAUDE.mdファイルに、自分が学んだ内容を追記していくことができます。

1

> /memory

/memoryコマンドでCLAUDE.mdを開き、以下のような情報を追記します。

  • プロジェクト固有の用語集
  • 重要なアーキテクチャ決定の記録
  • よくある質問とその回答

セッションの保存

重要な調査セッションには名前を付けて保存しておきましょう。

1

> /rename architecture-investigation

後日、このセッションを再開して、続きの調査を行うことができます。

1

claude -r "architecture-investigation"

まとめ

本記事では、Claude Codeを活用して新しいプロジェクトのコードベースを効率的に理解する方法を解説しました。

主なポイントは以下の通りです。

  • プロジェクト概要からディレクトリ構造、アーキテクチャへと段階的に理解を深める
  • @記法で特定のファイルやディレクトリを参照し、的確なコンテキストを提供する
  • Plan Modeを活用して、安全にコードベースを調査する
  • ドメイン用語やビジネスロジックについても積極的に質問する
  • 得た知識をCLAUDE.mdやセッションとして記録する

Claude Codeのエージェンティックサーチ機能により、手動でファイルを探し回る時間を大幅に削減できます。新しいプロジェクトへの参画時だけでなく、長期間触れていなかったコードベースに戻る際にも、これらのテクニックは有効です。

次のステップとして、Claude CodeのPlan Mode、Accept Mode、Auto-Accept Modeの使い分けについて学ぶことをお勧めします。状況に応じたモード選択により、安全かつ効率的に開発作業を進められるようになります。

参考リンク