【Claude Code】プロジェクトの推奨ディレクトリ・ファイル構成テンプレートをわかりやすく解説

開発環境

• OS: Windows10（WSL2 / Ubuntu）
• Editor: Visual Studio Code
• Node.js: v22.22.2
• claude-code: 2.1.118

Claude Code のディレクトリ構成とは？

Claude Code は、プログラムのプロジェクトを管理し、AIを活用して効率的に開発を進めるためのツールです。このツールは、プロジェクト内にある特定のファイルやフォルダを読み込んで動作します。具体的には、プロジェクトの最も上の階層（ルートディレクトリ）にある CLAUDE.md というファイルと、.claude/ という名前の特別なフォルダの中にあるファイルを読み込みます。

これらのファイルやフォルダがそれぞれどのような役割を担っているのか、そしてどれをバージョン管理システムであるGitで管理すべきかを事前に整理しておくことは、特にチームで開発を行う際に非常に重要です。構成を理解することで、メンバー間で共通の認識を持ち、作業をスムーズに進めることができます。

プロジェクト直下の CLAUDE.md ファイルについて

プロジェクトのルートディレクトリに配置される CLAUDE.md ファイルは、Claude Code がプロジェクト全体に関する情報を把握するために最初に参照するファイルです。このファイルには、プロジェクトの目的や概要、Claude Code に実行させたい具体的なタスク、コード生成の際の指示などが記述されます。Claude Code はこのファイルを基にして、どのようにプロジェクトを進めるべきかを理解し、適切な応答やコードを生成します。

.claude/ ディレクトリ配下のファイルについて

.claude/ ディレクトリは、CLAUDE.md ファイルだけではカバーしきれない、より詳細な設定や補助的な情報を格納するために使われる特別なフォルダです。このディレクトリ内には、例えば以下のような種類のファイルが配置されることが考えられます。

• 特定の指示や設定ファイル: プロジェクトの特定の部分に対する、より細かい設定や制約を記述したファイルが含まれる場合があります。
• カスタムツールやスクリプト: Claude Code が特定の作業を行う際に利用する、独自のツールやスクリプトが格納されることがあります。
• 参照用ドキュメント: Claude Code がコード生成や修正を行う際に参考にすべき、追加のドキュメントやガイドラインが含まれることがあります。

これらのファイルは、プロジェクトのニーズに合わせてカスタマイズされ、Claude Code の動作をさらに細かく制御するために利用されます。

Git管理について

チームでプロジェクトを進める際、Gitのようなバージョン管理システムを使うことは一般的です。どのファイルをGitで管理するべきかを明確にしておくことは、チームメンバー全員が同じ環境で作業するために非常に重要です。

• CLAUDE.md: このファイルはプロジェクトの根幹に関わる指示や設定を含むため、通常はGitで管理し、チーム全体で共有します。これにより、すべてのメンバーが同じClaude Code の設定で作業を進めることができます。
• .claude/ ディレクトリ配下のファイル: このディレクトリ内のファイルも、プロジェクトの動作に影響を与える設定やツールを含むため、通常はGitで管理し、共有することが推奨されます。ただし、個人環境に依存する一時的なファイルや、機密情報を含むファイルは、Git管理から除外（.gitignore ファイルを使用して無視）すべきです。

どのファイルを共有し、どのファイルを個人で管理するかをチーム内で合意しておくことで、無用な混乱を避け、効率的な開発に繋がります。

公式ドキュメント: https://code.claude.com/docs/ja/claude-directory

ファイル・ディレクトリ一覧

この一覧は、your-project/という名前のプロジェクトフォルダの中に、どのようなファイルやフォルダが配置されているかを示しています。システム開発では、このようにファイルを整理して管理することが一般的です。

Copy
1your-project/
2├── CLAUDE.md                        ★ メインの指示書
3├── CLAUDE.local.md                  個人用メモ       ※ gitignore
4├── .mcp.json                        MCPサーバー設定
5├── .gitignore
6└── .claude/                         Claude Code 専用フォルダ
7    ├── CLAUDE.md                    指示書（.claude内配置版）
8    ├── settings.json                共有設定         ※ git管理
9    ├── settings.local.json          ローカル設定     ※ gitignore
10    ├── rules/                       ルール集
11    ├── commands/                    スラッシュコマンド（旧形式）
12    ├── skills/                      スラッシュコマンド（新形式）
13    ├── agents/                      サブエージェント定義
14    ├── hooks/                       フックスクリプト
15    ├── agent-memory/                エージェント記憶  ※ git管理
16    └── agent-memory-local/          エージェント記憶  ※ gitignore

• your-project/ これは、いま取り組んでいるプロジェクト全体の「根っこ」にあたるメインのフォルダです。プロジェクトに関するすべてのファイルやサブフォルダがこの中に含まれています。

