Claude Code の動作検証と本体への質問でわかった実用的な設定

Posted at 2025-06-04

Claude Code は、Anthropic が提供する公式 CLI ツールです。ソフトウェア開発タスクを効率的に実行するためのインタラクティブなコマンドラインインターフェースを提供します。

この記事では、実際に Claude Code を使用した動作検証と、Claude Code 本体への質問を通じて得られた知見をまとめています。特に CLAUDE.md の自動読み込みの挙動、ファイルフォーマットチェックの制限、大規模プロジェクトでの効率的な活用方法など、公式ドキュメントには載っていない実践的な情報を共有します。なお、この記事自体も Claude Code を使って執筆・編集されています。

プロジェクト設定ファイル（CLAUDE.md）の活用

Claude Code では、プロジェクトのルートディレクトリに CLAUDE.md ファイルを作成することで、プロジェクト固有の設定やルールを定義できます。

一般的な設定項目

# プロジェクト設定

## 開発環境
- Node.js バージョン: 18.x
- パッケージマネージャー: npm
- テストフレームワーク: Jest

## コーディング規約
- インデント: スペース2個
- セミコロン: 必須
- クォート: シングルクォート

## コマンド
- ビルド: npm run build
- テスト: npm test
- リント: npm run lint

ファイル形式の設定

プロジェクトでは以下のファイル形式ルールを適用：

## ファイル作成・編集ルール

### 改行コード
- ファイルの終端は必ずLF（\n）にする
- 既に終端がLFの場合は追加しない（重複を避ける）
- これはすべてのテキストファイル（.md、.js、.ts、.py等）に適用する

### フォーマット
- 空白だけの行は改行文字のみにする（空白文字を含めない）
- 文章の末尾の空白は削除する
- 行末に不要な空白文字を残さない

Claude Code でのファイル形式チェック

チェック方法と制限:

Read ツール: ファイル読み込み時に No newline at end of file 等の警告で確認
事後確認: Edit/MultiEdit 実行後にしか結果を確認できない
リアルタイムチェック不可: 編集途中でのプレビューやフォーマット確認機能はない

推奨ワークフロー:

# 事前チェック方式
"ファイルを読み込んで末尾空白や改行の問題を確認して"
→ 問題箇所を特定してから編集

# 外部コマンドによる一括処理
sed -i 's/[[:space:]]*$//' ファイル名  # 末尾空白削除
echo >> ファイル名  # 末尾LF追加（既存LFがある場合は要注意）

# 段階的編集
"小さな変更を行って結果を確認" → "次の変更を実行"

ファイル・ディレクトリ管理とフォーマット設定

プロジェクトで一貫性を保つため、自動チェック機能とファイル管理ルールを設定できます。

設定サンプル（クリックで展開）

## 自動フォーマットチェック

### ファイル編集時のチェック
- ファイル編集時に該当ファイルのみフォーマットチェックを実行する
- 違反があれば自動修正してから編集を開始する
- 全ファイル一括チェックは実行しない

### チェック・修正コマンド
# 末尾空白の削除
sed -i 's/[[:space:]]*$//' ファイル名

# 末尾LFのチェック（戻り値1=LFあり、0=LFなし）
tail -c 1 ファイル名 | wc -l

# 末尾LFがない場合のみ追加
[ $(tail -c 1 ファイル名 | wc -l) -eq 0 ] && echo >> ファイル名

### 次回セッションでの実行
- 新規セッション開始時に「CLAUDE.mdを読んで」と明示的に指示する
- CLAUDE.mdを読み込んだ時点で、フォーマットルールを認識
- ファイル編集時に該当ファイルのみチェック・修正を実行
- チェック結果をユーザーに報告

## ファイル・ディレクトリ管理ルール

### 解析結果の記録・整理
- プロジェクト解析結果はCLAUDE.mdに追記する
- ファイル数やサイズを考慮して、適切な構成を判断する

### 整理方法（Claude に委ねる）
#### ファイル分割
- CLAUDE_ANALYSIS.md: 詳細解析結果
- CLAUDE_HISTORY.md: 作業履歴
- その他必要に応じて適切なファイル名で作成

