Claude Codeを触り始めると、いつの間にかホームディレクトリやプロジェクトに 見慣れないファイルが増えていくのに気づきますよね

CLAUDE.md settings.json AGENT.md SKILL.md .mcp.json ……名前は見たことがあるけど、「どれを触ると何が変わるのか」が把握しきれていない、という方は多いんじゃないでしょうか

この記事では、Claude Codeを使うときに登場する 主要な設定ファイル(.md含む)を一覧化して、保存場所と役割をまとめます

「Claudeが勝手に作るけど、いざ触る場面で慌てたくない」「自分用に微調整したい」という人が、早見表的に開いて参照できるような構成にしました

拡張機構の全体像についてはClaude Codeの拡張機構入門(基礎編)、用語の整理はClaudeを始める前に知っておきたい用語集で扱っているので、ベースから入りたい方はそちらと合わせてどうぞ

まず知っておきたい全体像と継承ルール

細かいファイル一覧に入る前に、大枠の地図を頭に入れておきましょう

Claude Codeの設定は、大きく 2つの軸で整理できます

1. 場所の軸:ユーザー全体(~/.claude/)とプロジェクト個別(<project>/.claude/)
2. 役割の軸:指示(Markdown)と挙動制御(JSON)と拡張機構(Markdown+YAML)

※ ~/ はホームディレクトリの省略表記で、Windowsなら C:\Users\<ユーザー名>\、Mac/Linuxなら /Users/<ユーザー名>/ や /home/<ユーザー名>/ に読み替えてください

つまり同じ settings.json でも 「どこに置くか」で適用範囲が変わるし、同じ「Markdownの指示書」でも CLAUDE.md と SKILL.md と AGENT.md で読まれ方が違うわけです

設定ファイルの階層イメージ

典型的な配置を図にするとこんな感じになります

~/.claude/                          ← ユーザー全体(全プロジェクト共通)
├── CLAUDE.md                       全体共通の指示
├── settings.json                   全体共通の挙動制御
├── skills/<name>/SKILL.md          個人スキル
└── projects/<project>/memory/
    ├── MEMORY.md                   メモリー目次
    └── <topic>.md                  個別メモリー

<project>/                          ← プロジェクト個別
├── CLAUDE.md                       プロジェクト指示
├── CLAUDE.local.md                 ローカル専用指示(gitignore)
├── README.md                       一般ドキュメント(間接参照)
├── .env                            認証情報(gitignore)
├── .gitignore                      バージョン管理除外
├── .mcp.json                       MCPサーバー登録
└── .claude/
    ├── settings.json               プロジェクト共有設定
    ├── settings.local.json         ローカル専用設定(gitignore)
    ├── rules/<name>.md             特定パス限定指示
    ├── skills/<name>/SKILL.md      プロジェクト固有スキル
    ├── agents/<name>/AGENT.md      サブエージェント定義
    └── hooks/<script>              Hookスクリプト本体

このツリーが頭に入っていると、「あ、これはユーザー全体に効くやつだな」「これはプロジェクト固有か」がすぐ判断できるようになります

継承ルールの基本

同じ役割のファイルが複数の階層に置かれているとき、どれが優先されるかは役割ごとにルールがあります

ここでとくに重要なのが、CLAUDE.md は上書きではなく『連結』されるという点です

ユーザー全体の CLAUDE.md と、プロジェクトの CLAUDE.md と、サブディレクトリの CLAUDE.md があったら、全部まとめて1つの巨大な指示書としてClaudeに渡されるイメージです

なので「上書きされるはずだから雑に書いておけばいい」みたいな運用は通用しません、書いたものは全部効いてくるので注意しましょう

プロジェクト指示・コンテキスト系

ここからカテゴリ別に 主要な設定ファイルを見ていきます、まずは Claudeに「こういう方針で動いて」と伝える系のファイルです

このカテゴリは触る頻度が一番高いので、優先的に押さえておきたいところになります

CLAUDE.md(グローバル)|全プロジェクト共通の指示書

• 場所:~/.claude/CLAUDE.md
• 形式:Markdown
• 触る頻度:高め(自分の好みが固まってきたら追記)

個人として「どのプロジェクトでも同じように動いてほしい」内容を書く場所です

たとえば「日本語で返答してね」「コミットメッセージは英語のconventional commitsで」「pythonは仮想環境を有効化してから実行して」みたいな、自分のスタンダードを宣言するイメージになります

注意点として、ここに書いた内容はすべてのプロジェクトのコンテキストに毎回入るので、肥大化するとトークン消費が増えます、本当に共通の事項だけにとどめるのが運用のコツです

CLAUDE.md(プロジェクト)|プロジェクトごとの指示書

