💻 Claude Code入門 📖 約22分で読めます

Claude Codeで既存プロジェクトを分析・理解する

新しいコードベースのオンボーディングをAIで加速

クロガイド｜Claude＆Claude Codeを無料で学ぼう

AI基礎からプロンプト術、Claude Codeの使い方まで。知識レッスンとクイズ式トレーニングで、AIスキルを段階的にアップ。ユーザー登録不要、すべて無料で今すぐ始められます。

新しいコードベースとの出会いを加速する

新しいプロジェクトに参加した際、コードベースを理解するまでに数日〜数週間かかることは珍しくありません。ドキュメントが不十分だったり、アーキテクチャが複雑だったりすると、さらに時間がかかります。Claude Codeを活用すれば、コードベースの構造把握、アーキテクチャの理解、データフローの追跡を対話的に進められ、オンボーディングを大幅に加速できます。

Claude Codeによるコードベース分析の5つの観点

プロジェクト構造: ディレクトリ構成、ファイルの役割、モジュール分割
アーキテクチャパターン: MVC、クリーンアーキテクチャ、マイクロサービス等の特定
データフロー: リクエストからレスポンスまでの処理の流れ
依存関係: ライブラリ、モジュール間の依存、外部サービス連携
技術的負債: コードの問題点、改善すべきポイントの洗い出し

実践1: プロジェクト構造の全体像を把握する

まず最初に、プロジェクト全体の構造を把握します。Claude Codeにディレクトリ構成を分析してもらい、各ディレクトリの役割を説明してもらいましょう。

プロジェクト構造の分析依頼

あなた: このプロジェクトの全体構造を分析してください。
- 主要なディレクトリの役割
- 使用しているフレームワーク・ライブラリ
- エントリーポイント
- 設定ファイルの場所
を教えてください。

Claude Code: プロジェクト構造を分析します。

[package.json, tsconfig.json, ディレクトリ構造を確認]

## プロジェクト概要
Next.js 14（App Router）+ TypeScriptのフルスタックアプリケーションです。

## ディレクトリ構成
src/
├── app/                    # Next.js App Router（ページ＆APIルート）
│   ├── (auth)/            # 認証関連ページ（グループルート）
│   ├── (dashboard)/       # ダッシュボード（認証必須）
│   ├── api/               # APIエンドポイント
│   └── layout.tsx         # ルートレイアウト
├── components/            # UIコンポーネント
│   ├── ui/               # 汎用UIコンポーネント（shadcn/ui）
│   ├── forms/            # フォームコンポーネント
│   └── layouts/          # レイアウトコンポーネント
├── lib/                   # ユーティリティ・設定
│   ├── prisma.ts         # Prismaクライアント
│   ├── auth.ts           # NextAuth設定
│   └── utils.ts          # ヘルパー関数
├── hooks/                 # カスタムフック
├── types/                 # TypeScript型定義
└── middleware.ts          # Next.jsミドルウェア（認証チェック）

## 使用ライブラリ（主要）
- Next.js 14.1, React 18, TypeScript 5.3
- Prisma 5.x（ORM）, PostgreSQL
- NextAuth.js v5（認証）
- shadcn/ui + Tailwind CSS（UI）
- React Hook Form + zod（フォーム＆バリデーション）
- TanStack Query v5（データフェッチ）

実践2: アーキテクチャパターンを特定する

プロジェクトがどのようなアーキテクチャパターンを採用しているかを理解することは、コードの読み方を決める上で非常に重要です。

アーキテクチャ分析の依頼

あなた: このプロジェクトのアーキテクチャパターンを分析してください。
- レイヤー構成（プレゼンテーション、ビジネスロジック、データアクセス等）
- 状態管理の方針
- データフェッチのパターン
- エラーハンドリングの方針
を教えてください。

Claude Code: アーキテクチャを分析します。

[主要ファイルを読み取り]

## アーキテクチャパターン

### レイヤー構成
このプロジェクトは3層アーキテクチャを採用しています。

1. プレゼンテーション層: app/, components/
   → Server Components + Client Componentsのハイブリッド
   → フォームはReact Hook Formで管理

2. ビジネスロジック層: lib/services/
   → 各ドメインごとにサービスクラスが存在
   → 例: UserService, ProjectService, TaskService

3. データアクセス層: lib/repositories/
   → Prismaを使ったリポジトリパターン
   → 各エンティティごとにリポジトリが存在

### 特徴的な設計判断
- Server Actionsを積極的に活用（フォーム送信）
- TanStack Queryでキャッシュ管理（クライアント側）
- zodスキーマをフロント/バック共有（lib/schemas/）
- エラーはカスタムAppErrorクラスで統一

実践3: 特定の機能のデータフローを追跡する

特定の機能（例: ユーザー登録、決済処理など）がどのように動作するかを追跡してもらうことで、コードの理解が深まります。

データフロー追跡の依頼テンプレート

あなた: 「ユーザーがタスクを作成する」機能のデータフローを
追跡してください。以下の観点で説明してください。

1. ユーザーがフォームに入力してから、DBに保存されるまでの流れ
2. 経由するファイル・関数の一覧
3. バリデーションが行われるタイミング
4. エラーハンドリングの箇所

Claude Code: タスク作成のデータフローを追跡します。

## データフロー: タスク作成

1. [UI] components/forms/TaskForm.tsx
   → React Hook Form + zodバリデーション
   → onSubmit → createTaskAction() を呼び出し

2. [Server Action] app/(dashboard)/tasks/actions.ts
   → createTaskAction(formData)
   → zodでサーバーサイドバリデーション
   → TaskService.create() を呼び出し

3. [Service] lib/services/taskService.ts
   → ビジネスロジック（権限チェック、ステータス初期化等）
   → TaskRepository.create() を呼び出し