#### ディレクトリ分割（ファイルが多い場合）
- docs/claude/ または claude-docs/ ディレクトリを作成
- 関連ファイルを配下に整理（隠しディレクトリは使用しない）
- 例: docs/claude/analysis/, docs/claude/history/

### 判断基準（Claude が自動判断）
- CLAUDE.mdの読み込み効率
- ファイル数の増加
- 検索性・保守性の向上
- チーム全体での情報共有

### 整理実行の指示
- "必要に応じてファイル・ディレクトリ構成を最適化してください"
- "Claude関連ファイルを適切に整理してください"

重要：CLAUDE.mdの読み込みについて

実際のテスト結果（2025年6月4日時点）:

新規セッション開始時の動作が一定しない
4回のテストで動作にばらつきがある：
- 1回目：CLAUDE.mdを自動読み込みしなかった
- 2-4回目：読んだり読まなかったりと結果が異なる
- CLAUDE.md読み込みの出力なしに、フォーマットチェックが実行されるケースもあり
- 実行されるコマンドもセッションにより異なる：
  - 条件付きLF追加: [ $(tail -c 1 file | wc -l) -eq 0 ] && echo >> file
  - 条件なしLF追加: echo >> file

現在の推奨対応:

# 確実にCLAUDE.mdを読み込ませる方法
"CLAUDE.mdを読んで、このプロジェクトの設定を理解してください"

# 設定が適用されているか確認
"フォーマットルールが適用されているかチェックして"

注意事項:

CLAUDE.mdの読み込み動作にばらつきがある
重要なプロジェクトでは明示的な読み込み指示を推奨
動作は将来のアップデートで改善される可能性がある

大規模プロジェクトでの活用

数十万行コードベースでの効率的な使い方

大規模な既存プロジェクトで Claude Code を活用する際の段階的なアプローチ：

1. プロジェクト理解フェーズ

# プロジェクト構造を把握
"プロジェクトの全体構造を教えて"
"主要なディレクトリとファイルの役割を説明して"

2. 局所的な調査・修正

# 特定機能の調査
"ユーザー認証部分のコードを見つけて説明して"
"エラーハンドリングがどこで行われているか調べて"

# 段階的な修正
"src/auth配下のファイルだけを対象に、deprecatedな関数を修正して"

3. 安全な変更手順

小さな範囲から開始: 1つのモジュールやコンポーネントに限定
影響範囲の確認: 「この変更が他のファイルに与える影響を調べて」
段階的なテスト: 各変更後に関連テストを実行

4. 効果的なプロンプト例

# 具体的な範囲指定
"src/components/Header.js の TypeScript 移行だけを行って"
"tests/unit/user.test.js に新しいテストケースを3つ追加して"

# 依存関係を考慮した変更
"API の変更に合わせて、それを使用しているコンポーネントを全て更新して"

5. 解析内容の永続化

新規セッションでも過去の解析結果を活用するため、重要な情報をCLAUDE.mdに記録します。

プロジェクト知識の蓄積

# プロジェクト解析履歴

## アーキテクチャ解析結果
- 最終更新: 2025-06-04
- メインフレームワーク: React 18 + TypeScript
- 状態管理: Redux Toolkit
- ルーティング: React Router v6

## 重要なファイル・ディレクトリ
- src/store/: Redux設定とslices
- src/hooks/: カスタムフック集
- src/types/: TypeScript型定義
- config/: 環境設定ファイル

## 開発ガイドライン
- 新しいコンポーネント作成時は src/components/common/ を確認
- API呼び出しは src/services/ のサービス層を使用
- エラーハンドリングは src/utils/errorHandler.js を活用

## よく使う作業パターン
- バグ修正: まず tests/ でテストケースを確認
- 新機能追加: 既存の類似機能を src/ で検索して参考にする
- パフォーマンス改善: React DevTools Profilerでボトルネック特定

セッション引き継ぎのコツ

# 新しいセッションでの開始方法
"CLAUDE.mdの内容を読んで、このプロジェクトの概要を教えて"
"前回の解析結果を踏まえて、○○機能の修正を継続して"

# 解析結果の更新
"今回の調査結果をCLAUDE.mdのアーキテクチャ部分に追記して"
"新しく見つけた技術的負債をCLAUDE.mdに記録して"

チーム共有

