Claude Code の .claude ディレクトリ構成と各ファイルの役割

Claude Code エンジニアリング 6分で読めます

Claude Code は、指示・設定・スキル・サブエージェント・メモリをプロジェクトのディレクトリとホームディレクトリの ~/.claude から読み込みます。本記事は公式ドキュメント「Explore the .claude directory」と「Settings files and precedence」に基づき、どのファイルを何のために置くのか、git にコミットするものとしないもの、~/.claude に自動で溜まるデータとその消し方を日本語で整理します。

公式によれば、ほとんどのユーザーが編集するのは CLAUDE.md と settings.json だけです。それ以外は必要になったときに足していけば十分です。

.claude ディレクトリの全体像

Claude Code の設定ファイルは、置き場所によって誰に効くかが変わります。

Windows では ~/.claude は %USERPROFILE%\.claude を指します。環境変数 CLAUDE_CONFIG_DIR を設定すると、~/.claude 配下のパスはすべてそのディレクトリに移ります。通常は ~/.claude.json にある .claude.json も同様です。

リポジトリにほかのコーディングエージェント向けの AGENTS.md がすでにある場合、Claude Code は CLAUDE.md の代わりにそれを読み込めます。

エクスプローラーの外にあるファイル

公式ページのツリー表示は自分で書いて編集するファイルが対象です。関連するファイルのうち、次のものは別の場所にあります。

ファイル場所用途
managed-settings.jsonシステムレベル(OS ごとに異なる)組織が強制する設定。自分の設定ファイルや --settings では上書きできない(一部例外あり)
CLAUDE.local.mdプロジェクト直下そのプロジェクトでの個人的な好み。CLAUDE.md と一緒に読み込まれる。手動で作り、.gitignore に追加する
AGENTS.mdプロジェクト直下・.claude/・任意のディレクトリAI コーディングエージェント向けの指示。CLAUDE.md の代わりに読み込める
インストール済みプラグイン~/.claude/pluginsclone したマーケットプレイス、プラグインの各バージョン、installed_plugins.json など。claude plugin コマンドが管理する

目的別にファイルを選ぶ

やりたいことからファイルを引くための対応表です。「プロジェクト/グローバル」はどちらにも置けることを表します。

やりたいこと編集するファイルスコープ
プロジェクトの前提や規約を伝えるCLAUDE.mdプロジェクト/グローバル
特定のツール呼び出しを許可・禁止するsettings.json の permissions または hooksプロジェクト/グローバル
ツール呼び出しの前後にスクリプトを動かすsettings.json の hooksプロジェクト/グローバル
セッションの環境変数を設定するsettings.json の envプロジェクト/グローバル
個人的な上書きを git に入れないsettings.local.jsonプロジェクトのみ
/name で呼び出すプロンプトや機能を足すskills/<name>/SKILL.mdプロジェクト/グローバル
専用のツールを持つサブエージェントを定義するagents/*.mdプロジェクト/グローバル
スクリプトから多数のサブエージェントを動かすworkflows/*.jsプロジェクト/グローバル
MCP で外部ツールをつなぐ.mcp.jsonプロジェクトのみ
応答の書き方を変えるoutput-styles/*.mdプロジェクト/グローバル

設定ファイルの優先順位

同じキーが複数の場所にあるときは、上位のものが使われます。「Settings files and precedence」が示す順番は、上から次のとおりです。

  1. 管理設定(managed settings): 組織が配布する設定。自分のファイルや --settings では上書きできない
  2. コマンドライン: 起動時に --settings で渡した JSON(そのセッションだけ)
  3. プロジェクトのローカル設定: .claude/settings.local.json
  4. 共有プロジェクト設定: .claude/settings.json
  5. ユーザー設定: ~/.claude/settings.json

ただし permissions.allow のようなリストは上書きではなく各ファイルの内容が結合されます。環境変数はこの階層には入らず、キーごとにどちらが優先されるかが決まっています。どのファイルが読み込まれたかは /status の Setting sources 行で確認できます。設定が効かないときの調べ方は 設定が効かないときの確認方法も参照してください。

.claude/settings.local.json は、Claude Code が git リポジトリ内で初めて書き込むときに、グローバルな git の除外ファイルへ **/.claude/settings.local.json を追加します。自分で手作りした場合は自動では除外されないので、.gitignore に追加します。

ファイル一覧と frontmatter

公式のファイルリファレンスにある各ファイルを、コミットするかどうかとあわせてまとめます。