• 場所:<project>/CLAUDE.md
• 形式:Markdown
• 触る頻度:高め(プロジェクトの方針を整理するたびに追記)

プロジェクトごとに違う情報を書く場所で、設定ファイルの中で一番触る機会が多いのがここになります

使っているフレームワーク・ディレクトリ構成のクセ・命名規則・テストの走らせ方・このプロジェクト特有の禁止事項など、「新人が入ってきたら最初に渡したい資料」に近いものを書くイメージです

複数階層に置けるのもポイントで、ルートに置いた CLAUDE.md に加えて、サブディレクトリ(たとえば backend/ や frontend/)にも個別の CLAUDE.md を置けば、その配下にいるときだけ追加で読まれます

大規模プロジェクトで役割ごとに指示を分割したい場合に効いてくる仕組みです

CLAUDE.local.md|gitignore対象のローカル指示

• 場所:<project>/CLAUDE.local.md
• 形式:Markdown
• 触る頻度:中(自分用メモを置きたいとき)

名前のとおり自分のローカル環境専用の指示書です、Gitで共有したくない個人メモを書く場所になります

たとえば「自分の検証用APIキーはここに置いてある」「個人的にこのプロジェクトで試している実験設定はこれ」みたいな、チームに共有する必要がない情報を書きます

このファイルは継承順で最後に追記される=実質一番優先される仕組みになっているので、プロジェクトのデフォルト動作を自分だけ一時的に変えたいときにも便利です

ただし忘れずに .gitignore に CLAUDE.local.md を入れておかないと、うっかりコミットしてしまうことがあるので注意しましょう

rules/ ディレクトリ|特定パスに限定した指示

• 場所:<project>/.claude/rules/<name>.md
• 形式:Markdown + YAML frontmatter
• 触る頻度:低〜中(細かい運用が固まってきたら作る)

CLAUDE.md が「全体方針」なら、こちらは 『この種類のファイルを触るときだけのルール』を書く場所です

frontmatterで paths を指定して、たとえば **/*.test.ts にマッチするファイルを開いているときだけ「テストはVitestで」「モックは最小限に」みたいなルールを発動させられます

---
paths:
  - "**/*.test.ts"
  - "**/*.spec.ts"
---

このプロジェクトのテストは Vitest を使う

- describe / it ではなく test() の単独形式
- モックは vi.mock() で最小限に
- スナップショットテストは原則使わない

CLAUDE.md がどんどん肥大化してきたら、役割ごとに rules/ へ分割していくのが整理のコツになります

README.md|間接的に参照される一般ドキュメント

• 場所:<project>/README.md
• 形式:Markdown
• 触る頻度:低(リポジトリの説明用)

これはClaude専用ファイルではないですが、Claudeはプロジェクトを開いたとき初回探索で README.md を読みに行く傾向があるので、ここにプロジェクト概要・セットアップ手順・ディレクトリ構成などを書いておくと初手の理解が早くなります

「Claude専用に書く」のではなく 『普通のドキュメントを充実させると、結果としてClaudeも賢く動く』という考え方が分かりやすいかもしれません

全体設定・挙動制御系

続いて、Claude Codeの 挙動そのものを制御する設定ファイル群です、ここはMarkdownではなくJSONで書く世界になります

settings.json の3階層

settings.json は3つの階層に置けて、それぞれ役割が違います

この3つは マージされる仕組みで、優先順位は Managed > CLI flag > Local > Project > User の順になっています(Managedは企業デプロイ向けで、個人運用ではあまり意識しなくてOK)

つまり同じキーがあれば Local が Project を、Project が User を上書きする形になります

settings.json の主要フィールド

知っておくと役立つフィールドをピックアップして整理しました

とくに permissions は セキュリティの要になる部分で、ここで deny リストを整えるかどうかで安心感がガラッと変わります

具体的な書き方はClaude Code Desktop初心者向けセキュリティの記事で詳しく扱っているので、合わせて読むと理解が深まります

最小サンプル|settings.json の中身

とりあえず書き始めるなら、こんな感じの構造から入るのが分かりやすいです

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)"
    ],
    "ask": [
      "Edit",
      "Write"
    ]
  },
  "env": {
    "PYTHONIOENCODING": "utf-8"
  },
  "autoMemoryEnabled": true,
  "model": "claude-sonnet"
}

このファイルは 慣れるまでコピペで始めるのが現実的、Claude公式ドキュメントや既存サンプルを土台にして、自分のプロジェクトに合わせて少しずつ削ったり足したりするのが良い感触です

hooks フィールド|自動処理の宣言場所

settings.json 内の hooks フィールドは、イベント駆動の自動処理を宣言する場所です