CLAUDE.mdをGitで管理してチーム全体で共有
重要な設計決定や制約事項を文書化
新メンバーのオンボーディング資料として活用

解析高速化テクニック

事前準備による高速化

# CLAUDE.md に事前情報を記録

## ファイル索引
- 認証関連: src/auth/login.js, src/middleware/auth.js
- API層: src/api/users.js, src/api/products.js
- フロントエンド: src/components/UserProfile.jsx
- 設定: config/database.js, config/redis.js

## 重要な関数・クラス
- UserService.authenticate() - src/services/UserService.js:45
- validateToken() - src/utils/tokenValidator.js:12
- ErrorHandler.handle() - src/middleware/errorHandler.js:8

再解析時の高速化

# ❌ 毎回ゼロから解析
"ユーザー認証の仕組みを調べて"

# ✅ 既存情報を活用
"CLAUDE.md の認証関連ファイルリストを参照して、JWT トークンの検証ロジックを確認して"
"前回調査した UserService.authenticate() メソッドに追加されたログ処理を調べて"

差分解析による効率化

# Git履歴を活用した調査
"最新の3つのコミットで変更されたファイルだけを対象に、API の破壊的変更を調べて"
"昨日以降に更新されたテストファイルで失敗しているテストを特定して"

# 特定範囲の更新調査
"src/components/Header.jsx の変更が他のコンポーネントに与える影響を import 文から調べて"

構造化された調査結果の活用

# 解析結果テンプレート（CLAUDE.md に保存）

## モジュール解析結果
### [モジュール名]
- **場所**: ファイルパス
- **依存関係**: 使用している他のモジュール
- **公開API**: 外部から使用可能な関数・クラス
- **最終更新**: 日付と変更内容

キャッシュ的な活用方法

# 一度調査した内容の再利用
"CLAUDE.md のデータベース設定情報を参照して、新しい接続プールの設定を追加して"
"既に整理済みのAPI一覧から、ユーザー関連エンドポイントだけを抽出して詳細調査して"

# パターンの再適用
"前回作成したコンポーネント構造のテンプレートを使って、新しいProductCard コンポーネントを作成して"

セッション管理のベストプラクティス

長時間セッション vs 新規セッション

継続セッションの利点:
- コンテキスト保持により解析結果を覚えている
- 同じファイルへの再アクセスが高速
- 会話の流れで関連作業を効率的に実行
新規セッションの利点:
- 前回の思い込みや誤解をリセット
- 新鮮な視点でのコード解析
- メモリ使用量のリセット

推奨アプローチ:

# 同一機能の連続作業 → セッション継続
"認証機能のバグ修正" → "認証のテスト追加" → "認証のドキュメント更新"

# 異なる領域の作業 → 新規セッション
"認証機能の修正完了" → セッション終了 → "データベース最適化作業" → 新規セッション開始

セッション切り替えのタイミング:

大きな作業区切り（機能単位）で終了
数時間の連続作業後は一度リフレッシュ
CLAUDE.md の更新完了時が切り替えのベストタイミング

網羅的ソースコード解析

大規模プロジェクトのソースコード全体を解析する方法について説明します。

全体解析の段階的戦略

Step 1: 解析マップの作成

# プロジェクト全体の可視化
"全ディレクトリとファイル数を調査して、解析対象の全体像を把握して"
"技術スタック、フレームワーク、主要ライブラリを特定して"

Step 2: 重要度別グルーピング

# CLAUDE.md に記録する解析戦略

## 全体解析計画
### 最重要 (セッション1)
- エントリーポイント、設定、共通ユーティリティ
- データモデル、コアビジネスロジック

### 重要 (セッション2-3)
- API層、サービス層、主要コンポーネント
- 認証、権限管理、エラーハンドリング

### 補完 (セッション4-)
- UI詳細、テスト、ドキュメント
- 設定ファイル、ビルドスクリプト

Step 3: セッション別解析実行

# セッション1: 基盤解析
"設定ファイル全体を調査して、環境変数と依存関係を完全にマッピングして"
"メインエントリーポイントから辿れる処理フローを全て追跡して"

# 解析結果をCLAUDE.mdに構造化して保存
"今回の解析結果を CLAUDE.md の「基盤アーキテクチャ」セクションに詳細記録して"

