CLAUDE.md入門 - 5分で始めるプロジェクト設定¶
この記事の対象者
- Claude Codeを初めて使う方
- プロジェクトにAIアシスタントを導入したい方
- CLAUDE.mdの基本を理解したい方
この記事で学べること¶
- CLAUDE.mdとは何か
- 最小構成での作成方法
- メモリ階層とファイル構成の全体像
- Skills・Subagentsとの使い分け
- 効果を実感できる実例
- 次のステップへの道筋
前提知識¶
- 基本的なコマンドライン操作
- テキストエディタの使用経験
CLAUDE.mdとは¶
CLAUDE.mdは、Claude Codeがあなたのプロジェクトを理解するための設定ファイルです。 このファイルがあることで、AIがプロジェクト固有のルールやワークフローを理解し、より適切な支援を提供できます。
重要: ファイル名は必ず
CLAUDE.md（すべて大文字）にしてください。
/init コマンドによる自動生成¶
CLAUDE.mdを手動で作成する代わりに、Claude Codeの /init コマンドを使うことでプロジェクトを自動分析し、CLAUDE.mdを自動生成できます。
# Claude Codeのセッション内で実行
/init
/init はプロジェクトのディレクトリ構造、使用言語、ビルドシステムなどを分析し、適切な初期設定を含むCLAUDE.mdを生成します。手動で書くよりも素早く始められるため、まず /init で生成してからカスタマイズする方法を推奨します。
CLAUDE.md・Skills・Subagentsの比較¶
Claude Codeには、AIの振る舞いをカスタマイズするための仕組みが複数あります。それぞれの役割と違いを理解しておくことが重要です。
| 機能 | CLAUDE.md | Skills (.claude/skills/) | Subagents (.claude/agents/) |
|---|---|---|---|
| 用途 | プロジェクトルール・規約 | オンデマンドの専門知識 | 独立コンテキストのタスク実行 |
| ロード | セッション開始時に自動 | トリガーキーワードで起動 | Task toolで明示的に呼び出し |
| スコープ | 全セッション | 起動時のみ | タスク実行中のみ |
| 記述内容 | ビルドコマンド、規約、制約 | ワークフロー手順、専門知識 | エージェントの振る舞い定義 |
| 共有 | Git管理で全員共有 | Git管理で全員共有 | Git管理で全員共有 |
- CLAUDE.md: プロジェクト全体に常時適用されるルールや規約。セッション開始時に自動的に読み込まれる
- Skills: 特定のタスクに必要な専門知識。トリガーキーワード（例：「記事作成」「ビルド」）で必要な時だけロードされる
- Subagents: 独立したコンテキストで特定タスクを実行するエージェント。メインの会話コンテキストを消費せずにタスクを委譲できる
メモリ階層¶
Claude Codeは複数の設定ファイルを階層的に読み込みます。上位ほど優先度が高く、広い範囲に適用されます。
| 優先度 | ファイル | スコープ | 説明 |
|---|---|---|---|
| 1（最高） | Managed policy（システムディレクトリ） | 組織の全ユーザー | 管理者が設定する組織ポリシー |
| 2 | ./CLAUDE.md または ./.claude/CLAUDE.md | チーム全員 | プロジェクトルールをGit管理で共有 |
| 3 | ./.claude/rules/*.md | チーム全員 | パス固有ルール（後述） |
| 4 | ~/.claude/CLAUDE.md | 自分のみ（全プロジェクト） | ユーザー個人の共通設定 |
| 5 | ./CLAUDE.local.md | 自分のみ（現プロジェクト） | ローカル専用の設定（Gitに含めない） |
| 6 | ~/.claude/projects/<project>/memory/ | 自分のみ（プロジェクト別） | Claude Codeが自動保存するメモリ |
使い分けのポイント¶
- チームで共有する設定 →
CLAUDE.mdに記述してGit管理 - 個人の好みや環境固有の設定 →
CLAUDE.local.mdに記述（.gitignoreに追加） - 全プロジェクト共通の個人設定 →
~/.claude/CLAUDE.mdに記述
自動メモリ（Auto Memory）¶
Claude Codeには自動メモリ機能があり、セッション中に学習したプロジェクトのパターンやデバッグのインサイトを ~/.claude/projects/<project>/memory/MEMORY.md に自動保存します。このファイルの先頭200行がセッション開始時に自動的に読み込まれます。
自動メモリには以下のような情報が蓄積されます：
- プロジェクト固有のデバッグパターン
- よく使うコマンドやワークフロー
- 過去のセッションで発見した注意点
@importによるファイル分割¶
CLAUDE.mdが大きくなった場合、@import 構文を使って他のファイルを読み込むことができます。
# プロジェクト設定
@docs/coding-standards.md
@docs/api-guidelines.md
@.claude/rules/testing-rules.md
@importの仕様¶
- 相対パス・絶対パスの両方が利用可能
- 再帰インポートは最大5ホップまで対応（循環参照を防止）
- 初回インポート時に承認ダイアログが表示される（セキュリティ保護）
- コードスパンやコードブロック内の
@pathは評価されない（通常のテキストとして扱われる）
# 以下はインポートされる
@configs/rules.md
# 以下はインポートされない（コードブロック内）
`@configs/rules.md`
パス固有ルール（.claude/rules/）¶
.claude/rules/ ディレクトリにMarkdownファイルを配置することで、特定のファイルパスに対してのみ適用されるルールを定義できます。YAMLフロントマターの paths フィールドで対象パスをglob形式で指定します。
---
paths:
- "src/api/**/*.ts"
---
# API開発ルール
- すべてのエンドポイントに入力バリデーションを含めること
- レスポンスは統一フォーマットで返すこと
- エラーハンドリングを必ず実装すること
---
paths:
- "tests/**/*.test.ts"
---
# テストルール
- テストはArrange-Act-Assertパターンに従うこと
- モックは最小限に抑えること
paths フィールドがないルールファイルは、すべてのファイルに対して適用されます。
5分で始める最小構成¶
Step 1: ファイルを作成する（30秒）¶
プロジェクトのルートディレクトリで以下を実行：
touch CLAUDE.md
または、Claude Codeのセッション内で /init を実行して自動生成できます。
Step 2: 最小限の内容を追加（2分）¶
以下の内容をCLAUDE.mdに記述：
# プロジェクト設定
## 概要
このプロジェクトは[目的]のためのアプリケーションです。
## 技術スタック
- 言語: [Python/JavaScript/など]
- フレームワーク: [使用しているフレームワーク]
## 主要コマンド
- 開発サーバー起動: `npm run dev`
- テスト実行: `npm test`
## 注意事項
- [プロジェクト固有の重要な注意点]
Step 3: 実際の例（2分）¶
React プロジェクトの場合の具体例：
# プロジェクト設定
## 概要
顧客管理システムのフロントエンドアプリケーション
## 技術スタック
- 言語: TypeScript
- フレームワーク: React 18
- スタイリング: Tailwind CSS
## 主要コマンド
- 開発サーバー起動: `npm run dev`
- テスト実行: `npm test`
- ビルド: `npm run build`
## 注意事項
- APIエンドポイントは環境変数で管理
- コンポーネントはsrc/components配下に配置
Step 4: Gitに追加（30秒）¶
git add CLAUDE.md
git commit -m "Add CLAUDE.md configuration"
CLAUDE.mdに書くべきこと・書かないこと¶
書くべきこと¶
CLAUDE.mdには、コードだけでは推測できない情報を記述します。
- ビルド・テストコマンド:
npm run build、pytestなど、プロジェクト固有のコマンド - コードスタイルルール: このプロジェクト固有の命名規則やフォーマットルール
- リポジトリの作法: PR規約、ブランチ命名規則、コミットメッセージのフォーマット
- アーキテクチャ上の決定事項: 特定のパターンを採用した理由やデザイン方針
- よくある落とし穴: 新規参加者が陥りやすいミスや注意点
書くべきでないこと¶
以下の情報はCLAUDE.mdに含めるべきではありません。
- 標準的な規約: PEP 8やESLintのデフォルトルールなど、Claude Codeが既に知っている一般的な規約
- 詳細なAPIドキュメント: 長大なAPIリファレンスはリンクで参照する（CLAUDE.mdが肥大化するため）
- 頻繁に変更される情報: バージョン番号やリリース日など、すぐに古くなる情報
効果を実感する¶
CLAUDE.mdを追加した後、Claude Codeに以下のような質問をしてみてください：
Before（CLAUDE.mdなし）¶
Q: 「新しいコンポーネントを追加して」
A: どのようなコンポーネントを、どこに追加すればよいでしょうか？
After（CLAUDE.mdあり）¶
Q: 「新しいコンポーネントを追加して」
A: src/components配下にTypeScriptとTailwind CSSを使用したコンポーネントを作成します。
よくある質問¶
Q: ファイル名は小文字でも動作しますか？¶
A: 技術的には動作しますが、CLAUDE.md（大文字）が推奨されています。
Q: どこに配置すべきですか？¶
A: プロジェクトのルートディレクトリに配置してください。.claude/CLAUDE.md に配置することも可能です。
Q: 日本語で書いても大丈夫ですか？¶
A: はい、日本語で記述できます。チームの言語に合わせてください。
Q: CLAUDE.mdとCLAUDE.local.mdの違いは？¶
A: CLAUDE.md はGitで管理してチーム全員で共有します。CLAUDE.local.md は個人のローカル設定で、Gitにはコミットしません。
Q: /init で生成した内容はそのまま使えますか？¶
A: /init が生成する内容は良い出発点ですが、プロジェクト固有の規約やワークフローは手動で追加・調整することを推奨します。
次のステップ¶
基本的なCLAUDE.mdが作成できたら、以下の記事で更に活用方法を学びましょう：
- CLAUDE.md実践編 - プロジェクトタイプ別の詳細設定
- トラブルシューティング - よくある問題と解決方法
- ベストプラクティス - 上級者向けの最適化手法
まとめ¶
CLAUDE.mdは、AIアシスタントとのコミュニケーションを改善する簡単で効果的な方法です。 まずは /init コマンドや最小構成から始めて、プロジェクトの成長に合わせて徐々に詳細を追加していきましょう。メモリ階層やSkills・Subagentsを活用することで、より高度なAI支援を実現できます。
この記事は初心者向けの入門ガイドです。より詳細な設定方法については、上記の関連記事をご覧ください。