「ツールを使う前にこのスクリプトを走らせて」「セッション開始時にこれを実行して」みたいな指定をJSONで書きます、スクリプト本体は別ファイル(.claude/hooks/<name>)に置くのが一般的です

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/check-dangerous.sh"
          }
        ]
      }
    ]
  }
}

主なイベントは SessionStart UserPromptSubmit PreToolUse PostToolUse Stop あたりで、機械的に確実に走らせたい処理がある場合に使います

初心者向けには優先度低めで、Claude Codeに慣れて「定型処理を自動化したい」と感じたタイミングで触り始めれば十分だと思います

拡張機構系|サブエージェントとスキル

Claude Codeを 自分用に拡張する仕組みで使われるファイル群です、ここからは中級者向けの色が濃くなってきます

AGENT.md|サブエージェントの定義ファイル

• 場所:<project>/.claude/agents/<name>/AGENT.md
• 形式:Markdown + YAML frontmatter
• 触る頻度:中(サブエージェントを使う運用なら必須)

サブエージェント(Subagent)を1個1個「こういう仕事をする専門係」として定義するファイルです

frontmatterで name description tools model などを指定し、本文にはそのエージェントが守るべき行動指針を自然言語で書きます

たとえば「コードレビュー専用エージェント」「リサーチ専用エージェント」みたいに役割を分けて、メインのClaudeセッションから委譲できる仕組みです

frontmatterの主要フィールドは次のような構成です

サブエージェントを使うと メインのコンテキストを汚さずに重いタスクを処理できるので、大規模プロジェクトで効いてきます

SKILL.md|スキル定義ファイル

• 場所(個人):~/.claude/skills/<name>/SKILL.md
• 場所(プロジェクト):<project>/.claude/skills/<name>/SKILL.md
• 形式:Markdown + YAML frontmatter
• 触る頻度:中(よく使う作業をテンプレ化したくなったら作る)

スキル(Skill)は「よく使う指示パターンをまとめてClaudeに覚えさせる」仕組みで、その本体ファイルが SKILL.md になります

frontmatterで name description when_to_use allow-tools user-invocable などを指定して、本文にスキルが実行すべき手順や注意事項を書きます

呼び出し方法は3パターンあって、以下のように整理できます

個人スキルはホームディレクトリ、プロジェクト固有スキルはプロジェクト内に置けるので、『どこに置くか』で誰と共有するかを分けられます

commands/ ディレクトリ|レガシー扱いの旧コマンド機構

• 場所:<project>/.claude/commands/<name>.md
• 状態:Skills(SKILL.md)に統合され、新規利用は非推奨

以前はカスタムスラッシュコマンドを commands/<name>.md として置く方式がありましたが、2026年5月現在は Skills(SKILL.md)に統合されています

過去の記事やGitHubのサンプルで commands/ 配下の .md を見かけることがありますが、新規に作るならSKILL.md側で書くのがおすすめです

SKILL.mdの user-invocable: true を指定すれば、これまで通り /コマンド名 でユーザー側から呼び出せる挙動が再現できます

連携・運用系|外部接続とメモリー

続いて、Claude Codeの外側とつなげるための設定ファイルや、長期的な情報を覚えておくためのファイル群です

.mcp.json|MCPサーバーの登録

• 場所(プロジェクト):<project>/.mcp.json
• 場所(ユーザー):~/.claude.json の mcpServers フィールド
• 形式:JSON
• 触る頻度:中(MCPサーバーを追加するたびに編集)

MCP(Model Context Protocol)サーバーの接続情報を書く場所です

「WordPressに投稿するMCPサーバー」「データベース操作のMCPサーバー」みたいな外部連携を増やすたびに、ここに登録していくイメージになります

{
  "mcpServers": {
    "wordpress": {
      "command": "python",
      "args": ["./wp_mcp_server.py"],
      "env": {
        "WP_BASE_URL": "https://example.com"
      }
    }
  }
}

ポイントは user scope と project scope の2階層に置けること、共通で使うMCPはユーザー側、プロジェクト固有のMCPはプロジェクト側、と振り分けると整理しやすいです

.env|認証情報・APIキー

• 場所:<project>/.env
• 形式:KEY=VALUE のテキスト
• 触る頻度:中(認証情報を追加するたびに編集)

Claude専用というわけではないものの、Claude Codeで外部APIや独自MCPサーバーを使うとき、認証情報の置き場として頻出します

パスワード・APIキー・アクセストークンなど 原則Gitには上げない情報をここに集約しておきましょう

WP_BASE_URL=https://example.com
WP_USERNAME=admin
WP_APP_PASSWORD=xxxx xxxx xxxx xxxx

.gitignore に .env を入れておくのは運用上の鉄則になります、忘れるとGitHubに認証情報が漏れる事故につながります

MEMORY.md / 個別 memory|プロジェクト固有の長期記憶