• CLAUDE.md これは、プロジェクトのメインとなる指示書ファイルです。プロジェクトの目的や、重要な情報、作業手順などがMarkdown形式で記述されています。

• CLAUDE.local.md これは、個人的なメモを記録するためのファイルです。他の人と共有する必要のない、自分だけの作業メモや一時的な情報などを書き留めます。ファイル名の横に※ gitignoreと書かれているのは、このファイルがバージョン管理システム（Gitなど）の管理対象から除外され、共有されないように設定されていることを意味します。

• .mcp.json これは、MCPサーバーに関する設定ファイルです。MCPサーバーとは、特定のシステムを動かすためのサーバーのことで、このファイルにはそのサーバーが正しく動作するために必要な設定情報がJSON形式で記述されています。

• .gitignore これは、Gitというバージョン管理システムに対して、どのファイルをバージョン管理の対象から除外するかを指示するファイルです。例えば、先ほどのCLAUDE.local.mdのように、プロジェクトには含めるが、Gitの履歴には残したくないファイルやフォルダを指定します。

• .claude/ これは「Claude Code」という特定の開発ツールやサービス専用のフォルダです。このフォルダの中には、Claude Codeを使う上で必要となる様々な設定ファイルや機能が格納されています。

  • CLAUDE.md (.claude/内) .claudeフォルダの中にある指示書ファイルです。このファイルには、Claude Codeに関する具体的な利用方法や設定に関する指示が書かれていると考えられます。

  • settings.json これは、Claude Codeに関する共有設定ファイルです。このプロジェクトに関わるメンバー全員で共通して使うべき設定情報がJSON形式で記述されています。※ git管理と書かれているのは、この設定がGitでバージョン管理され、チームメンバーと共有されるべきものであることを示します。

  • settings.local.json これは、個々の開発環境に合わせたローカル設定ファイルです。例えば、自分のパソコンでだけ適用したいClaude Codeの設定などを記述します。※ gitignoreと書かれているのは、個人環境に特化した設定なので、Gitの管理対象から除外され、共有されないように設定されていることを意味します。

  • rules/ これは、ルール集を格納するためのフォルダです。例えば、コードの書き方に関するルール（コーディング規約）や、Claude Codeの動作に関する特定のルールなどがここにまとめられている可能性があります。

  • commands/ これは、スラッシュコマンド（旧形式）を格納するためのフォルダです。スラッシュコマンドとは、特定のツールで/コマンド名のように入力して、特定の機能を実行させる仕組みです。このフォルダには、以前の形式のスラッシュコマンドが格納されています。

  • skills/ これは、スラッシュコマンド（新形式）を格納するためのフォルダです。commands/と同様にスラッシュコマンドですが、こちらは新しいバージョンや改良された形式のものが格納されています。

  • agents/ これは、サブエージェントの定義を格納するためのフォルダです。サブエージェントとは、メインのシステムとは別に、特定のタスクや役割を専門的に担当する小さなプログラムやモジュールのことを指します。

  • hooks/ これは、フックスクリプトを格納するためのフォルダです。フックスクリプトとは、特定のイベント（例えば、ファイルを保存した時や、プログラムが実行される直前など）が発生した際に、自動的に実行されるプログラムのことです。

  • agent-memory/ これは、エージェント（AIや自動化プログラムなど）が過去に学習した情報や処理履歴などの「記憶」を格納するためのフォルダです。※ git管理と書かれているのは、この記憶情報がGitでバージョン管理され、チームメンバーと共有されるべきものであることを示します。

  • agent-memory-local/ これは、ローカル環境で利用されるエージェントの記憶を格納するためのフォルダです。agent-memory/とは異なり、個人的な環境に特化した記憶情報が保存されます。※ gitignoreと書かれているのは、この記憶情報がGitの管理対象から除外され、共有されないように設定されていることを意味します。

各ファイル・フォルダの説明

1. CLAUDE.md ★ 最重要

CLAUDE.md は、Claude Code というAI開発ツールが、プロジェクトを開くたびに自動で読み込む指示書です。

ここに書かれている内容は、ClaudeというAIアシスタントが毎回必ず読み込みます。プロジェクトの目標、開発のルール、使うべき技術、便利なコマンドなど、AIに守ってほしいことや、AIにどう動いてほしいかを具体的に記述します。

このファイルはGitで管理し、チームのメンバー全員で共有します。これにより、全員が同じ認識でプロジェクトを進めることができます。

git管理してチームで共有します。

2. CLAUDE.local.md

CLAUDE.local.md は、自分個人のパソコンだけに適用される指示書です。

これは CLAUDE.md の後に読み込まれるため、CLAUDE.md に書かれている共通のルールを、自分だけの設定で一時的に変更したり、追加したりすることができます。