4. [Repository] lib/repositories/taskRepository.ts
   → prisma.task.create() を実行
   → DB保存完了

5. [レスポンス] Server Action → revalidatePath()
   → タスク一覧ページが自動更新される

実践4: 依存関係の分析

プロジェクトが依存しているライブラリや外部サービスを把握することは、開発環境の構築やトラブルシューティングに不可欠です。

依存関係の分析依頼

あなた: このプロジェクトの依存関係を分析してください。
- 外部API・サービスとの連携一覧
- 環境変数で設定が必要なもの
- セットアップ時に特別な手順が必要なもの

Claude Code: 依存関係を分析します。

[package.json, .env.example, 設定ファイルを確認]

## 外部サービス連携
| サービス | 用途 | 環境変数 |
|---------|------|---------|
| PostgreSQL | メインDB | DATABASE_URL |
| Redis | セッション/キャッシュ | REDIS_URL |
| AWS S3 | ファイルアップロード | AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, S3_BUCKET |
| Stripe | 決済処理 | STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET |
| SendGrid | メール送信 | SENDGRID_API_KEY |
| Google OAuth | ソーシャルログイン | GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET |

## セットアップ手順（推奨）
1. .env.example → .env にコピー
2. PostgreSQL/Redis をDockerで起動: docker-compose up -d
3. Prismaマイグレーション: npx prisma migrate dev
4. シードデータ: npx prisma db seed
5. 開発サーバー: npm run dev

実践5: 技術的負債の発見

既存プロジェクトには、時間の経過とともに蓄積された技術的負債が存在することがほとんどです。Claude Codeに分析を依頼して、優先的に対処すべき問題を特定しましょう。

技術的負債の調査依頼

あなた: このプロジェクトの技術的負債を分析してください。
以下の観点でチェックしてください。
- 非推奨API・古いパターンの使用
- 重複コード
- テストカバレッジの低い箇所
- セキュリティ上の懸念
- パフォーマンスの問題

Claude Code: 技術的負債を分析します。

[主要ファイルを網羅的に読み取り]

## 技術的負債レポート

### 高優先度（すぐに対応すべき）
1. **SQL注入の脆弱性** (lib/legacy/queries.ts:45)
   → テンプレートリテラルで直接SQLを構築している箇所がある
   → Prismaのクエリビルダーに移行すべき

2. **APIキーのハードコーディング** (lib/email.ts:12)
   → SendGridのAPIキーが直接コードに書かれている
   → 環境変数に移動すべき

### 中優先度（計画的に対応）
3. **重複コード** (components/forms/ 内)
   → TaskForm, ProjectForm, UserForm でバリデーションロジックが重複
   → 共通のフォームファクトリー関数に抽出可能

4. **非推奨API使用** (pages/ ディレクトリ)
   → Pages Routerの古いページが5ファイル残っている
   → App Routerに移行すべき

### 低優先度（余裕があるときに対応）
5. **TypeScript any型の多用** (46箇所)
   → 特にAPI レスポンスの型定義が不十分
   → zodスキーマから型を推論する方式に統一すべき

オンボーディングドキュメントの自動生成

分析結果をもとに、新メンバー向けのオンボーディングドキュメントを生成してもらうことも可能です。

ドキュメント生成の依頼例

あなた: これまでの分析結果をもとに、新しいチームメンバー向けの
オンボーディングドキュメントを作成してください。
以下を含めてください。
- プロジェクト概要と技術スタック
- ディレクトリ構成と各ディレクトリの責務
- 開発環境のセットアップ手順
- アーキテクチャの概要図（Mermaid形式）
- 主要な機能のデータフロー
- コーディング規約とベストプラクティス
- 知っておくべき注意点や落とし穴

Mermaidダイアグラムの活用

Claude Codeは、コードベースの分析結果をMermaid形式のダイアグラムで出力できます。視覚的な理解を助けるために積極的に活用しましょう。

アーキテクチャ図の生成依頼

あなた: このプロジェクトのアーキテクチャ図をMermaid形式で
生成してください。

Claude Code:

```mermaid
graph TB
    subgraph Frontend
        A[Next.js App Router] --> B[Server Components]
        A --> C[Client Components]
        C --> D[TanStack Query]
        C --> E[React Hook Form]
    end

    subgraph Backend
        F[API Routes] --> G[Services]
        H[Server Actions] --> G
        G --> I[Repositories]
        I --> J[(PostgreSQL)]
    end

    subgraph External
        K[Stripe API]
        L[SendGrid]
        M[AWS S3]
    end

    B --> F
    D --> F
    E --> H
    G --> K
    G --> L
    G --> M
```

このダイアグラムをREADME.mdに追加すると、
新メンバーの理解が早まります。

分析の進め方 ― 効率的なプロンプト戦略

フェーズ	所要時間	やること	主なプロンプト
全体把握	30分	構造・技術スタック確認	「プロジェクト全体の構造を分析して」
設計理解	1時間	アーキテクチャ・パターン特定	「アーキテクチャパターンを分析して」
機能理解	2時間	主要機能のデータフロー追跡	「〇〇機能のデータフローを追跡して」
課題把握	1時間	技術的負債・改善点の洗い出し	「技術的負債を分析して」
文書化	30分	オンボーディングドキュメント生成	「オンボーディングドキュメントを作成して」

プロのヒント: 大規模なコードベースを分析する際は、一度にすべてを理解しようとせず、「まず全体像、次に担当する機能の詳細」という順序で進めましょう。Claude Codeは会話の文脈を維持するため、段階的に質問を深めていく対話スタイルが最も効果的です。CLAUDE.mdにプロジェクトの概要を記述しておくと、分析の精度がさらに向上します。