ファイルスコープコミット役割
CLAUDE.mdプロジェクト/グローバルする毎セッション読み込まれる指示
rules/*.mdプロジェクト/グローバルするトピック別の指示。パスで適用範囲を絞れる
settings.jsonプロジェクト/グローバルする権限・フック・環境変数・モデルの既定値
settings.local.jsonプロジェクトのみしない個人的な上書き
.mcp.jsonプロジェクトのみするチームで共有する MCP サーバー
.worktreeincludeプロジェクトのみする新しい worktree にコピーする gitignore 済みファイル
skills/<name>/SKILL.mdプロジェクト/グローバルする/name で呼ぶか自動で呼ばれる再利用プロンプト
commands/*.mdプロジェクト/グローバルする1ファイルのプロンプト。仕組みはスキルと同じ
output-styles/*.mdプロジェクト/グローバルするClaude の動き方を調整する指示セット
agents/*.mdプロジェクト/グローバルする独自のプロンプトとツールを持つサブエージェント定義
workflows/*.jsプロジェクト/グローバルする/workflows から保存する動的ワークフロー。各ファイルが /<name> コマンドになる
agent-memory/<name>/プロジェクト/グローバルするサブエージェントの永続メモリ
~/.claude.jsonグローバルのみ-アプリの状態、アカウント情報、UI の切り替え、個人の MCP サーバー
projects/<project>/memory/グローバルのみ-自動メモリ(Claude がセッションをまたいで残すメモ)
keybindings.jsonグローバルのみ-キーボードショートカットのカスタマイズ
themes/*.jsonグローバルのみ-独自のカラーテーマ

~/.claude.json がない場合は、セッションの開始時や claude auth status などのサブコマンド実行時に自動で作られます(--version と --help では作られません)。なお、これらのファイルの内容は、組織の管理設定、--permission-mode や --settings などの CLI フラグ、一部の環境変数によって上書きされることがあります。

ファイルごとの frontmatter

スキル・コマンド・サブエージェント・出力スタイル・ルールは、先頭の YAML frontmatter で設定を読みます。使えるフィールドはファイルの種類ごとに異なります。

プラグインに同梱されたエージェントは、サブエージェントのフィールドの一部だけに対応します。各ファイルの書き方は はじめてのスキル作成や サブエージェントの使い方で解説しています。

~/.claude に溜まるアプリケーションデータ

自分で書く設定とは別に、~/.claude には Claude Code が作業中に書き込むデータも置かれます。トランスクリプト、プロンプト履歴、ファイルのスナップショット、キャッシュ、ログなどです。

重要なのは、これらが平文で保存される点です。ツールを通ったもの(ファイルの内容、コマンドの出力、貼り付けたテキスト)はトランスクリプトに書かれ、システムプロンプト、ツール定義、リクエストのパラメータ、読み込んだ CLAUDE.md などの指示ファイルも含まれることがあります。

自動で削除されるもの

次のパスのファイルは、cleanupPeriodDays より古くなると削除されます。既定は30日、最小は1で、0 を設定すると検証エラーになります。

backups/ には書き換え前の ~/.claude.json が保存され、新しい5つと読み込めなかった版のコピーが残ります。

別のルールで扱われるもの

claude -p を --bare 付きで実行したセッションでは、この自動削除は走りません。

機密情報を残しにくくする

トランスクリプトや履歴は保存時に暗号化されず、OS のファイル権限だけが保護です。.env を読んだりコマンドが認証情報を表示したりすると、その値はトランスクリプトに書かれます。公式は次の対策を挙げています。

ローカルデータの整理と claude purge

あるプロジェクトについて Claude Code が持っている状態をまとめて消すには、claude purge を使います(v2.1.288 より前は claude project purge)。削除されるのは次のものです。

実行すると削除計画を表示し、確認してから消します。まずは --dry-run で何が消えるかを確かめるのが安全です。

# 削除せずに計画だけ表示する
claude purge ~/work/my-repo --dry-run

# 確認プロンプトを1回出してから削除する
claude purge ~/work/my-repo

# スクリプト用に確認を省く
claude purge ~/work/my-repo --yes

~/work/my-repo は公式の例のパスなので、自分のプロジェクトのパスに置き換えます。パスを省くと対話的な一覧からプロジェクトを選べます。--all を付けるとすべてのプロジェクトが対象になり、history.jsonl は絞り込みではなく丸ごと削除されます。-i を付けると削除計画を1件ずつ確認できます。

shell-snapshots/ と backups/ はプロジェクト単位ではないため claude purge では消えず、計画の出力で注意が表示されます。貼り付けた画像やセッションのスクラッチパッドは ~/.claude ではなく一時ディレクトリにあるので、これも対象外です。

手で消すときの注意

アプリケーションデータは手で削除しても構いませんが、失うものを把握しておきます。

一方で、~/.claude.json・~/.claude/settings.json・~/.claude/plugins/ は削除しないよう公式は明記しています。アカウント情報、設定、インストール済みプラグインが入っているためです。ログイン情報の .credentials.json、サブエージェントのメモリ agent-memory/、バックグラウンドセッションの状態 jobs/・daemon/ も残しておくべき状態ファイルとして挙げられています。

関連記事: CLAUDE.md でプロジェクトを覚えさせる / Claude Code の設定と権限

本記事は Anthropic 公式ドキュメント「Explore the .claude directory」と「Settings files and precedence」に基づく非公式の日本語解説です(確認日 2026-11-12)。仕様は更新される場合があるため、利用前に公式ドキュメントをご確認ください。