新規セッションでの解析結果活用

解析結果を新規セッションで効果的に活用する方法を説明します。

Claude への詳細保存指示

# 詳細解析＆保存の指示例
"以下の形式でCLAUDE.mdに詳細な解析結果を保存してください：

1. ファイルの役割・機能を具体的に記述
2. 使用技術・ライブラリを明記
3. 重要な関数・メソッド名を記録
4. データフロー・処理の流れを説明
5. 設定値・定数・制約事項も含める

新規セッションで即座に理解できる詳細度で記録してください。"

詳細記録の例

CLAUDE.md での詳細保存例（クリックで展開）

# CLAUDE.md での詳細保存例

## ソースコード解析結果（詳細版）
### 最終更新: 2025-06-04

#### 基盤システム ✅完了
- **設定管理**:
  - config/app.js: サーバーポート3000、MongoDB接続、CORS設定
  - .env.example: 必須環境変数（DB_URL, JWT_SECRET, STRIPE_KEY）
- **アプリケーション起動**:
  - src/index.js: Expressサーバー起動、ミドルウェア設定
  - app.js: ルート定義、エラーハンドラー登録
- **共通ユーティリティ**: src/utils/
  - logger.js: Winston使用、ログレベル(info/error/debug)
  - validator.js: 入力検証、emailFormat()、passwordStrength()
  - crypto.js: bcrypt使用、saltRounds=10、ハッシュ化

#### ビジネスロジック ✅完了
- **データモデル**: src/models/ (Mongoose ODM)
  - User.js:
    - フィールド: email, password, role(admin/user), createdAt
    - メソッド: validatePassword(), generateToken()
    - バリデーション: email unique, password min 8文字
  - Product.js:
    - フィールド: name, price, category, stock, description
    - メソッド: checkStock(), decrementStock()
    - 制約: price > 0, stock >= 0
  - Order.js:
    - フィールド: userId, products[], totalAmount, status
    - ステータス: pending/processing/completed/cancelled
    - 関連: User、Product参照

#### API設計 ✅完了
- **認証API**: /api/auth
  - POST /login: email/password → JWT token(24h有効)
  - POST /register: ユーザー作成、重複チェック
  - GET /profile: JWT認証必須、ユーザー情報返却
- **商品API**: /api/products
  - GET /: ページネーション(limit=20)、カテゴリフィルター
  - GET /:id: 商品詳細、在庫状況含む
  - POST /: admin権限必須、商品作成
- **注文API**: /api/orders
  - POST /: 注文作成、在庫チェック、決済連携
  - GET /user/:id: ユーザー注文履歴
  - PUT /:id/status: admin用ステータス更新

## 重要な処理フロー

### 注文処理シーケンス
1. フロント: カート確定 → POST /api/orders
2. バック: OrderController.create()
3. 在庫確認: Product.checkStock() for each item
4. 決済処理: PaymentService.processStripePayment()
5. 注文作成: Order.create() with status='pending'
6. 在庫更新: Product.decrementStock() for each item
7. 通知送信: NotificationService.sendOrderEmail()
8. レスポンス: order ID + payment confirmation

### エラーハンドリング戦略
- **共通処理**: middleware/errorHandler.js
- **API応答**: 統一フォーマット {success, data, error, code}
- **フロント**: Redux error state → Toast通知表示
- **ログ**: Winston → ファイル出力 + コンソール表示

Claude への指示のコツ

# 効果的な保存指示
"調査した内容を以下の観点でCLAUDE.mdに整理してください：
- 技術選択の理由（なぜこのライブラリを使用？）
- 設定値の意味（ポート番号、タイムアウト値など）
- 関数の引数・戻り値・副作用
- ファイル間の依存関係
- エラーケースの処理方法
- パフォーマンス・セキュリティの考慮点

新規セッションで『CLAUDE.mdを読んで』と言うだけで、
詳細なコンテキストを理解できる状態にしてください。"

新規セッションでの高速立ち上げ

# セッション開始時の標準プロンプト
"CLAUDE.mdの「ソースコード全体マップ」を参照して、前回の解析状況を教えて"
"未解析のsrc/pages/admin/を継続調査して、前回のフロントエンド解析に統合して"

