Claude Codeを使い始めたとき、プロジェクト内に点在する設定ファイル群に戸惑う開発者は少なくないでしょう。CLAUDE.md、.claude/settings.json、skillsディレクトリ、そしてmcp.jsonやhooksといったファイルがそれぞれどんな役割を持ち、どこに何を記述すべきか、最初は迷ってしまうものです。しかし、これらのファイルを適切に配置し、役割を明確にすることで、Claude Codeへの依頼は格段にスムーズになり、手戻りを大きく減らせます。（出典: Anthropic）
この記事では、Claude Codeのファイル構成における「どこに何を書くべきか」という判断軸を明確にし、新規プロジェクトで迷わないための理想的な配置ガイドを提供します。コピペできる依頼文テンプレートと、AIの生成結果を人間がレビューする際のチェックリストも用意したので、Claude Codeを初めて触る個人開発者から、AI開発環境を整えたい小さなチームまで、今日から実践できる具体的な成果物を得られるはずです。（出典: Claude Code）
Claude Codeのファイル構成、なぜ迷うのか？
Claude Codeは、プロジェクトの根幹に関わるAIアシスタントだからこそ、その設定ファイルは多岐にわたります。例えば、プロジェクトの全体方針を記述するCLAUDE.md、モデルの挙動や出力形式を制御する.claude/settings.json、特定のタスクを実行するカスタムスキルを定義する.claude/skillsディレクトリ、外部ツールとの連携を管理する.mcp.json、そして特定のイベントで自動実行されるhooks。これら全てが.claudeディレクトリ配下に集約されるものの、それぞれの役割が曖昧だと、いざ設定しようとしたときに「これはCLAUDE.mdに書くべきか、それともsettings.jsonか？」と悩む場面が出てきます。（出典: Connect Claude Code to tools via MCP）
この混乱は、各ファイルが持つ「スコープ」と「目的」が明確でない場合に起こりがちです。プロジェクト全体のガイドラインなのか、特定のAIモデル設定なのか、外部連携の定義なのか。この違いを理解しないまま設定を進めると、意図しない挙動につながったり、チームメンバー間での認識のずれを生んだりする原因にもなります。まずは、それぞれのファイルが何のために存在するのか、その本質を捉えるところから始めたいところです。（出典: Best practices for Claude Code）
想定ケース: Claude Codeでファイル編集やBash実行を任せ始めたリポジトリに、最小限のhooksを入れる場面を想定します。読者が持ち帰る成果物は、.claude/settings.jsonの小さなhooks設定、危険コマンドを止めるスクリプト、自動整形をどこまで許可するかの判断メモです。（出典: Claude Code）
使う判断: PostToolUseで整形やログ保存を走らせる、PreToolUseで危険なBashだけを止める、といった決定的で小さい処理はhooksに向いています。
止める判断: 秘密情報の送信、広い外部権限、破壊的なGit操作、確認なしのデプロイは、人間が差分とログを見てから進めます。
自動化したい作業を1つ選ぶ
↓
PreToolUseかPostToolUseかを決める
↓
.claude/settings.jsonに最小設定を書く
↓
スクリプト単体でログと終了コードを確認する
↓
Claude Code上で小さい差分だけに適用する
| イベント | 向いている用途 | 人間の確認 |
|---|---|---|
| PreToolUse | 危険なBashや秘匿ファイルアクセスを止める | ブロック条件が広すぎないか |
| PostToolUse | 整形、lint、ログ保存を実行する | 失敗時に作業を壊さないか |
| Stop | 完了前の最終チェックを走らせる | 長時間処理にならないか |
新規プロジェクトで迷わない！理想のファイル配置ガイド
新しいプロジェクトを始める際、Claude Codeの設定ファイル群をどのように配置すれば、後々の運用が楽になるでしょうか。推奨されるのは、.claudeディレクトリ配下に役割ごとにファイルを整理し、それぞれが持つ情報を明確にすることです。これにより、プロジェクトの成長に合わせて設定を追加・変更する際も、どこを修正すればよいか一目でわかるようになります。
以下は、新規プロジェクトで推奨される.claudeディレクトリのファイル構成例です。
.
├── .claude/
│ ├── CLAUDE.md # プロジェクト全体のAI利用方針、主要なスキル呼び出し方
│ ├── settings.json # モデル設定、出力形式、AIの振る舞いに関する詳細設定
│ ├── skills/ # カスタムスキル定義ディレクトリ
│ │ ├── skill-name-1/
│ │ │ └── SKILL.md # スキルの説明と使い方
│ │ │ └── main.py # スキルの実行スクリプト
│ │ └── skill-name-2/
│ │ └── SKILL.md
│ │ └── main.js
│ ├── mcp.json # 外部ツ…
「共通ルール」と「個別手順」の住み分け：CLAUDE.mdとsettings.jsonの使い分け
Claude Codeの設定で特に迷いやすいのが、CLAUDE.mdと.claude/settings.jsonの使い分けです。どちらもAIの挙動を左右する重要なファイルですが、それぞれが担う役割は異なります。簡単に言えば、CLAUDE.mdは「プロジェクト全体の共通ルールやガイドライン」を、settings.jsonは「AIモデルの具体的な挙動を制御する個別設定」を記述する場所だと考えると、整理しやすいでしょう。
CLAUDE.mdは、プロジェクトのルートディレクトリに置かれることが多いMarkdownファイルです。ここには、AIに期待する役割、コード規約、主要なスキルやツールの呼び出し方、AIが参照すべきドキュメントへのリンクなど、プロジェクト全体で共有すべき「AIとの協業ガイドライン」を記述します。人間が読んでも理解しやすい形式で、AIがプロジェクトの文脈を把握するための重要な情報源となるわけです。
一方、.claude/settings.jsonは、より技術的で具体的なAIモデルのパラメータや動作設定をJSON形式で記述します。例えば、使用するAIモデルの指定、出力の冗長性、特定のスキルを呼び出す際のデフォルト引数、出力形式（JSON、Markdownなど）の制約といった内容です。これらは、AIの「思考プロセス」や「出力形式」に直接影響を与える、いわばAIの「脳みそ」を調整する部分と言えるでしょう。
スキルと外部連携の設計：skillsディレクトリとMCPの役割
Claude Codeの真価は、単なるテキスト生成にとどまらず、外部ツールと連携したり、特定のカスタムロジックを実行したりできる点にあります。この機能を支えるのが、.claude/skillsディレクトリとmcp.jsonです。
.claude/skillsディレクトリは、独自のカスタムスキルを定義するための場所です。例えば、「特定のデータベースからデータを取得して要約する」「特定のAPIを呼び出して情報を更新する」「複雑なコード変換ロジックを実行する」といった、Claude Codeの標準機能だけでは難しい処理を、PythonやJavaScriptなどのスクリプトとして記述し、AIから呼び出せるようにします。各スキルは通常、専用のサブディレクトリにSKILL.md（スキルの説明）と、実行可能なスクリプト（例: main.py）を配置する形が一般的です。これにより、AIは特定のタスクを依頼された際に、どのスキルを使えばよいかを判断し、実行できるようになります。
一方、mcp.json（Model Control Plane）は、Claude Codeが外部ツールやサービスと連携する際の「橋渡し役」を担います。ここには、AIがアクセスを許可される外部APIのエンドポイント、必要な認証情報（ただし、直接的な秘密情報の記述は避け、環境変数などを参照させるのが安全）、そしてAIが実行できるコマンドのホワイトリストなどを定義します。mcp.jsonは、AIの「行動範囲」と「権限」を明確にすることで、意図しない外部へのアクセスや破壊的な操作を防ぐための重要なセキュリティレイヤーとして機能します。
自動化の安全弁：hooksの適切な配置と実行判断
開発ワークフローの効率化において、自動化は欠かせません。Claude Codeのhooks機能は、コミット前やマージ後といった特定のイベント発生時に、あらかじめ定義したスクリプトを自動で実行できるため、コードフォーマット、Linter、テストの自動実行などに非常に強力です。しかし、その便利さの裏には、意図しない破壊的な変更や情報漏洩のリスクも潜んでいます。
hooksは、主に.claude/hooksディレクトリ配下に設定ファイルを置くことで機能します。例えば、pre-commit.shにはコミット前にコードのリントやテストを実行するコマンドを、post-merge.pyにはマージ後のビルドスクリプトを記述するといった使い方が考えられます。ここで重要なのは、実行されるコマンドが、AIによって生成されたコードの品質を担保しつつ、開発環境に不測の事態を引き起こさない範囲に限定することです。
hooksで実行してよい処理と避けるべき処理
Claude Codeへの依頼例
依頼例1:
対象ファイル: .claude/settings.json と .claude/hooks/block-dangerous-commands.sh
変更範囲: Bash実行前に git reset --hard、git push --force、rm -rf を止めるPreToolUse hookを追加する
制約: 既存設定を消さず、ブロック時は理由をstderrに出す
確認観点: 通常のgit statusは通り、危険コマンドだけが止まるか
依頼例2:
対象ファイル: .claude/settings.json と package.json
変更範囲: EditまたはWrite後に対象ファイルだけprettierを走らせるPostToolUse hookを追加する
制約: 失敗しても作業ファイルを壊さず、対象外ファイルへ広げない
確認観点: hookのログ、終了コード、差分の範囲を確認できるか
依頼文テンプレートと人間が確認するリスト：設定を活かす実践例
これまでのファイル構成の理解を基に、Claude Codeに具体的な作業を依頼する際の依頼文テンプレートと、その結果を人間がレビューする際のチェックリストを見ていきましょう。抽象的な依頼はAIの解釈に幅を持たせ、意図しない結果を招きがちです。明確な依頼文は、手戻りを減らし、効率的な開発を可能にします。
依頼文は、以下の4つの要素を意識して構成すると良いでしょう。
- 対象ファイル/ディレクトリ: 変更を加える具体的な場所。
ファイル構成の継続的な見直しとチームでの運用
Claude Codeのファイル構成は、一度決めたら終わりではありません。プロジェクトの成長、チームメンバーの増加、新しい技術の導入など、状況は常に変化します。そのため、定期的にファイル構成を見直し、現在のプロジェクトのニーズに合致しているかを確認する時間を設けることをおすすめします。
特に、新しい機能を追加する際や、大規模なリファクタリングを行う際は、その変更がファイル構成にどう影響するかを事前に検討する良い機会です。例えば、特定のドメイン知識を持つスキルが増えてきたら、skillsディレクトリ配下をさらにサブディレクトリで整理する、といった判断も必要になるでしょう。
チームでClaude Codeを運用する場合は、ファイル構成に関する合意形成が非常に重要です。どのファイルにどのような情報を記述するか、誰がそのファイルを管理・更新するのか、といったルールを明確にし、すべてのメンバーが理解し遵守することが、スムーズなAI協業の鍵となります。新しいメンバーが加わった際には、このファイル構成ガイドを共有し、AIとの効果的な連携方法を早期に習得してもらうのも良いでしょう。
参考文献
Anthropic Claude Code Connect Claude Code to tools via MCP Best practices for Claude Code Claude Code