Claude Codeの設定 - CLAUDE.md
概要
CLAUDE.mdは、Claude Codeの永続的プロジェクトメモリ機能である。
Claude Codeはステートレスな大規模言語モデル (LLM) であるため、通常は前回のセッションの内容を記憶できない。
CLAUDE.mdファイルを活用することにより、プロジェクト固有のルール、コーディング規約、よく使うコマンド、アーキテクチャパターンなどを永続化し、
セッション開始時に自動的に読み込ませることができる。
CLAUDE.mdは以下に示す特徴を持つ。
- セッション開始時の自動読み込み
- プロジェクト固有の知識を永続化
- チーム全体で共有可能
- 複数の優先度レベルで階層的に管理
- Markdown形式での記述
CLAUDE.mdを使用することにより、以下に示すメリットが得られる。
- 一貫性の向上
- プロジェクト固有のルールやパターンを全セッションで適用
- 効率の向上
- よく使うコマンドやワークフローを記録し、毎回説明する手間を削減
- チーム間の知識共有
- プロジェクトのベストプラクティスをチーム全体で共有
- コンテキストの維持
- プロジェクトの背景、技術スタック、制約事項を常に保持
メモリ優先度の階層構造
Claude Codeは、4層のメモリ優先度階層を持つ。
優先度の高い順に以下に示す。
優先度1 : エンタープライズポリシー
最高優先度のメモリである。
組織全体のポリシーやセキュリティ要件を定義する。
- 管理者によって設定される
- 全てのユーザとプロジェクトに適用
- エンタープライズ版のみで使用可能
優先度2 : プロジェクトメモリ
プロジェクト固有のルールとパターンを定義するメモリである。
- 配置場所
- ./CLAUDE.md
- または
- ./.claude/CLAUDE.md
- スコープ
- 現在のプロジェクトディレクトリ内のみ
- 用途
- プロジェクト固有のコーディング規約、ディレクトリ構造、技術スタック情報
- 共有方法
- バージョン管理システムでチーム全体と共有
優先度3 : ユーザメモリ
ユーザ個人の全プロジェクトで共有される個人設定である。
- 配置場所
- ~/.claude/CLAUDE.md
- スコープ
- 全てのプロジェクトで適用
- 用途
- 個人のコーディングスタイル、よく使うツール、個人的な制約事項
- 共有方法
- 個人設定であり、通常は共有しない
優先度4 : ローカルメモリ
最低優先度のメモリである。
プロジェクト固有だが、バージョン管理からは除外されるローカル設定である。
- 配置場所
- ./CLAUDE.local.md
- スコープ
- 現在のプロジェクトディレクトリ内のみ
- 用途
- 個人的なメモ、実験的な設定、機密情報
- 共有方法
- .gitignoreに含め、共有しない
競合が発生した場合、優先度の高いメモリが優先される。
たとえば、エンタープライズポリシーで禁止されている操作は、プロジェクトメモリやユーザメモリで許可されていても実行できない。
CLAUDE.mdに記述する内容
プロジェクト概要
プロジェクトの目的、技術スタック、主要な機能を簡潔に記述する。
記述例を以下に示す。
# プロジェクト概要 このプロジェクトは、ユーザ認証機能を持つWebアプリケーションです。 技術スタック: - フロントエンド: React 19.2 + TypeScript 5.0 - バックエンド: Node.js 20 + Express 4.18 - データベース: PostgreSQL 15 - 認証: JWT (JSON Web Token)
ディレクトリ構造
プロジェクトのディレクトリ構成と各ディレクトリの役割を説明する。
記述例を以下に示す。
# ディレクトリ構造 ``` project/ ├── src/ │ ├── components/ # Reactコンポーネント │ ├── api/ # APIエンドポイント │ ├── models/ # データモデル │ └── utils/ # ユーティリティ関数 ├── tests/ # テストコード └── docs/ # ドキュメント ```
コーディング規約
プロジェクトで使用するコーディング規約、命名規則、スタイルガイドを記述する。
記述例を以下に示す。
# コーディング規約 - 関数名: camelCase - コンポーネント名: PascalCase - 定数: UPPER_SNAKE_CASE - ファイル名: kebab-case - インデント: 半角スペース2つ - 行の最大文字数: 100文字 - セミコロン: 必須
頻繁に使用するコマンド
プロジェクトで頻繁に使用するコマンドを記録する。
記述例を以下に示す。
# 頻繁に使用するコマンド ## 開発サーバの起動 npm run dev ## テストの実行 npm test ## ビルド npm run build ## データベースマイグレーション npm run migrate
アーキテクチャパターン
プロジェクトで使用するデザインパターン、アーキテクチャパターンを記述する。
記述例を以下に示す。
# アーキテクチャパターン ## 状態管理 - Zustandを使用したグローバル状態管理 - ローカル状態はuseStateで管理 ## APIクライアント - Axiosを使用したRESTful APIクライアント - エラーハンドリングはinterceptorで一元管理 ## 認証フロー - JWTトークンをlocalStorageに保存 - リフレッシュトークンで自動更新
注意事項・制限事項
プロジェクトで避けるべきパターン、使用禁止のライブラリ、セキュリティ制約等を記述する。
記述例を以下に示す。
# 注意事項・制限事項 - パスワードをログに出力しないこと - APIキーは.envファイルに記載し、.gitignoreに含めること - moment.jsは使用禁止 (date-fnsを使用) - グローバル変数の使用を避けること - インラインスタイルは使用禁止 (Tailwind CSSを使用)
CLAUDE.mdの作成方法
ステップ 1 : 自動生成 (/init コマンド)
Claude Codeセッションを開始し、/init コマンドを実行する。
このコマンドにより、プロジェクトのコンテキストを解析し、自動的にCLAUDE.mdファイルが生成される。
# コマンドの実行 : /init
/init コマンドは以下に示す内容を自動的に生成する。
- プロジェクトの技術スタックの検出
- ディレクトリ構造の解析
- package.json や Cargo.toml 等の設定ファイルの読み取り
- 頻繁に使用するコマンドの推測
自動生成されたCLAUDE.mdファイルは、以下のいずれかの場所に配置される。
- プロジェクトルート
- ./CLAUDE.md
- .claudeディレクトリ内
- ./.claude/CLAUDE.md
生成されたファイルを確認し、必要に応じて編集する。
ステップ 2 : 手動作成
/init コマンドを使用せず、手動でCLAUDE.mdファイルを作成することもできる。
手動作成の手順を以下に示す。
ステップ 2-1 : ファイルの作成
プロジェクトルートまたは.claudeディレクトリにCLAUDE.mdファイルを作成する。
# プロジェクトルートに作成する場合 : touch CLAUDE.md
# .claudeディレクトリに作成する場合 : mkdir -p .claude touch .claude/CLAUDE.md
ステップ 2-2 : 基本情報の記述
プロジェクト概要、技術スタック、ディレクトリ構造などを記述する。
Markdown形式で記述する。
# プロジェクト概要 このプロジェクトは... # 技術スタック - フロントエンド: React - バックエンド: Node.js # ディレクトリ構造 ``` src/ ├── components/ └── api/ ```
ステップ 2-3 : コーディング規約の追加
プロジェクト固有のコーディング規約を追加する。
# コーディング規約 - 関数名: camelCase - インデント: 半角スペース2つ - セミコロン: 必須
ステップ 2-4 : 頻繁に使用するコマンドの追加
頻繁に使用するコマンドを記録する。
# 頻繁に使用するコマンド ## 開発サーバの起動 npm run dev ## テストの実行 npm test
ステップ 2-5 : ファイルの保存と確認
ファイルを保存し、Claude Codeセッションを再起動して読み込みを確認する。
# Claude Codeセッションの終了 : /exit
# Claude Codeセッションの再起動 : claude
セッション開始時に、CLAUDE.mdの内容が自動的に読み込まれる。
ステップ 3 : カスタマイズと改善
プロジェクトの進行に合わせて、CLAUDE.mdファイルを定期的に更新する。
更新タイミングの例を以下に示す。
- 新しい技術スタックを導入した時
- コーディング規約を変更した時
- 新しいディレクトリを追加した時
- 新しいワークフローを導入した時
月に1回程度、CLAUDE.mdファイルを見直すことを推奨する。
基本的な記述例
シンプルな例
最小限の構成でCLAUDE.mdを作成する例を以下に示す。
# MyProject
React + TypeScript のWebアプリケーション。
## 技術スタック
- React 18
- TypeScript 5
- Vite
## 開発サーバの起動
npm run dev
## テストの実行
npm test
詳細な例
包括的なCLAUDE.mdファイルの例を以下に示す。
# E-Commerce Web Application
このプロジェクトは、ユーザ認証、商品管理、決済機能を持つECサイトです。
## 技術スタック
### フロントエンド
- React 18.2 + TypeScript 5.0
- 状態管理: Zustand
- スタイリング: Tailwind CSS
- ルーティング: React Router 6
- テスト: Jest + React Testing Library
### バックエンド
- Node.js 20 + Express 4.18
- データベース: PostgreSQL 15
- ORM: Prisma
- 認証: JWT (JSON Web Token)
- 決済: Stripe API
## ディレクトリ構造
```
project/
├── frontend/
│ ├── src/
│ │ ├── components/ # Reactコンポーネント
│ │ ├── pages/ # ページコンポーネント
│ │ ├── hooks/ # カスタムHooks
│ │ ├── store/ # Zustandストア
│ │ └── utils/ # ユーティリティ関数
│ └── tests/ # テストコード
├── backend/
│ ├── src/
│ │ ├── routes/ # APIルート
│ │ ├── controllers/ # コントローラ
│ │ ├── models/ # データモデル
│ │ ├── middleware/ # ミドルウェア
│ │ └── utils/ # ユーティリティ関数
│ └── tests/ # テストコード
└── docs/ # ドキュメント
```
## コーディング規約
### 命名規則
- 変数・関数名: camelCase
- コンポーネント名: PascalCase
- 定数: UPPER_SNAKE_CASE
- ファイル名: kebab-case
### スタイル
- インデント: 半角スペース2つ
- 行の最大文字数: 100文字
- セミコロン: 必須
- クォート: シングルクォート
### React
- 関数コンポーネントを使用
- propsの型定義を必須とする
- useEffectの依存配列を正確に指定
- コンポーネントは200行以内に抑える
## 頻繁に使用するコマンド
### フロントエンド
```bash
# 開発サーバの起動
npm run dev
# テストの実行
npm test
# ビルド
npm run build
# Lint
npm run lint
```
### バックエンド
```bash
# 開発サーバの起動
npm run dev
# データベースマイグレーション
npm run migrate
# シード
npm run seed
# テストの実行
npm test
```
## アーキテクチャパターン
### 状態管理
- グローバル状態: Zustand
- ローカル状態: useState
- サーバ状態: React Query
### APIクライアント
- Axiosを使用
- エラーハンドリングはinterceptorで一元管理
- リトライロジックを実装
### 認証フロー
- JWTトークンをlocalStorageに保存
- リフレッシュトークンで自動更新
- トークン有効期限切れ時は自動ログアウト
## 注意事項・制限事項
### セキュリティ
- パスワードをログに出力しないこと
- APIキーは.envファイルに記載し、.gitignoreに含めること
- ユーザ入力は必ずバリデーション
- SQLインジェクション対策を実装
### 使用禁止
- moment.js (date-fnsを使用)
- グローバル変数
- インラインスタイル (Tailwind CSSを使用)
- any型 (TypeScript)
## テスト要件
- 全ての新機能にはテストを追加
- カバレッジは80%以上を維持
- E2Eテストは主要なユーザフローに対して実装
## デプロイメント
- フロントエンド: Vercel
- バックエンド: AWS ECS
- データベース: AWS RDS
- CI/CD: GitHub Actions
高度な機能
@import構文による他ファイルの参照
CLAUDE.mdファイルから他のファイルを参照することにより、ファイルサイズを抑えつつ必要な情報を読み込める。
@import 構文の基本形式を以下に示す。
@import path/to/file.md
使用例を以下に示す。
# MyProject
このプロジェクトは...
@import docs/coding-standards.md
@import docs/architecture.md
@import docs/deployment.md
@import 構文を使用することにより、以下に示すメリットが得られる。
- ファイルの分割管理
- CLAUDE.mdをコンパクトに保ち、詳細は別ファイルで管理
- チーム間での責任分担
- 各ドキュメントを担当者ごとに分割して管理
- 再利用性の向上
- 複数のプロジェクトで共通のドキュメントを参照
※注意
- 相対パスまたは絶対パスを指定
- 循環参照を避ける
- 参照先ファイルが存在しない場合はエラーが発生
.claude/rules/ によるモジュール化
.claude/rules/ ディレクトリを使用することにより、ルールをモジュール化できる。
このディレクトリ内のMarkdownファイルは、CLAUDE.mdと同様に自動的に読み込まれる。
# ディレクトリ構成の例 :
.claude/
├── CLAUDE.md
└── rules/
├── coding-standards.md
├── security.md
├── testing.md
└── deployment.md
各ルールファイルの例を以下に示す。
- coding-standards.mdの例
# コーディング規約 - 関数名: camelCase - インデント: 半角スペース2つ - セミコロン: 必須
- security.mdの例
# セキュリティルール - パスワードをログに出力しないこと - APIキーは.envファイルに記載 - ユーザ入力は必ずバリデーション
.claude/rules/ディレクトリを使用することにより、以下に示すメリットが得られる。
- 責任の分離
- ルールをカテゴリごとに分割
- 保守性の向上
- 各ファイルを独立して編集
- チーム間の協力
- 異なる担当者が異なるルールファイルを管理
YAMLフロントマターによるパス固有ルール
YAMLフロントマターを使用することにより、特定のパスに対してのみ適用されるルールを定義できる。
基本形式を以下に示す。
---
paths:
include:
- src/components/**
exclude:
- src/components/deprecated/**
---
このルールはsrc/components/配下のファイルにのみ適用されます。
ただし、src/components/deprecated/は除外されます。
使用例を以下に示す。
- .claude/rules/react-rules.mdの例
--- paths: include: - src/components/** --- # React コンポーネントのルール - 関数コンポーネントを使用 - propsの型定義を必須とする - useEffectの依存配列を正確に指定 - コンポーネントは200行以内に抑える
- .claude/rules/api-rules.mdの例
--- paths: include: - src/api/** --- # API ルート のルール - 全てのエンドポイントにバリデーションを実装 - エラーハンドリングを必須とする - レスポンスは統一されたフォーマットで返す
パス固有ルールを使用することにより、以下に示すメリットが得られる。
- コンテキストの最適化
- 作業中のファイルに関連するルールのみが適用される
- ルールの明確化
- 各ディレクトリに適用されるルールが明確
- 柔軟性の向上
- 異なるディレクトリで異なるルールを適用
サブエージェントとの連携
CLAUDE.mdファイルの内容は、サブエージェントにも引き継がれる。
サブエージェントは独立したコンテキストウィンドウを持つが、CLAUDE.mdの内容は親エージェントから子エージェントに自動的に引き継がれる。
このため、サブエージェントでもプロジェクト固有のルールやパターンを適用できる。
連携の仕組み
- ユーザがClaude Codeセッションを開始
- 親エージェントがCLAUDE.mdを読み込み
- 親エージェントがサブエージェントを呼び出す
- サブエージェントは親エージェントから引き継いだCLAUDE.mdの内容を利用
連携の例
CLAUDE.mdでコーディング規約を定義している場合、code-reviewerサブエージェントは自動的にその規約を適用してコードレビューを実行する。
この連携により、サブエージェントでもプロジェクト固有のルールを一貫して適用できる。
推奨される方法
簡潔性を保つ
CLAUDE.mdファイルは、60行から300行程度に抑えることを推奨する。
ファイルサイズの目安を以下に示す。
- 最小構成: 60行程度
- プロジェクト概要、技術スタック、よく使うコマンドのみ
- 標準構成: 150行程度
- 概要、技術スタック、ディレクトリ構造、コーディング規約、よく使うコマンド
- 詳細構成: 300行程度
- 概要、技術スタック、ディレクトリ構造、コーディング規約、よく使うコマンド、アーキテクチャパターン、注意事項
300行を超える場合は、@import構文または.claude/rules/を使用してファイルを分割する。
具体性を重視する
抽象的な説明ではなく、具体的な指示を記述する。
| 抽象的な表現 | 具体的な表現 |
|---|---|
| コードは読みやすく書くこと | 関数は50行以内に抑え、変数名はcamelCaseを使用すること |
| テストを書くこと | 全ての新機能にはJestでユニットテストを追加し、カバレッジ80%以上を維持すること |
| セキュリティに注意すること | APIキーは.envファイルに記載し、ユーザ入力は必ずバリデーションを実施すること |
具体的な指示を記述することにより、Claudeがより正確に理解し、適切なコードを生成できる。
定期的な更新
CLAUDE.mdファイルは、プロジェクトの進行に合わせて定期的に更新する。
更新のタイミング
- 月に1回程度の定期レビュー
- 新しい技術スタックを導入した時
- コーディング規約を変更した時
- 新しいディレクトリを追加した時
- 新しいワークフローを導入した時
更新の手順
- CLAUDE.mdファイルを開く。
- 現在のプロジェクトの状態と一致しているか確認する。
- 古い情報を削除する、
- 新しい情報を追加する。
- Claude Codeセッションを再起動して確認する。
定期的に更新することにより、CLAUDE.mdファイルは常に最新の状態を保ち、Claudeに正確な情報を提供できる。
機密情報を含めない
CLAUDE.mdファイルには、機密情報を記載しない。
記載禁止の情報例を以下に示す。
- パスワード
- APIキー
- シークレットトークン
- データベース接続文字列
- プライベートなIPアドレス
- 個人情報
機密情報は、以下のように管理する。
- .envファイルに記載
- 環境変数として管理
- .gitignoreに含める
- バージョン管理から除外
- CLAUDE.local.mdに記載
- ローカルメモリとして個人で管理
CLAUDE.mdファイルはバージョン管理システムに含めることが多いため、機密情報を含めないよう注意する。
バージョン管理に含める
プロジェクトレベルのCLAUDE.mdファイルは、バージョン管理システムに含めることを推奨する。
バージョン管理に含めるファイル
- ./CLAUDE.md
- プロジェクトメモリ
- .claude/CLAUDE.md
- プロジェクトメモリ (代替配置)
- .claude/rules/*.md
- モジュール化されたルールファイル
バージョン管理から除外するファイル
- ./CLAUDE.local.md
- ローカルメモリ (個人設定)
- ~/.claude/CLAUDE.md
- ユーザメモリ (個人設定)
.gitignoreの例
# Claude Code local settings
CLAUDE.local.md
.claude/settings.local.json
.claude/cache/
バージョン管理に含めることにより、チーム全体でプロジェクトのルールとパターンを共有できる。
学習に用いる場合
例えば、コーディング技術を学習する場合は、CLAUDE.mdファイル内に以下に示すような文章を記述する。
これにより、修正すべき箇所および理由を教示してもらうことができる。
## 出力ガイド
ユーザは、写経して学習しながら開発を行うことを希望しています。
**あなたはコードを教えるだけで実装しないでください。**
まず、現在のファイルを一緒に確認してから、変更箇所を順番に教えていきます。
各変更箇所ごとに：
- 変更後のコードを提示
- なぜこう変更するのかを説明
という流れで進めてください。
トラブルシューティング
CLAUDE.mdが読み込まれない場合
ファイルの配置場所を確認
CLAUDE.mdファイルが正しい場所に配置されているか確認する。
正しい配置場所を以下に示す。
- プロジェクトレベル
- ./CLAUDE.md
- または
- .claude/CLAUDE.md
- ユーザレベル
- ~/.claude/CLAUDE.md
- ローカルレベル
- ./CLAUDE.local.md
ファイルの権限を確認
CLAUDE.mdファイルが読み取り可能であるか確認する。
# 権限の確認 : ls -l CLAUDE.md
読み取り権限がない場合は、権限を変更する。
# 読み取り権限の付与 : chmod +r CLAUDE.md
Claude Codeセッションを再起動
CLAUDE.mdファイルを作成または変更した後、Claude Codeセッションを再起動する。
セッション開始時に、CLAUDE.mdの内容が自動的に読み込まれる。
# Claude Codeセッションの終了 /exit
# Claude Codeセッションの再起動 claude
ファイルのフォーマットを確認
CLAUDE.mdファイルがMarkdown形式で正しく記述されているか確認する。
Markdown構文のエラーがある場合、ファイルが正しく読み込まれない可能性がある。
確認項目を以下に示す。
- ファイルの拡張子が .md であること。
- ファイルの文字エンコーディングがUTF-8であること。
- Markdown構文が正しいこと。
優先度の競合が発生する場合
複数のメモリ階層で異なるルールが定義されている場合、優先度の高いメモリが優先される。
優先度の順序を以下に示す。
- エンタープライズポリシー (最高優先度)
- プロジェクトメモリ
- ./CLAUDE.md
- ユーザメモリ
- ~/.claude/CLAUDE.md
- ローカルメモリ
- ./CLAUDE.local.md
競合が発生した場合の対処法を以下に示す。
- 優先度の高いメモリを確認
- どのルールが適用されているか確認
- 不要なルールを削除
- 競合するルールを削除または修正
- ローカルメモリで上書き
- プロジェクトメモリを変更できない場合、ローカルメモリで一時的に上書き
どのルールが適用されているかを確認するには、Claudeに直接質問する。
# 質問例 : このプロジェクトのコーディング規約を教えてください
Claudeは、現在適用されているルールを説明する。
@import参照が失敗する場合
@import構文で他のファイルを参照する際、ファイルが見つからない場合がある。
ファイルパスを確認
参照先のファイルパスが正しいか確認する。
相対パスの場合、CLAUDE.mdファイルからの相対パスを指定する。
# 正しい例 : @import docs/coding-standards.md
# 誤った例 : @import /docs/coding-standards.md
循環参照を確認
@import 構文で循環参照が発生していないか確認する。
循環参照の例を以下に示す。
- CLAUDE.md が docs/a.md をインポート
- docs/a.md が docs/b.md をインポート
- docs/b.md が CLAUDE.md をインポート (循環参照)
循環参照が発生している場合は、インポート構造を見直す。
関連機能
settings.json との関係
Claude Codeは、CLAUDE.mdファイルとは別に、settings.jsonファイルを使用してプロジェクト設定を管理する。
settings.jsonの配置場所を以下に示す。
- プロジェクトレベル
- .claude/settings.json
- ユーザレベル
- ~/.claude/settings.json
settings.jsonには、以下に示す設定を記述する。
- 使用するモデル (model)
- サブエージェントの有効化 (subagents)
- コンテキストの最大サイズ (maxContextSize)
- その他のClaude Code固有の設定
下表に、settings.jsonとCLAUDE.mdの使い分けを示す。
| ファイル | 用途 | 記述内容 |
|---|---|---|
| settings.json | Claude Code の動作設定 | モデル、サブエージェント、コンテキストサイズ等 |
| CLAUDE.md | プロジェクトの知識とルール | コーディング規約、技術スタック、アーキテクチャ等 |
- settings.jsonの例
{ "model": "claude-sonnet-4-5-20250929", "subagents": true, "maxContextSize": 200000, "hooks": { "enabled": true } }
.claudeignore との関係
.claudeignoreファイルを使用することにより、Claude Codeが特定のファイルやディレクトリを無視するよう設定できる。
.claudeignoreの配置場所を以下に示す。
- プロジェクトルート
- ./.claudeignore
.claudeignoreの記述形式は、.gitignoreと同様である。
- .claudeignoreの例
# 依存関係 node_modules/ vendor/ # ビルド成果物 dist/ build/ # ログファイル *.log # 環境変数 .env .env.local # キャッシュ .cache/
.claudeignoreとCLAUDE.mdの連携を以下に示す。
- CLAUDE.mdで重要なファイルやディレクトリを説明する。
- .claudeignoreで不要なファイルを除外する。
- Claudeは必要な情報に焦点を当てる。
この連携により、Claudeは効率的にプロジェクトのコンテキストを把握できる。
参考リンク
