Claude Codeをプロジェクトに導入する際、「どこに何を配置すべきか」と戸惑う場面は多いはずだ。CLAUDE.md、.claude/settings.json、skills、.mcp.json、そしてhooks……と、設定ファイルが複数あると、それぞれに何を書き、どこに置くべきか判断に迷う人も少なくないだろう。設定が散らばってしまい、結局どれが正しい情報なのか分からなくなる。そんな混乱を経験した開発者は、きっといるに違いない。実は、この設定の「散らばり」こそが、Claude Codeの能力を最大限に引き出せない原因になっているケースも多いと見ている。（出典: Anthropic）
設定が曖昧だと、Claude Codeは期待通りの動きをしてくれない。最悪の場合、意図しないファイル変更やコマンド実行で、プロジェクトに損害を与える可能性すらある。特に、新規リポジトリで作業を始める個人開発者や小さなチームにとっては、この初期設定の壁が、AIを活用した開発ワークフロー導入の大きな障壁になりがちだ。（出典: Claude Code）
Claude Codeプロジェクトの基本構造を理解する
Claude Codeは、プロジェクトディレクトリ内の.claudeフォルダ、そしてホームディレクトリの~/.claudeから、指示、設定、スキル、サブエージェント、メモリといった情報を読み込んで動作する。このファイルシステムこそが、Claude Codeがプロジェクトをどのように解釈し、どのように動くかを決める、いわば「脳」のような役割を果たすと捉えられる。（出典: Connect Claude Code to tools via MCP）
ここでまず押さえておきたいのは、設定の「スコープ」の違いだ。プロジェクトルートにある.claudeフォルダは、そのプロジェクト固有の構成を保持する場所になる。これをGitで管理すれば、チームメンバー全員が同じルールやポリシーを共有できる。例えば、特定のコーディング規約や、プロジェクトで許可するBashコマンドのリストなど、チーム全体で守るべき「共通の約束事」をここに置くのが一般的だ。（出典: substack.com）
一方、グローバルな~/.claudeフォルダには、個人の設定やセッション履歴、自動メモリなど、ユーザーの作業環境全体に適用される設定が格納される。これは、エディタの設定や、個人がよく使うAIモデルの優先度など、他のプロジェクトには影響しない「自分だけのカスタマイズ」を置くのに適している。この「プロジェクト固有」と「個人環境全体」というスコープの違いをしっかり理解しておくことが、設定管理の最初の、そして最も重要なステップになる。ここを間違えると、意図せずチーム全体に影響を与えたり、逆に個人の設定がプロジェクトに反映されなかったりといった、小さなトラブルにつながりやすい。（出典: medium.com）
想定ケース: Claude Codeでファイル編集やBash実行を任せ始めたリポジトリに、最小限のhooksを入れる場面を想定します。読者が持ち帰る成果物は、.claude/settings.jsonの小さなhooks設定、危険コマンドを止めるスクリプト、自動整形をどこまで許可するかの判断メモです。（出典: medium.com）
使う判断: PostToolUseで整形やログ保存を走らせる、PreToolUseで危険なBashだけを止める、といった決定的で小さい処理はhooksに向いています。（出典: Best practices for Claude Code）
止める判断: 秘密情報の送信、広い外部権限、破壊的なGit操作、確認なしのデプロイは、人間が差分とログを見てから進めます。
| イベント | 向いている用途 | 人間の確認 |
|---|---|---|
| PreToolUse | 危険なBashや秘匿ファイルアクセスを止める | ブロック条件が広すぎないか |
| PostToolUse | 整形、lint、ログ保存を実行する | 失敗時に作業を壊さないか |
| Stop | 完了前の最終チェックを走らせる | 長時間処理にならないか |
主要な設定ファイルとそれぞれの役割
Claude Codeの挙動を細かく制御するために、いくつかの主要な設定ファイルが存在する。それぞれが異なる役割を担っているため、その特性を理解しておくことが、AIを意図通りに動かす鍵となるだろう。（出典: Claude Code）
-
CLAUDE.md: プロジェクトのルートディレクトリに配置するMarkdownファイルだ。Claude Codeがセッション開始時に最初に読み込むファイルであり、プロジェクトの目的、技術スタック、アーキテクチャ、コーディング規約、ファイル配置など、プロジェクト全体にわたる共通のルールやコンテキストを自然言語で記述する。Claude Codeが常に参照する「北極星」のような存在と考えるといい。ただし、あまりに多くの情報を詰め込みすぎると、Claude Codeが処理するコンテキストウィンドウを圧迫し、パフォーマンスが落ちる可能性もある。RedditやGitHubの議論でも、CLAUDE.mdが長くなりすぎて応答が遅くなったり、意図を正確に汲み取れなくなったりするケースが報告されている。簡潔に、しかし網羅的に書くバランスが求められる。具体的なコードスニペットや詳細な手順は、後述する
skillsに任せるのが賢明な選択肢だ。プロジェクトの「… -
.claude/settings.json: Claude Codeの権限、利用できるツール、フックの動作など、より機械的な設定をJSON形式で記述するファイルになる。CLAUDE.mdが「指針」だとすれば、settings.jsonは「強制力のあるガードレール」として機能する。例えば、Claude CodeがどのBashコマンドを実行できるか、どの外部ツールへのアクセスをブロックするか、あるいは特定の操作を自動承認するかどうかといった、セキュリティや安定性に直結する設定を定義できる。チームで共有するプロジェクトでは、このファイルで共通のセキュリティポリシーを強制するのが一般的だ。誤った設定は予期せぬ挙動やセキュリティリスクにつながるため、変更には慎重なレビューが欠かせない。特にbash_modeの設定は、AIが実行できるコマンドの範囲を直接制御するため、最小限の権限に絞るのが鉄則だ。auto_approveを安易に`tr… -
.claude/skills/: 再利用可能なワークフローや、特定のタスクに対する専門知識をパッケージ化して格納するディレクトリだ。各スキルは、そのスキルを説明するSKILL.mdファイルを含む独自のサブディレクトリに配置される。Claude Codeは、ユーザーのリクエスト内容に応じて、関連するスキルを自動的に読み込み、適用してくれる。例えば、プルリクエストのレビュー手順、特定のライブラリの利用ガイドライン、デプロイ前のコードチェックリストなどをスキルとして定義しておけば、開発プロセスを標準化し、チーム全体の生産性を高められる。スキルは、CLAUDE.mdで記述するには長すぎる、しかしプロジェクト全体で共有したい具体的な手順や知識を置くのに最適だ。例えば、特定のフレームワークの定型的なファイル生成や、複雑なテスト環境のセットアップ手順など、AIに「こうしてほしい」と具体的に伝えたい場面で真価を発揮する。
自動化したい作業を1つ選ぶ
↓
PreToolUseかPostToolUseかを決める
↓
.claude/settings.jsonに最小設定を書く
↓
スクリプト単体でログと終了コードを確認する
↓
Claude Code上で小さい差分だけに適用する
設定ファイル配置の判断基準：何をどこに書くか
Claude Codeの設定は、その適用範囲や性質によって配置場所を使い分けるのが賢明だ。複数のファイルに設定が散らばってしまい、「結局どれが優先されるんだ？」と混乱する事態を避けるためにも、以下の判断基準を参考にしてみてほしい。
まず、設定したい内容が「誰にとって」必要なのかを考えるのが良いだろう。個人開発者ならグローバル設定も選択肢に入るが、チーム開発ならプロジェクト固有の設定を優先すべきだ。次に、「どのような性質の設定か」を見極める。自然言語で記述するガイドラインなのか、それとも機械的に処理されるべきルールなのか。この二つの軸で考えると、配置場所が見えてくるはずだ。
設定の決定フロー
Claude Codeの自動化を安全に進めるためのチェックリスト
Claude Codeのhooks機能は非常に強力だが、その分、設定を誤ると予期せぬ問題を引き起こす可能性がある。特に、ファイルシステムへの変更や外部コマンドの実行を伴う場合、人間による慎重な確認が不可欠だ。ここでは、hooks設定を導入する際に、人間が確認すべきポイントをまとめた。
hooks設定導入時の人間による確認リスト
Claude Codeの自動化は、開発効率を大きく向上させる一方で、リスクも伴う。特にhooksのような自動実行される設定は、導入前に以下の点を徹底的に確認し、問題発生時の対応策も検討しておくことが重要だ。
人間が確認するリスト
- 差分に、依頼していないファイル変更が混ざっていないか。
- テスト、lint、型チェックの結果がログで確認できるか。
- .mcp.jsonやsettings.jsonに秘密情報の実値が入っていないか。
- MCPの権限が、今回の作業に必要な範囲だけになっているか。
- 問題が出たときに、Git差分を戻せる単位で作業できているか。
チーム開発におけるClaude Code設定の共有と管理
チームでClaude Codeを導入する際、設定の共有と管理は個人開発以上に重要になる。メンバー間で異なる設定を使っていると、AIの挙動に一貫性がなくなり、デバッグが困難になったり、共同作業の効率が落ちたりする。
GitOpsによる設定管理
最も推奨されるのは、プロジェクト固有の.claudeディレクトリ全体をGitで管理する「GitOps」のアプローチだ。
次に何を見るか：Claude Codeの進化と設定管理の視点
Claude Codeのようなエージェント型AIは、まだ進化の途上にある。今日の最適な設定管理が、明日もそうであるとは限らない。では、私たちは次に何に注目し、どのように設定管理の知識をアップデートしていけば良いのだろうか。
まず、Anthropicの公式発表やドキュメントは常にチェックしておきたい。新しい機能が追加されたり、既存の設定オプションが変更されたりする可能性は十分にある。特に、AIの権限管理やセキュリティに関するアップデートは、プロジェクトの安全性に直結するため、見逃さないようにしたいところだ。
次に、コミュニティの動向も重要だ。GitHubのIssueやRedditのフォーラムでは、実際の開発者がどのような課題に直面し、どのような解決策を試しているか、生の声が聞ける。CLAUDE.mdの最適な書き方、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のログ、終了コード、差分の範囲を確認できるか
参考文献
Anthropic Claude Code Connect Claude Code to tools via MCP substack.com medium.com medium.com Best practices for Claude Code Claude Code