# 特定作業での活用
"全体マップの認証関連ファイルを参照して、新しいOAuth実装を追加して"
"API解析結果を基に、エンドポイントの重複チェックを実行して"

累積的な知識構築

各セッションで解析結果をCLAUDE.mdに蓄積
新規セッションでは既存の解析を前提として作業開始
解析の抜け漏れを段階的に補完

全自動での網羅的解析

⚠️ 注意: この方法は一般的には推奨しません

推奨しない理由:

時間: 数十万行のプロジェクトで3-6時間程度かかる場合がある
効率性: 重要度に関係なく全てを調べるため非効率
実用性: 結果が膨大すぎて把握困難
リスク: 長時間セッションでタイムアウトの可能性

時間目安:

小規模プロジェクト（〜1万行）: 30分-1時間
中規模プロジェクト（1-10万行）: 1-3時間
大規模プロジェクト（10万行〜）: 3-6時間以上

それでも実行する場合の方法:

完全自動解析の依頼方法

# 全自動解析のプロンプト例
"プロジェクト全体を完全に自動解析して、以下を CLAUDE.md に記録してください：
1. 全ディレクトリ・ファイル構造
2. 使用技術スタックと依存関係
3. アーキテクチャ設計パターン
4. 主要な機能・モジュールの詳細
5. データフロー・処理フロー
6. API仕様・エンドポイント一覧
7. データベーススキーマ（あれば）
8. テスト戦略・カバレッジ
9. 設定・環境変数
10. 技術的負債・改善提案

時間はかかっても構わないので、すべて自動で調査・整理してください。"

段階的自動解析の指示

# より詳細な自動解析指示
"以下の手順で完全自動解析を実行してください：

Phase 1: 基盤調査
- package.json, requirements.txt 等から技術スタック特定
- 設定ファイル群の完全調査
- エントリーポイントとアプリケーション起動フロー

Phase 2: アーキテクチャ解析
- ディレクトリ構造とモジュール分割方針
- 設計パターン・アーキテクチャパターンの特定
- 依存関係とデータフローの可視化

Phase 3: 機能詳細解析
- 全ソースファイルの機能・役割調査
- API・エンドポイント・関数の完全一覧
- ビジネスロジック・ドメインモデルの抽出

Phase 4: 品質・運用面解析
- テスト状況・カバレッジ・品質指標
- パフォーマンス・セキュリティ観点
- デプロイ・CI/CD設定

すべての結果を構造化してCLAUDE.mdに保存してください。"

自動解析結果の活用

一度の解析で全プロジェクトの完全な理解を獲得
新規セッションで即座にプロジェクト全体を把握可能
特定の機能修正時も全体への影響を瞬時に判断
チーム全体での知識共有が効率化

推奨：段階的解析アプローチ

効率的な解析手順（推奨）

# Step 1: 概要把握（15-30分）
"プロジェクトの基本情報を調査してCLAUDE.mdに記録してください：
- 技術スタック（package.json等から）
- ディレクトリ構造の概要
- エントリーポイントとメイン処理フロー"

# Step 2: 重要モジュール特定（15-30分）
"重要なファイル・モジュールを特定してください：
- 設定ファイル群
- コアビジネスロジック
- 外部API・データベース接続部分"

# Step 3: 必要に応じて詳細調査
"特定の機能について詳細調査：
- 認証機能の実装詳細
- エラーハンドリングの仕組み
- パフォーマンス関連の実装"

段階的解析の利点:

短時間: 各段階15-30分程度で完了
実用的: 重要な情報から優先的に把握
柔軟性: 必要に応じて深掘り可能
継続性: セッション間で効率的に継続

まとめ

この記事では、Claude Code の実践的な活用方法について、動作検証と本体への質問を通じて得られた知見を共有しました。

重要なポイント:

CLAUDE.md の自動読み込みは動作が一定しないため、明示的な読み込み指示が推奨される
ファイルフォーマットチェックはリアルタイムではなく事後確認のみ可能
大規模プロジェクトでは段階的解析アプローチが効率的
解析結果の永続化により、新規セッション間での知識継承が可能

Claude Code を効果的に活用するには、これらの特性を理解し、プロジェクトに応じた設定と運用方法を確立することが重要です。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up