CLAUDE.md と settings.json の違い:何をどちらに書くか

公開: 2026年10月15日 ・ 中小DXラボ ・ 内容は執筆時点(2026年10月)の公式ドキュメントなどの出典にもとづきます(各節の末尾に出典を記載)

まず違いをひとことで:文脈か、強制か

Claude Code(Anthropic 社が提供する、ターミナルで動く AI コーディングエージェント)には、指示を書く CLAUDE.md と、設定を書く settings.json があります。どちらも挙動に関わるため、社内で配る前に何をどちらに書くかを整理します。

公式ドキュメントによると、CLAUDE.md は Claude に永続的な指示を与えるマークダウンのファイルです。プレーンテキストで書き、Claude がセッションの開始時に読み込みます。Claude はこれを文脈として扱い、強制される設定としては扱いません。指示が具体的で簡潔なほど、Claude は安定して従うとされています。

Claude の判断にかかわらず特定の操作をブロックしたい場合は、CLAUDE.md ではなく PreToolUse hook を使う、とも書かれています。守ってほしいお願いは CLAUDE.md、止めたい操作は強制の仕組み、という切り分けです。

出典: How Claude remembers your project

CLAUDE.md の置き場所と書く内容

公式ドキュメントでは、CLAUDE.md を「毎回説明し直すことを書き留める場所」としています。入れるのは、ビルドコマンド、規約、プロジェクトの構成、「常に〜する」というルールなど、毎セッション持たせておきたい事実です。複数手順の作業や、コードベースの一部にしか関係しない内容は、スキルやパス指定のルールに移すよう案内されています。

置き場所は4種類

• 組織の管理ポリシー:OS ごとに決まった場所に置く、組織全体向けの指示です。IT や DevOps が管理し、組織の全利用者に共有されます。場所は公式ドキュメントで確認してください。
• ユーザーの指示:~/.claude/CLAUDE.md。自分だけの、全プロジェクト共通の好みを書きます。
• プロジェクトの指示:./CLAUDE.md または ./.claude/CLAUDE.md。ソース管理を通じてチームに共有されるため、個人の好みではなくプロジェクトの標準を書きます。
• ローカルの指示:./CLAUDE.local.md。このプロジェクトだけの個人の好みで、.gitignore に追加します。

上の順は読み込み順で、範囲の広いものから並びます。プロジェクトの指示はユーザーの指示より後に文脈へ入ります。作業ディレクトリより上の階層のファイルは起動時に、サブディレクトリのファイルは必要になったときに読み込まれます。

書き方の注意

公式ドキュメントは、確認できるくらい具体的に書くことを勧めています。たとえば「コードを適切に整形する」ではなく「インデントは 2 スペース」、「変更をテストする」ではなく「コミット前に npm test を実行する」です。目安は 1 ファイル 200 行未満で、長いと文脈を多く使い、従う度合いが下がります。指示同士が矛盾すると Claude がどちらかを任意に選ぶことがあるため、古い指示や矛盾は定期的に見直します。

出典: How Claude remembers your project

settings.json の置き場所と優先順位

公式ドキュメントによると、settings は Claude Code のふるまいを変える JSON のキーです。起動時のモデル、確認なしで実行できる操作、読めないファイル、組織が強制する内容などを扱います。どのファイルに書くかで、設定が効く範囲が決まります。

• ユーザー(~/.claude/settings.json):自分の全プロジェクトに効きます。テーマ、既定のモデル、自分用の許可ルールなどの個人の好みに使います。
• 共有プロジェクト(.claude/settings.json):そのフォルダで働く全員に効きます。git のリポジトリならコミットして配ります。チームの権限、hooks、プラグイン、プロジェクトに必要な環境変数に使います。
• プロジェクトローカル(.claude/settings.local.json):自分のこのプロジェクトだけに効きます。手で作った場合は自分で .gitignore に追加します。
• 管理設定:組織が配布します。セキュリティポリシーや法令順守の要件に使います。

同じキーが複数のファイルにあると、高いレベルの値が使われます。優先度は、管理設定、コマンドライン、プロジェクトローカル、共有プロジェクト、ユーザーの順です。permissions.allow のようなリストは上書きされず結合されます。モデル関連の一部のキーには別の規則があるため、公式ドキュメントで確認してください。

設定ファイルは厳密な JSON で、// のコメントや末尾のカンマは構文エラーになります。保存後は /status を実行して、読み込まれたファイルを確認します。permissions や hooks の編集は、再起動なしで実行中のセッションに反映されます。

公式ドキュメントの設定例では、permissions の allow に Bash(npm run lint) と Bash(npm run test *) を、deny に Read(./.env) と Read(./.env.*) を書いています。.env を読ませない設定は、CLAUDE.md の文章ではなく deny のルールで書かれています。

出典: Settings files and precedence

何をどちらに書くか:使い分けの目安

公式ドキュメントには、管理設定と管理 CLAUDE.md の使い分けの表があります。技術的な強制は設定、ふるまいの案内は CLAUDE.md という整理です。

• 特定のツール、コマンド、ファイルパスのブロック:permissions.deny(管理設定)
• サンドボックスの分離の強制:sandbox.enabled(管理設定)
• 環境変数と API プロバイダーの経路:env(管理設定)
• ログイン方法と組織の制限:forceLoginMethod、forceLoginOrgUUID(管理設定)
• コードスタイルと品質の指針、データの扱いやコンプライアンスの注意書き、Claude への行動指示:管理 CLAUDE.md

なお、settings には CLAUDE.md の読み込みを調整するキーもあります。claudeMdExcludes は、大きなモノレポで他チームの CLAUDE.md が拾われるときに、特定のファイルを除外します。自分のマシンだけに効かせる場合は .claude/settings.local.json に書きます。

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

管理ポリシーの CLAUDE.md は除外できません。組織全体の指示が個人の設定にかかわらず適用されるようにするためです。

出典: How Claude remembers your project

社内で配るときの注意

チームに配るなら、.claude/settings.json をコミットします。各自が自分用に上書きしたい場合は、コミット不要の .claude/settings.local.json に書けます。

コミットした設定には、各メンバーがフォルダを信頼するまで効かないものがあります。公式ドキュメントによると、permissions.allow のルール、permissions.additionalDirectories、extraKnownMarketplaces、ほとんどの env の値が対象で、deny と ask のルールはすぐ適用されます。また、リポジトリのファイルからは効かないキーもあります。

組織が管理設定を配っている場合、自分のファイルや --settings では管理されたキーを上書きできません。どの管理ソースが効いているかは /status で確認します。

執筆時点(2026年10月)の公式ドキュメントに基づく内容です。キー名や挙動は更新されることがあるため、配布前に公式ドキュメントで確認してください。

出典: Settings files and precedence

参考(執筆時点)

• How Claude remembers your project(公式ドキュメント)
• Settings files and precedence(公式ドキュメント)

この記事は、上の出典の内容を中小DXラボが要約・再構成したものです。仕様は変わることがあります。社内で使う・配る前に、公式ドキュメントで最新の情報を確認してください。