例えば、以下のような内容を記述できます。

• 自分のローカル環境（開発しているパソコン上）でのみ有効なURL情報
• テストをするための個人用アカウント情報
• 他のチームメンバーには影響を与えず、自分だけに適用したい開発ルール

このファイルはGitの管理から除外し、チームには共有しません。

gitignore に登録してチームには共有しません。

3. .mcp.json

.mcp.json は、MCP（Model Context Protocol）サーバー の設定ファイルです。

MCPサーバーとは、ClaudeというAIアシスタントが、データベースやSlack、GitHubなどの外部のツールやサービスと連携するための橋渡しをする仕組みです。このファイルには、AIが外部ツールに接続するために必要な情報や、許可する操作などを設定します。

参考: MCP ドキュメント

4. .claude/CLAUDE.md

.claude/CLAUDE.md は、プロジェクトのルートディレクトリにある CLAUDE.md と同じ役割を持つファイルです。

どちらを使ってもAIへの指示書としての機能は同じですが、.claude/ というフォルダ内にまとめたい場合にこちらを使用します。プロジェクト内でどちらか一方を使えば問題ありません。

5. .claude/settings.json

.claude/settings.json は、プロジェクト全体に適用される Claude Code の設定ファイルです。

このファイルには、プロジェクト全体に影響する様々な設定を記述します。

• 使用モデルの指定: AIアシスタントとして、どの種類のAIを使うかを設定します。
• ツールの許可・禁止: AIにどのツールを使わせて良いか、または使わせてはいけないかを設定します。
• フックの設定: 特定のタイミングで自動的に実行される処理（フックスクリプト）を定義します。
• 環境変数: プログラムが動作するために必要な環境固有の値（例: APIキー）を設定します。

このファイルはGitで管理し、チーム全員で共有します。

git管理してチームで共有します。

6. .claude/settings.local.json

.claude/settings.local.json は、自分のパソコンだけに適用されるローカル設定ファイルです。

settings.json で定義されたプロジェクト全体の設定よりも優先されるため、自分個人の環境に合わせて設定を上書きすることができます。これにより、チームの共通設定に影響を与えずに、自分の開発環境を調整することが可能です。

このファイルはGitの管理から除外し、チームには共有しません。

gitignore に登録してチームには共有しません。

7. .claude/rules/

.claude/rules/ フォルダは、セッション開始時にClaudeというAIアシスタントが自動で読み込むルール集を置く場所です。

Copy
1rules/
2├── code-style.md   コーディングスタイル
3├── testing.md      テストの書き方
4└── security.md     セキュリティルール

このフォルダ内に.md（Markdown）形式のファイルを置くだけで、AIはその内容をプロジェクトのルールとして認識します。例えば、コードの書き方、テストの方法、セキュリティに関する注意点などをファイルに分けて記述できます。

ファイルを細かく分けることで、ルールを管理しやすく、また特定の種類のルールをまとめて参照しやすくなります。サブフォルダを使ってさらに細かく整理することも可能です。

8. .claude/skills/ （新形式・推奨）

.claude/skills/ フォルダは、カスタムスラッシュコマンドを定義するための場所です。

Copy
1skills/
2└── deploy/
3    └── SKILL.md    → /deploy で呼び出せる

スラッシュコマンドとは、AIに対して特定の作業を指示する際に使う、/コマンド名 の形式で実行できるショートカット。このフォルダのサブフォルダ名がそのままコマンド名になります。

例えば、skills/deploy/SKILL.md というファイルを作成すると、AIに対して /deploy というコマンドで特定のデプロイ（プログラムを公開する）作業を実行させることができます。

参考: Skills リファレンス

9. .claude/commands/ （旧形式・後方互換）

.claude/commands/ フォルダも、skills/ フォルダと同じくスラッシュコマンドを定義する場所でした。

Copy
1commands/
2└── deploy.md    → /deploy で呼び出せる

現在は skills/ フォルダに機能が統合されたため、新しいスラッシュコマンドを作成する際には skills/ フォルダを使用することが推奨されています。しかし、既存の commands/ フォルダ内のファイルは引き続き正常に動作します。

10. .claude/agents/

.claude/agents/ フォルダは、カスタムサブエージェントを定義するための場所です。

サブエージェントとは、ClaudeというAIアシスタントの中で、特定の複雑なタスクを専門的に、そして自律的に処理する小さな専門家AI。これにより、AIアシスタント全体の作業効率を高めることができます。

.md ファイル1つにつき、1つのサブエージェントを定義します。ファイルの冒頭には、--- で囲まれたフロントマターという部分があり、そこにエージェントの名前、説明、そしてそのエージェントが使えるツールなどを設定します。

参考: Sub-agents ガイド

11. .claude/hooks/

