Claude Codeを新規プロジェクトに導入する際、まず頭を悩ませるのが、その設定ファイルの管理ではないでしょうか。CLAUDE.md、.claude/settings.json、.claude/skills、.mcp.jsonといった複数のファイルが連携し、AIの振る舞いを決定します。これらの役割を曖昧なまま使い始めると、設定が重複したり、意図しない動作を引き起こしたり、最悪の場合、セキュリティリスクにつながる可能性も出てきます。（出典: Anthropic）
この記事は、Claude Codeを初めて触る個人開発者や、AIコーディングを業務に導入したい初級〜中級エンジニア、そしてAI開発環境を整えたい小さなチームに向けて書きました。新規プロジェクトで迷うことなく最適なファイル構成を構築できるよう、各設定ファイルの役割と配置の判断基準を具体的に解説します。設定が散らばる混乱を避け、効率的かつ安全なAI開発ワークフローを確立するための実践的なヒントを掴んでいきましょう。（出典: Claude Code）
Claude Codeの振る舞いを決める主要な設定ファイル群
Claude Codeは、複数の設定ファイルを読み込むことで、その振る舞いをカスタマイズします。これらのファイルを適切に配置し、管理することが、AIとの協調開発をスムーズに進めるための第一歩となるでしょう。まずは、主要なファイルとディレクトリの役割を整理しておきたいところです。（出典: Connect Claude Code to tools via MCP）
CLAUDE.mdは、プロジェクト全体のAIに対する指示や制約、開発方針を記述する中心的なファイルです。これは人間が読むドキュメントとしての側面と、AIが参照するプロンプトとしての側面を併せ持っています。プロジェクトの共通認識を形成し、AIに期待する成果物の品質やスタイルを定義するのに役立つでしょう。（出典: medium.com）
次に、.claude/settings.jsonは、Claude Codeの環境固有の設定やパーミッションを管理します。例えば、AIがアクセスできるファイルの範囲や、特定のコマンドの実行許可などをここに記述します。開発環境や本番環境といった異なる状況に応じて、柔軟に設定を切り替えたい場面で活躍するファイルです。（出典: Best practices for Claude Code）
.mcp.jsonは、Model Context Protocol (MCP) の設定を定義するファイルで、Claude Codeが外部ツールやAPIと連携する際の認証情報やエンドポイントなどを記述します。AIが外部のサービスを利用してタスクを遂行する際に、安全かつ適切に接続するための橋渡し役を担っていると見ています。（出典: Claude Code）
想定ケース: Claude Codeを初めてチームのリポジトリへ入れる場面を想定します。読者が持ち帰る成果物は、CLAUDE.md、.claude/skills、.mcp.json、hooksの置き場所を決める小さな設計メモです。（出典: claude.com）
使う判断: 繰り返す手順の整理、設定ファイルの下書き、差分の説明はClaude Codeに任せやすい作業です。
止める判断: 秘密情報、広い外部権限、破壊的なhooks、未確認のMCP接続は、人間が差分とログを見てから進めます。
人間がMCPとSkillsの範囲を決める
↓
Claude Codeに対象ファイルと制約を渡す
↓
Claude Codeが差分と実行ログを作る
↓
人間が権限、秘密情報、戻し方を確認する
↓
問題なければ反映する
| 置き場所 | 入れる内容 | 人間の確認 |
|---|---|---|
| CLAUDE.md | 共通ルール | 長すぎないか |
| .claude/skills | 繰り返す手順 | 実行条件が明確か |
| .mcp.json | 外部接続 | 権限が最小か |
新規プロジェクトで迷わない.claudeディレクトリの構成と役割
これらのファイルを新規プロジェクトでどのように配置すべきか、迷う人もいるかもしれません。まずはシンプルな構造から始めるのが現実的だと考えます。以下に、一般的なプロジェクトで推奨される.claudeディレクトリの構成例を示します。（出典: claude.com）
プロジェクトルート/
├── .claude/
│ ├── CLAUDE.md
│ ├── settings.json
│ ├── mcp.json
│ └── skills/
│ ├── format_code.skill.md
│ └── run_tests.skill.md
└── (その他のプロジェクトファイル...)
この構成は、プロジェクトのルートディレクトリ直下に.claudeディレクトリを置き、その中に主要な設定ファイルを格納する形です。スキルはさらにskillsサブディレクトリにまとめることで、見通しが良くなります。各ファイルをどこに配置すべきか、その判断基準を簡単な表で整理してみましょう。
設定の重複と衝突を避けるための判断軸と秘密情報の管理
複数の設定ファイルが存在するため、どこに何を記述すべきか、迷う場面も出てきます。ここで重要なのは、設定のスコープと優先順位を理解することです。グローバルな設定とプロジェクト固有の設定、あるいはスキルとプロンプトの使い分けを明確にすることで、設定の重複や衝突を防ぎ、AIの挙動を一貫させられます。
一般的に、プロジェクト全体に適用される共通のルールや方針はCLAUDE.mdに記述します。例えば、どのプログラミング言語を使うか、どのようなアーキテクチャを目指すか、といった高レベルな指示がこれに当たります。一方、特定の環境でのみ有効な設定や、AIがアクセスできる具体的なディレクトリパスなどは.claude/settings.jsonに記述するのが適切です。もし複数の設定ファイル間で同じ内容が重複して記述されそうな場合は、一度立ち止まって、どちらのファイルがその設定の「本来の置き場所」なのかを確認したいところです。
秘密情報やAPIキーの管理は特に注意が必要です。.mcp.jsonに直接書き込むことも可能ですが、セキュリティの観点からは環境変数を利用する方が安全だとされています。.mcp.jsonには環境変数を参照する設定を記述し、実際の値は実行環境で設定するという運用が現実的でしょう。これにより、機密情報が誤ってバージョン管理システムにコミットされるリスクを避けられます。設定ファイル内にAPIキーなどの秘密情報を直接記述しようとしている場合は、環境変数利用を検討し、その行為を止めるべきです。
チームで進める設定ファイルの更新とレビューのポイント
設定ファイルは一度作ったら終わりではありません。プロジェクトの進捗やチームのニーズに合わせて、定期的に見直し、更新していく必要があります。特にCLAUDE.mdは、プロジェクトの「憲法」とも言えるファイルなので、チームメンバー全員でその内容を理解し、合意形成しながらメンテナンスしていくことが重要です。新しいルールを追加したり、古いルールを削除したりする際は、必ずレビュープロセスを設け、変更が意図しない影響を及ぼさないかを確認するべきでしょう。
.claude/settings.jsonは環境固有の設定を含むため、開発環境、テスト環境、本番環境など、それぞれの環境で適切な値が設定されているかを確認することが肝心です。特に、AIのファイルアクセス権限やコマンド実行の許可範囲は、セキュリティに直結するため、慎重な管理が求められます。バージョン管理システムで管理しつつも、環境ごとの差異を吸収する仕組みを検討しておきたいところです。
skillsディレクトリ内のスキルファイルは、汎用性を意識して作成することが、効率的な運用につながります。特定のプロジェクトに強く依存するスキルは避けるか、十分に抽象化して再利用可能な形に落とし込む工夫が必要だと見ているからです。また、使われなくなったスキルは定期的に棚卸しし、削除することで、ディレクトリの清潔さを保てるでしょう。
人間が確認するリスト
- 差分に、依頼していないファイル変更が混ざっていないか。
- テスト、lint、型チェックの結果がログで確認できるか。
- .mcp.jsonやsettings.jsonに秘密情報の実値が入っていないか。
- MCPの権限が、今回の作業に必要な範囲だけになっているか。
- 問題が出たときに、Git差分を戻せる単位で作業できているか。
人間が最終確認すべき設定ファイルの健全性チェックリスト
Claude Codeに設定ファイルの管理や更新を任せる場合でも、最終的な責任は人間にあります。AIの生成した設定や変更が適切であるか、セキュリティ上の問題がないかを人間が確認するプロセスは不可欠です。一般的な入門記事では、各ファイルの役割を個別に説明するに留まりがちですが、実務では設定が複数ファイルに散らばった際の整合性維持や、秘密情報の安全な管理、hooksのセキュリティリスクといった落とし穴に注意が必要です。以下に、設定ファイルの健全性を保つために人間が確認すべきリストを挙げます。
-
設定ファイルの整合性: 例えば、
settings.jsonで許可されていないコマンドが、CLAUDE.mdやskillsでAIに指示されていないか。スキル定義内で使われている外部ツールが、mcp.jsonで正しく設定されているか、といった点を確認します。 -
秘密情報の露出:
settings.jsonやmcp.json、あるいはskillsファイル内に、APIキーや認証情報などの秘密情報がハードコードされていないか、環境変数への参照が適切に行われているかを確認します。バージョン管理システムへのコミット前に必ずチェックしたい項目です。
Claude Codeへの依頼例
依頼例1:
対象ファイル: CLAUDE.md と .claude/skills/release-check/SKILL.md
変更範囲: 共通ルールをCLAUDE.mdに残し、繰り返す確認手順をSkillへ分ける
制約: APIキー、接続文字列、社内URLの実値は書かない
確認観点: CLAUDE.mdが短く保たれ、SKILL.mdだけで実行手順が分かるか
依頼例2:
対象ファイル: .mcp.json と .claude/settings.json
変更範囲: 外部ツール接続の責務と権限範囲を整理する
制約: トークンはプレースホルダーにし、読み取り権限から始める
確認観点: MCPが必要な作業、不要な作業、人間の承認が必要な作業が分かれているか
プロジェクトに合わせたClaude Code設定の最適化へ
Claude Codeのファイル構成は、プロジェクトの規模や複雑さ、チームの運用体制によって最適な形が異なります。まずはこの記事で紹介したようなシンプルな構成から始め、実際に使ってみる中で、どの情報をどこに置くのが最も効率的で管理しやすいかを判断していくのが良いでしょう。小さな試行錯誤を繰り返しながら、チーム独自のベストプラクティスを築き上げていくのが現実的だと見ているからです。
Anthropicの公式ドキュメントや、開発者コミュニティで共有されている事例も、設定のヒントになるはずです。特に、大規模プロジェクトでの運用例や、特定の課題を解決するためのカスタム設定などは、今後の参考になるかもしれません。急いで完璧な設定を目指すよりも、まずは手を動かし、Claude Codeとの対話を通じて、自分たちのプロジェクトに最適な設定のあり方を探っていくことをおすすめします。そうすることで、AIとの協調開発が、より確かなものになるはずです。
参考文献
Anthropic Claude Code Connect Claude Code to tools via MCP medium.com Best practices for Claude Code Claude Code claude.com claude.com