Claude Code導入時の設定ファイル完全ガイド：効率的なAI開発の基盤を築く

Claude Codeを新規プロジェクトに導入しようとしたとき、まず頭を悩ませるのが「どの設定ファイルをどこに置けばいいのか」「それぞれに何をどう書けば、AIが意図通りに動いてくれるのか」という点ではないでしょうか。AIによるコード生成や自動化は開発効率を大きく引き上げますが、その恩恵を最大限に受けるには、初期段階での適切な設定とファイル構成が欠かせない。設定が曖昧だったり、複数のファイルに散らばったりしていると、後から「この指示はどこから来ているんだ？」と混乱したり、AIが予期せぬコードを生成したりする原因にもなりかねません。（出典: Anthropic）

この記事は、Claude Codeを初めて使う個人開発者や、AIコーディングを業務で試したい初級〜中級エンジニア、そしてAI開発環境を効率的に整えたい小規模チームを対象にしています。新規リポジトリでClaude Codeの主要な設定ファイル（CLAUDE.md、.claude/settings.json、.mcp.json、hooks、skills）の役割を理解し、それぞれに記述すべき内容を判断できるようになるのがゴールだ。設定の混乱を避け、効率的なAI開発の基盤を構築するための具体的な判断軸と、見落としがちなポイントを提示していきます。（出典: Claude Code）

Claude Codeプロジェクトの全体像：設定ファイル群の役割

Claude Codeは、プロジェクトのルートディレクトリや.claudeディレクトリ配下に配置される複数のファイルを読み込んで動作します。これらのファイルは、AIへの指示、プロジェクト固有の設定、外部ツールとの連携、自動化スクリプトなど、それぞれ異なる役割を担っている。まずは、プロジェクト全体のファイル構成と各ファイルの基本的な役割を把握しておくのが、混乱を避けるための第一歩になるでしょう。（出典: Connect Claude Code to tools via MCP）

典型的なClaude Codeプロジェクトのディレクトリ構造は、以下のような形が考えられます。

. (プロジェクトルート)
├── CLAUDE.md       # Claude Codeへのメイン指示ファイル
├── .claude/        # Claude Codeの動作設定を格納するディレクトリ
│   ├── settings.json # プロジェクト固有の詳細設定
│   ├── skills/     # 特定のタスクを実行するためのスキル定義
│   │   └── my_skill.py
│   └── hooks/      # 特定のイベント時に自動実行されるスクリプト
│       └── pre_commit.sh
├── .mcp.json       # Model Context Protocol (MCP) の設定ファイル
├── src/            # ソースコードなど
└── ...

想定ケース: Claude Codeでファイル編集やBash実行を任せ始めたリポジトリに、最小限のhooksを入れる場面を想定します。読者が持ち帰る成果物は、.claude/settings.jsonの小さなhooks設定、危険コマンドを止めるスクリプト、自動整形をどこまで許可するかの判断メモです。（出典: Best practices for Claude Code）

使う判断: PostToolUseで整形やログ保存を走らせる、PreToolUseで危険なBashだけを止める、といった決定的で小さい処理はhooksに向いています。（出典: Claude Code）

止める判断: 秘密情報の送信、広い外部権限、破壊的なGit操作、確認なしのデプロイは、人間が差分とログを見てから進めます。

自動化したい作業を1つ選ぶ
↓
PreToolUseかPostToolUseかを決める
↓
.claude/settings.jsonに最小設定を書く
↓
スクリプト単体でログと終了コードを確認する
↓
Claude Code上で小さい差分だけに適用する

主要設定ファイル：CLAUDE.mdとsettings.jsonの使い分け

Claude Codeの挙動を制御する上で、最も頻繁に触れることになるのがCLAUDE.mdと.claude/settings.jsonでしょう。これらはAIへの指示と、その指示を補完する詳細な設定を記述する場所です。

CLAUDE.md: AIへのメイン指示書

CLAUDE.mdは、Claude Codeに対する主要な指示、タスクの要件、プロジェクトの背景情報などを記述するMarkdownファイルです。これはAIがコードを生成したり、タスクを実行したりする際の「憲法」のようなものだと考えると、その重要性が伝わるかもしれません。ここに書かれた内容が、Claude Codeの行動の大部分を決定します。