.claude/hooks/ フォルダは、フックスクリプトを置く場所です。

フックスクリプトとは、特定のイベント（出来事）が発生した際に、自動的に実行されるプログラムのことです。Claude Codeでは、AIがツールを実行する前や後、セッションの開始時など、様々なタイミングでフックスクリプトを走らせることができます。

このフォルダにスクリプトファイルを置き、.claude/settings.json の hooks セクションで、どのタイミングでどのスクリプトを実行するかを設定して使います。

タイミング	説明
PreToolUse	Claudeが外部ツールを実行する前に走るスクリプトです。
PostToolUse	Claudeが外部ツールを実行した後に走るスクリプトです。
SessionStart	Claude Codeのセッション（作業開始）時に走るスクリプトです。
Stop	Claudeが応答（回答や作業）を終えたときに走るスクリプトです。

参考: Hooks ガイド

12. .claude/agent-memory/

.claude/agent-memory/ フォルダは、ClaudeというAIアシスタント（エージェント）が記憶した情報を保存する場所です。

AIがプロジェクトの作業を進める中で学習したことや、繰り返し使うべき重要な情報などを記憶としてここに保存します。この記憶は、チームの他のメンバーにも共有したい内容を置くために使われます。

このフォルダもGitで管理し、チーム全体で記憶を共有することで、AIの学習効果をメンバー間で共有できます。

git管理してチームで共有します。

13. .claude/agent-memory-local/

.claude/agent-memory-local/ フォルダは、自分のパソコンだけに保存する、AIアシスタントの記憶を置く場所です。

これは、チーム全体で共有する必要のない、個人用のAIの記憶を保存するために使われます。例えば、自分が行った一時的なテストの結果や、自分だけが参照したい個人的なメモなどが該当します。

このフォルダはGitの管理から除外し、チームには共有しません。

gitignore に登録してチームには共有しません。

Gitはプログラムのソースコードや関連ファイルをバージョン管理するためのツールです。しかし、すべてのファイルをGitで管理する必要があるわけではありません。例えば、開発者のパソコンでのみ使用する一時ファイルや、個人の設定情報が含まれるファイルなどは、Gitのリポジトリに含めるべきではありません。

このような「Gitで管理したくないファイル」をGitに無視させるための設定ファイルが.gitignoreです。.gitignoreファイルにファイル名やフォルダ名を記述することで、Gitはそれらのファイルをバージョン管理の対象から外します。これにより、不要なファイルがリポジトリにコミットされるのを防ぎ、プロジェクトをきれいに保つことができます。

gitignore 対象ファイル一覧

ファイル	理由
CLAUDE.local.md	個人設定のため
.claude/settings.local.json	個人設定のため
.claude/agent-memory-local/	個人の記憶のため

上記のファイルやフォルダは、特定のプロジェクトでgitignoreの対象として設定されています。それぞれの理由について詳しく説明します。

• CLAUDE.local.md: このファイルは「個人設定のため」と指定されています。これは、開発者一人ひとりが自身の作業環境や好みに合わせて設定を記述するファイルであることを意味します。プロジェクト全体で共有すべき内容ではないため、Gitの管理対象から除外することで、各開発者が自由に設定を調整できるようになります。

• .claude/settings.local.json: こちらも「個人設定のため」とあります。JSON形式で書かれた設定ファイルで、特定のツールや環境における開発者個人の設定情報が含まれています。他の開発者の環境には関係のない情報であり、共有するとかえって混乱を招く可能性があるため、gitignoreの対象として適切です。

• .claude/agent-memory-local/: このフォルダは「個人の記憶のため」と説明されています。これは、開発ツールなどが、開発者個人の作業履歴や一時的なデータ、AIエージェントの記憶情報などを保存する場所であることを示唆しています。これらの情報は他の開発者には不要であり、また非常に容量が大きくなることもあるため、Gitで管理する必要はありません。

このように、gitignoreは、プロジェクトのコードや共有すべき設定ファイルだけをGitで管理し、開発者個人の環境設定や一時的なファイルを区別するために非常に重要な役割を果たします。これにより、チーム開発がスムーズに進み、不要なファイルの混入を防ぐことができます。

おわりに

本記事では、システム開発でAIアシスタントを活用するためのClaude Codeプロジェクトの推奨ディレクトリ・ファイル構成を解説しました。プロジェクト全体の指示書であるCLAUDE.mdや、settings.jsonなどの共有設定ファイルがAIの動作にどう関わるかを具体的に学びました。また、CLAUDE.local.mdやsettings.local.jsonのように個人環境に特化したファイルはGitの管理対象から外し、gitignoreで除外することの重要性も理解できました。このような構成を理解することで、チーム開発において共有すべき情報と個人の設定を適切に管理し、効率的に作業を進めることができます。