Claude Codeをプロジェクトに導入しようとしたとき、まずどこから手をつければいいのか、どのファイルに何を書けばいいのか、迷う人は少なくないはずです。特に個人開発や少人数のチームで使い始める際、その設定ファイルの多さに少し戸惑うかもしれません。しかし、ここをしっかり押さえておけば、Claude Codeはあなたの意図を正確に汲み取り、開発を強力にサポートしてくれる頼もしい相棒になります。（出典: Anthropic）
この記事では、Claude Codeの「頭脳」を構成する主要な設定ファイル、特にCLAUDE.mdと.claude/settings.jsonに焦点を当て、それぞれの役割と適切な記述方法を具体的に解説します。読み終える頃には、新規プロジェクトでClaude Codeを導入する際の最適なファイル構成と、各ファイルにどのような情報を記述すべきかの判断基準が明確になっているでしょう。手元でClaude Codeを試し始めるための具体的なステップと、チームで運用する際の注意点も合わせて見ていきます。（出典: Claude Code）
Claude Codeの「頭脳」を構成するファイルたち
Claude Codeは、プロジェクトのルートディレクトリに置かれる.claudeという特別なディレクトリにその設定と能力のほとんどを格納しています。このディレクトリは、Claude Codeがプロジェクトの文脈を理解し、コードを生成・修正するための「頭脳」の役割を果たす場所です。ここが正しく設定されていなければ、Claude Codeは期待通りの動きをしてくれないかもしれません。（出典: Connect Claude Code to tools via MCP）
主な構成要素は以下の通りです。
CLAUDE.md: プロジェクト全体の目的、コーディング規約、技術スタックなどの高レベルな指示を記述するファイルです。
想定ケース: Claude Codeを初めてチームのリポジトリへ入れる場面を想定します。読者が持ち帰る成果物は、CLAUDE.md、.claude/skills、.mcp.json、hooksの置き場所を決める小さな設計メモです。（出典: Best practices for Claude Code）
使う判断: 繰り返す手順の整理、設定ファイルの下書き、差分の説明はClaude Codeに任せやすい作業です。
止める判断: 秘密情報、広い外部権限、破壊的なhooks、未確認のMCP接続は、人間が差分とログを見てから進めます。
人間がMCPとSkillsの範囲を決める
↓
Claude Codeに対象ファイルと制約を渡す
↓
Claude Codeが差分と実行ログを作る
↓
人間が権限、秘密情報、戻し方を確認する
↓
問題なければ反映する
| 置き場所 | 入れる内容 | 人間の確認 |
|---|---|---|
| CLAUDE.md | 共通ルール | 長すぎないか |
| .claude/skills | 繰り返す手順 | 実行条件が明確か |
| .mcp.json | 外部接続 | 権限が最小か |
CLAUDE.mdとsettings.json：役割を明確にする「二つの指針」
Claude Codeを効果的に使う上で、最も重要になるのがCLAUDE.mdと.claude/settings.jsonの使い分けです。これらはどちらもClaude Codeの振る舞いを規定しますが、その役割は大きく異なります。ここを混同してしまうと、設定が複雑になったり、意図しない挙動に悩まされたりする原因になりかねません。（出典: Claude Code）
CLAUDE.md：プロジェクトの「憲法」を定める
CLAUDE.mdは、Claude Codeにプロジェクトの全体像と、守るべきルールを伝えるための「憲法」のような存在です。ここに書かれた内容は、Claude Codeがコードを生成・修正する際の最も基本的な指針となります。プロジェクトの目的、主要な技術スタック、コードの品質基準、アーキテクチャの制約など、高レベルな情報を記述するのに適しています。
カスタム能力と自動化：SkillsとHooksをどう使うか
Claude Codeの能力をさらに拡張するのが、skillsとhooksです。これらはそれぞれ異なる役割を持ち、開発ワークフローの自動化を強力にサポートしますが、その導入には慎重な検討が求められます。
Skills：カスタム能力の定義
.claude/skills/ディレクトリには、Claude Codeに特定のタスクを実行させるためのカスタムスキルが定義されます。例えば、特定の外部APIを呼び出すスキルや、複雑なデータ変換ロジックを実行するスキルなどを作成できます。これにより、Claude Codeは単なるコード生成だけでなく、外部ツールとの連携や、より複雑な処理も実行できるようになります。スキルは再利用可能な形で定義されるため、複数のプロジェクトやタスクで共通の処理を効率的に実行できるのが大きなメリットです。
失敗を避ける：設定ファイルの落とし穴と確認ポイント
Claude Codeのファイル構造を効果的に活用するには、どこに何を置くべきかという明確な判断基準を持つことが重要です。ここで迷いやすいのは、共通のプロジェクトルールと、環境やタスク固有の設定をどう分けるかという点でしょう。
共通ルールと個別手順の分け方: CLAUDE.mdには、プロジェクト全体で共有すべき高レベルな指示や制約を記述します。これは、チームメンバー全員が合意し、頻繁には変更されない「プロジェクトの憲法」と位置づけたいですね。一方、.claude/settings.jsonは、個々の開発環境やタスクによって調整されうる実行時のパラメータを設定する場所です。モデルの選択や温度設定など、柔軟に変更したい項目はここに置くのが適切です。
避けるべき落とし穴: 最もよくある失敗は、設定が複数ファイルに散らばり、どれが「正」の設定なのか分からなくなることです。例えば、CLAUDE.mdに詳細なモデル設定を書き込みつつ、settings.jsonでも似たような設定をしてしまうと、どちらが優先されるのか、あるいは意図通りに動いているのかが不明瞭になります。また、settings.jsonで重要なプロジェクトルールを定義してしまうと、その設定が共有されにくく、チーム全体での一貫性が失われる可能性もあります。
Claude Codeへの依頼例
Claude Codeへの依頼例:
対象ファイル: CLAUDE.md と .claude/skills/release-check/SKILL.md
変更範囲: 共通ルールをCLAUDE.mdに残し、繰り返す確認手順をSkillへ分ける
制約: APIキー、接続文字列、社内URLの実値は書かない
確認観点: CLAUDE.mdが短く保たれ、SKILL.mdだけで実行手順が分かるか
Claude Codeへの依頼例:
対象ファイル: .mcp.json と .claude/settings.json
変更範囲: 外部ツール接続の責務と権限範囲を整理する
制約: トークンはプレースホルダーにし、読み取り権限から始める
確認観点: MCPが必要な作業、不要な作業、人間の承認が必要な作業が分かれているか
人間が確認するリスト
- 差分に、依頼していないファイル変更が混ざっていないか。
- テスト、lint、型チェックの結果がログで確認できるか。
- .mcp.jsonやsettings.jsonに秘密情報の実値が入っていないか。
- MCPの権限が、今回の作業に必要な範囲だけになっているか。
- 問題が出たときに、Git差分を戻せる単位で作業できているか。
導入の次へ：チームでClaude Codeを育てるために
Claude Codeのファイル構造を理解し、適切に設定することは、AIを開発ワークフローに組み込む上での第一歩です。今回解説したCLAUDE.mdと.claude/settings.jsonの役割を明確に区別し、それぞれのファイルに適切な情報を記述する習慣をつけましょう。
まずは最小限のCLAUDE.mdとsettings.jsonから始めて、プロジェクトのニーズに合わせて徐々にスキルやフックを追加していくのがおすすめです。急いで全ての機能を導入するよりも、少しずつ試しながら、その効果とリスクを見極めていくのが現実的だと感じます。
そして、チームでClaude Codeを運用する場合は、これらのファイル構造と設定に関する合意を事前に形成し、ドキュメント化しておくことが、将来的な混乱を防ぐ上で非常に重要になります。どの情報をどのファイルに書くか、誰が変更を承認するかといったルールを明確にしておくと、スムーズな運用につながるでしょう。
参考文献
Anthropic Claude Code Connect Claude Code to tools via MCP Best practices for Claude Code Claude Code