• 場所:~/.claude/projects/<project>/memory/MEMORY.md と <topic>.md
• 形式:Markdown
• 触る頻度:中(自動で書き換わる、手動編集は最小限)

Claude Codeの自動メモリー機能が、会話の中で得た情報をプロジェクト固有の知識として書き出していくファイル群です

MEMORY.md が目次で、トピック別の個別ファイル(user_profile.md project_context.md など)が実体として並ぶ構造になっています

基本的にClaudeが自分で書き換える領域なので、頻繁に手で編集する場所ではないですが、「ここに書かれた情報を見直したい」とか「明らかに古い情報が残っている」みたいなときに開いて整えるのは有効です

settings.json の autoMemoryEnabled でメモリー機能の有効/無効を切り替えられるので、邪魔ならOFFにする選択肢もあります

.gitignore|バージョン管理から外したいファイル

• 場所:<project>/.gitignore
• 形式:テキスト(パターン1行ずつ)
• 触る頻度:中(新しい設定ファイルを増やすたびに点検)

Claude専用ではなくGit本来のファイルですけど、Claude Code関連のファイルを増やすたびに点検すべき場所として外せません

Claude Code関連で .gitignore に入れておきたい代表的なパターンはこんな感じです

# Claude Code ローカル専用ファイル
.env
CLAUDE.local.md
.claude/settings.local.json

# 必要に応じて
.claude/cache/
*.log

逆にチームで共有したい設定(.claude/settings.json .claude/agents/ .claude/skills/ .mcp.json など)は .gitignoreに入れないのが原則になります、ここをきれいに分けておけば運用がぐっと安定します

プラグイン系|こういうのもあるよ

最後に、ちょっと発展形としてプラグイン系のファイルも紹介しておきます、こちらは 中級〜上級者向けの領域なので、初心者の方は「こういうのもあるんだな」程度で大丈夫です

plugin.json|プラグインのマニフェスト

• 場所:<plugin-root>/.claude-plugin/plugin.json
• 形式:JSON
• 触る頻度:低(プラグインを自作するなら必須)

Claude Codeのプラグインを1つのパッケージとして配布するときに、そのマニフェスト情報を書くファイルです

プラグイン名・バージョン・作者・含まれているスキルやエージェントの一覧などを記述します

プラグイン同梱のskills / agents / hooks

• 場所:<plugin-root>/skills/ agents/ hooks/ 配下
• 形式:Markdown / JSON
• 触る頻度:低(プラグイン開発者向け)

プラグインに同梱される拡張機能の本体ファイル群です、プラグインをインストールすると、ここのファイルがあたかも自分が書いたかのようにClaude Codeから読み込まれる仕組みになっています

Hooksをまとめた hooks/hooks.json もこの中に置かれることがあって、ユーザー側の settings.json を汚さずに自動処理を配布できる利点があります

まとめ|どこから手を付けるか

ここまでで主要な設定ファイルを一通り見てきましたが、『結局どこから触ればいいの?』という疑問が残るかもしれません

個人的にはClaude Codeを始めた人の流れとして、以下の順番で触っていくのが 無理なく押さえやすいと思っています

1. CLAUDE.md(プロジェクト):何はなくともプロジェクトの方針をここに書く、最も触る頻度が高い
2. settings.json + .gitignore + .env:権限と認証情報を整える、セキュリティの土台になる
3. CLAUDE.md(グローバル):全プロジェクトで共通の好みが固まってきたら追加
4. SKILL.md:同じ指示を何度も書いていることに気づいたらテンプレ化、Markdown1ファイルで始められる
5. .mcp.json:外部サービスと連携したくなったら登録、公式コネクタから始めるのが現実的
6. AGENT.md:重いタスクが増えてきて、メインコンテキストを汚したくなくなったら導入
7. rules/ + hooks:プロジェクト固有の運用が固まってきた段階で整理、運用熟練者向け

大切なのは『全部を一気に触ろうとしない』こと、Claude Codeはハーネス層が広いので、いきなり全カテゴリを整えようとすると確実に挫折します

困りごとが出てきたら、その時点で関連ファイルを1つだけ触る、ぐらいのペースが結果的に長続きすると思います

早見表|主要ファイル一覧

最後にもう一度、この記事で扱った主要ファイルを1枚の早見表として整理しておきます、ブックマークしてリファレンス的に使ってもらえると嬉しいです

各ファイルの細かい使い方はClaude Codeの拡張機構入門(基礎編)やClaudeの使い方を初心者向けに解説した記事でも触れているので、深掘りしたい部分があれば合わせて読んでみてください

Claude Codeはまだまだ進化中で、設定ファイルの種類や役割も少しずつ変わっていく可能性があります、この早見表も折を見て追記していく予定なので、また覗きに来てもらえると嬉しいです