• 記述すべき内容: プロジェクトの目的、コード規約、アーキテクチャの概要、現在のタスク、考慮すべき制約事項、禁止事項など。具体的な変更指示や、コードのレビュー観点などもここに含めると良いでしょう。

外部連携を強化するSkillsとMCPの役割

Claude Codeは、単にコードを生成するだけでなく、外部ツールと連携したり、複雑なタスクを自動化したりする能力を持っています。これを可能にするのが、SkillsとModel Context Protocol (MCP) です。

.claude/skills: 特定のタスクを実行するカスタムツール

.claude/skillsディレクトリには、Claude Codeが実行できるカスタムツール（スキル）をPythonスクリプトとして定義します。例えば、特定のAPIを呼び出す、データベースを検索する、テストを実行するといった、AIが直接できない操作をスキルとして与えることで、その能力を拡張できます。

自動化の境界線：hooksファイルの活用と注意点

.claude/hooksディレクトリには、Claude Codeの特定のイベント（例えば、コード生成後やコミット前など）に自動的に実行されるスクリプトを配置できます。これは、生成されたコードの自動整形、テストの実行、リンティングなど、開発ワークフローにおける定型作業を自動化するのに役立つ機能です。

• 記述すべき内容: シェルスクリプトやPythonスクリプトなど、実行可能なファイル。例えば、post_generateフックを使って、Claude Codeが生成したPythonコードをコミットする前に自動的にblackフォーマッターで整形する、といった使い方が考えられます。

• 配置の判断: Claude Codeの作業結果に対して、常に実行すべき確認作業や整形作業がある場合にhooksを活用します。ただし、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のログ、終了コード、差分の範囲を確認できるか

新規プロジェクト向け：設定ファイルの記述判断ガイドと管理のポイント

これらのファイルを新規プロジェクトでどう使い分けるか、迷うこともあるでしょう。そこで、各ファイルに何を記述すべきか、簡単な判断ガイドを以下に示します。

新しい設定や指示がある？
│ ├─── プロジェクトの目的やタスクの要件、AIへの振る舞い指示？
│     └───> CLAUDE.md に記述
│ ├─── AIモデルの挙動や全体的な制限（モデル名、温度、トークン数など）？
│     └───> .claude/settings.json に記述
│ ├─── 外部サービスとの連携が必要（GitHub、Linearなど）？
│     └───> .mcp.json に認証・権限を設定
│ ├─── 特定のAPI呼び出しやDB操作をAIにさせたい？
│     └───> .claude/skills/ にカスタムスキルを定義
│ └─── AI作業後の自動実行タスク（テスト、整形、リンティングなど）？
└───> .claude/hooks/ にスクリプトを配置

避けるべき失敗と人間が確認するリスト

効率的なAI開発ワークフローを確立するための次の一手

Claude Codeのプロジェクト構造を理解し、適切に設定ファイルを配置することは、効率的で安全なAI開発ワークフローを確立するための基盤となります。初期段階で少し手間をかけてでも、これらのファイルの役割を整理し、チーム内で共通認識を持つことが、後々の開発をスムーズに進める鍵となるでしょう。

次に試してほしいのは、実際に小さなタスクをClaude Codeに依頼し、各設定ファイルがどのようにその動作に影響を与えるかを体験してみることです。例えば、新しいスキルを一つ作成し、それを使って特定の情報を取得するタスクをClaude Codeに実行させてみる。そして、その結果がsettings.jsonのtemperatureの値でどう変わるか、CLAUDE.mdの指示でどう調整されるかを見てほしい。この実践を通じて、各ファイルの「生きた役割」がより深く理解できるはずです。また、設定ファイルを変更する際は、変更履歴をしっかり残し、チームで共有する習慣をつけることを強くおすすめします。そうすることで、将来的なトラブルシューティングも格段に楽になるでしょう。

参考文献

Anthropic / Claude Code / Connect Claude Code to tools via MCP / Best practices for Claude Code / Claude Code