ai-tools-kbMarkdown が正

facts ／Claude Code ／memory

stable4 日前 · 2026-08-09

How Claude remembers your project

概要

セッションをまたいで知識を持ち越す 2 つの仕組み。ユーザーが書く CLAUDE.md files と、Claude が自分で書く auto memory。どちらも毎回の会話開始時に読み込まれる。

仕様

CLAUDE.md と auto memory の比較

CLAUDE.md filesAuto memory
書く主体ユーザーClaude
内容指示とルール学習内容とパターン
スコープproject / user / orgリポジトリ単位、worktree 間で共有
読み込み毎セッション毎セッション（先頭 200 行または 25KB）
用途コーディング標準、ワークフロー、プロジェクト構造ビルドコマンド、デバッグの知見、Claude が発見した好み
  • どちらも context であり、強制される設定ではない。Claude の判断に関わらず動作をブロックするには PreToolUse hook を使う

CLAUDE.md の配置場所

読み込み順（広いスコープから具体的なものへ）:

スコープ場所共有範囲
Managed policymacOS: /Library/Application Support/ClaudeCode/CLAUDE.md
Linux / WSL: /etc/claude-code/CLAUDE.md
Windows: C:\Program Files\ClaudeCode\CLAUDE.md		組織の全ユーザー
User instructions~/.claude/CLAUDE.md自分のみ（全プロジェクト）
Project instructions./CLAUDE.md または ./.claude/CLAUDE.mdソース管理経由でチーム
Local instructions./CLAUDE.local.md（.gitignore に追加する）自分のみ（現在のプロジェクト）
  • /init で初期の CLAUDE.md を自動生成できる。既に CLAUDE.md がある場合は上書きせず改善案を提示する
  • CLAUDE_CODE_NEW_INIT=1 を設定すると対話的な多段フローになる。CLAUDE.md / skills / hooks のどれを用意するか尋ね、subagent でコードベースを調査し、追加質問で不足を埋め、ファイル書き込み前にレビュー可能な提案を提示する
  • 読み込まれたか確認するにはセッション内で /context を実行し Memory files の一覧を見る

読み込みの仕組み

  • 現在の作業ディレクトリからディレクトリツリーを上へ辿り、各ディレクトリの CLAUDE.md と CLAUDE.local.md を読む
  • 見つかったファイルは互いを上書きせず連結される。ファイルシステムのルートから作業ディレクトリへ向かう順で並ぶため、起動場所に近い指示ほど後に読まれる
  • 各ディレクトリ内では CLAUDE.local.md が CLAUDE.md の後に追加される
  • 作業ディレクトリより下のサブディレクトリの CLAUDE.md / CLAUDE.local.md は起動時ではなく、Claude がそのサブディレクトリのファイルを読んだときに含められる
  • ブロックレベルの HTML コメント（<!-- maintainer notes -->）はコンテキストへ注入する前に除去される。コードブロック内のコメントは保持される。Read ツールで直接開いた場合はコメントも見える

追加ディレクトリからの読み込み

  • --add-dir で追加したディレクトリの CLAUDE.md は既定では読み込まれない
  • CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 を設定すると、追加ディレクトリの CLAUDE.md / .claude/CLAUDE.md / .claude/rules/*.md / CLAUDE.local.md を読み込む
  • --setting-sources から local を除外している場合 CLAUDE.local.md はスキップされる

import

  • @path/to/import 構文で他のファイルを取り込める。取り込まれたファイルは起動時に展開されコンテキストに入る
  • 相対パス・絶対パスの両方が使える。相対パスは import を含むファイルからの相対で、作業ディレクトリ基準ではない
  • 再帰的な import が可能で、最大 4 ホップ
  • import の解析は Markdown のコードスパンとフェンス付きコードブロックをスキップする。バッククォートで囲めば取り込まれない
  • プロジェクトレベルの memory ファイル内の import で、パスが作業ディレクトリの外に解決されるものは external として扱う。初回はファイル一覧を示す承認ダイアログが出る。拒否すると import は無効のままになり、以後ダイアログは出ない
  • user スコープの memory ファイル（~/.claude/CLAUDE.md、~/.claude/rules/）内の import はダイアログなしで読み込まれる

AGENTS.md

  • Claude Code は CLAUDE.md を読み、AGENTS.md は読まない
  • 既に AGENTS.md がある場合は、@AGENTS.md を import する CLAUDE.md を作る。import の下に Claude 固有の指示を追記できる
  • Claude 固有の内容が不要なら symlink でもよい（ln -s AGENTS.md CLAUDE.md）。Windows での symlink 作成には管理者権限か Developer Mode が必要なため、@AGENTS.md import を使う
  • /init は Cursor rules（.cursor/rules/ または .cursorrules）と Copilot rules（.github/copilot-instructions.md）を読み、関連部分を生成する CLAUDE.md に取り込む。CLAUDE_CODE_NEW_INIT=1 を設定すると AGENTS.md、.devin/rules/、.windsurf/rules/ または .windsurfrules、.clinerules も読む
  • /import は対応するコーディングエージェントの設定を Claude Code に取り込む。AGENTS.md などの指示ファイルの一度きりのコピーを対応する CLAUDE.md に追記し、MCP サーバー・コマンド・subagent・skill も引き継ぐ。v2.1.213 以降が必要

.claude/rules/

  • プロジェクトの .claude/rules/ に markdown ファイルを置いて指示を分割する。.md ファイルは再帰的に発見されるためサブディレクトリで整理できる
  • paths frontmatter を持たない rule は起動時に読み込まれ、優先度は .claude/CLAUDE.md と同じ
  • --setting-sources から project を除外すると project rules はスキップされる。v2.1.211 より前は、path-scoped rule やネストした .claude/rules/ の rule など on demand で読み込まれる rule は project を除外しても読み込まれていた

path-specific rules

  • YAML frontmatter の paths フィールドで対象ファイルを限定する。パターンに一致するファイルを Claude が読んだときにトリガーされる（毎回のツール使用ではない）
  • v2.1.198 以降、プロジェクトディレクトリへの symlink 経由でファイルに到達した場合もマッチする
パターンマッチ対象
**/*.ts任意のディレクトリの全 TypeScript ファイル
src/**/*src/ 配下の全ファイル
*.mdプロジェクトルートの Markdown ファイル
src/components/*.tsx特定ディレクトリの React コンポーネント
  • brace expansion が使える（src/**/*.{ts,tsx}）。各 brace グループは展開後のパターン数を掛け算する（src/*.{ts,tsx} は 2 パターン、{a,b}/{c,d}/*.{ts,tsx} は 8 パターン）
  • 1 つの rule の paths 全体で、展開後 1,000 パターンおよび 4 MiB の予算を共有する。brace を含まないパターンは予算に算入されない
  • 予算を超えるパターンは展開されずに使われ、リテラルの brace はどのファイルにもマッチしない。v2.1.217 より前は brace グループの多い paths が起動時に CLI を停止・クラッシュさせた
  • glob 構文では [ は bracket expression の開始として扱われる。photos [2024/** のように bracket expression として読めない [ を含むパターンは無効で、何にもマッチしない（同じ rule の他のパターンは動作する）。リテラルの [ は photos \[2024/** のようにエスケープする。v2.1.207 より前は、1 つの不正なパターンがその rule を評価する全ファイルで Read ツールを失敗させていた
  • .claude/rules/ は symlink をサポートする。symlink は解決されて通常どおり読み込まれ、循環 symlink は検出して適切に処理される
  • ~/.claude/rules/ の user-level rules は全プロジェクトに適用される。project rules より先に読み込まれるため、project rules の方が優先度が高い

組織向けの管理

  • managed policy の場所に CLAUDE.md を置くと、そのマシンの全ユーザーに適用され、個々の設定では除外できない
  • managed-settings.json の claudeMd キーで、別ファイルを配布せず managed CLAUDE.md の内容を直接書ける
    • スコープ: そのマシンの全 Claude Code セッション、全リポジトリ
    • 優先度: managed CLAUDE.md ファイルと同じ。user / project の CLAUDE.md より先に読み込まれる
    • 有効な場所: managed / policy 設定のみ。user / project / local 設定に書いても効果は無い
目的設定先
特定のツール・コマンド・ファイルパスをブロックManaged settings: permissions.deny
sandbox 分離の強制Managed settings: sandbox.enabled
環境変数と API プロバイダのルーティングManaged settings: env
認証方式と組織ロックManaged settings: forceLoginMethod, forceLoginOrgUUID
コードスタイル・品質のガイドラインManaged CLAUDE.md
データ取り扱い・コンプライアンスの注意Managed CLAUDE.md
Claude への行動指示Managed CLAUDE.md

claudeMdExcludes

  • 特定の CLAUDE.md をパスまたは glob パターンで読み込み対象から外す
  • パターンは絶対パスに対して glob 構文でマッチする
  • user / project / local / managed policy のどの settings 層でも設定でき、配列は層をまたいでマージされる
  • managed policy の CLAUDE.md は除外できない

Auto memory

  • 既定で有効。/memory の auto memory トグルで切り替えると autoMemoryEnabled が ~/.claude/settings.json に保存される。プロジェクト単位で切るにはそのプロジェクトの settings に設定する
  • 環境変数で無効化する場合は CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

保存場所

  • プロジェクトごとに ~/.claude/projects/<project>/memory/
  • <project> のパスは git リポジトリから導出されるため、同一リポジトリの全 worktree とサブディレクトリが 1 つの auto memory ディレクトリを共有する。git リポジトリ外ではプロジェクトルートが使われる
  • autoMemoryDirectory を settings.json に設定すると保存場所を変えられる。user / project / local / policy / --settings のどの settings スコープからも読まれる
  • 値は絶対パスか ~/ 始まりでなければならない。プロジェクトの .claude/settings.json / .claude/settings.local.json に設定した場合、そのフォルダの workspace trust ダイアログを承認した後にのみ有効になる（hooks と同じゲート）
  • ディレクトリは MEMORY.md エントリポイントと任意のトピックファイルを含む
  • auto memory はマシンローカル。マシン間やクラウド環境では共有されない

動作

  • MEMORY.md の先頭 200 行、または先頭 25KB のいずれか早い方が毎回の会話開始時に読み込まれる。それを超える内容はセッション開始時には読み込まれない
  • MEMORY.md への書き込み後、200 行 / 25KB の読み取り上限に対してファイルを計測する。上限に近い場合は短縮するよう Claude にリマインドし、上限を超えた場合は書き込み自体は成功するが、インデックスを書き直すようエラーを返す
  • 計測対象は読み込まれる内容のみ。YAML frontmatter とブロックレベルの HTML コメントはインデックス読み込み前に除去されるため上限に算入されない。v2.1.211 より前は生ファイルを計測していた
  • この上限は MEMORY.md にのみ適用される。CLAUDE.md は長さに関わらず全体が読み込まれる
  • debugging.md などのトピックファイルは起動時には読み込まれず、必要になったときに通常のファイルツールで読まれる
  • メイン会話の auto memory は subagent には読み込まれない。例外は fork で、親の会話とシステムプロンプトを継承する。subagent 自身の auto memory（subagent の memory フィールドで有効化）は別ディレクトリ
  • YAML frontmatter で始まる memory ファイルを書くとき、書き込み時刻を modified frontmatter フィールドに ISO 8601 タイムスタンプで記録する。frontmatter を持つファイルは次の書き込み時にこのフィールドが付く。frontmatter が無いファイルに frontmatter を追加することはない。v2.1.214 以降が必要

/memory コマンド

  • user / project スコープの CLAUDE.md、CLAUDE.local.md、その他の memory ファイルの場所を一覧する。まだ存在しない user / project の CLAUDE.md エントリも含む
  • auto memory のオン・オフ切り替えと、auto memory フォルダを開く操作ができる
  • ファイルを選ぶとエディタで開く。存在しないファイルを選ぶと先に作成する
  • 実際に現在のセッションへ読み込まれたファイルを確認するには /context を使う
  • VS Code などの GUI エディタは別ウィンドウで開き、開いている間もセッションを使い続けられる。v2.1.216 より前は /memory がファイルを閉じるまで応答を待っていた。Vim などのターミナルエディタは終了までターミナルを占有する

設定

{
  "autoMemoryEnabled": false
}
{
  "autoMemoryDirectory": "~/my-custom-memory-dir"
}
{
  "claudeMd": "Always run `make lint` before committing.\nNever push directly to main."
}
{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}
---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation

制約・注意点

  • CLAUDE.md の内容はシステムプロンプトの一部ではなく、システムプロンプトの後のユーザーメッセージとして届けられる。厳密な遵守は保証されない
  • CLAUDE.md は 1 ファイル 200 行未満が目安。長いファイルはコンテキストを消費し遵守率を下げる。@path import への分割は整理には役立つがコンテキスト削減にはならない（import されたファイルも起動時に読み込まれるため）
  • 矛盾するルールがあると Claude はどちらかを任意に選ぶ
  • 特定の時点で必ず実行させたい指示は hook として書く
  • システムプロンプトのレベルで指示したい場合は --append-system-prompt を使う。毎回の起動で渡す必要がある
  • InstructionsLoaded hook で、どの指示ファイルが、いつ、なぜ読み込まれたかを記録できる
  • /doctor はチェックイン済み CLAUDE.md の削減案を提示する。コードベースから導出できる内容（ディレクトリ構成、依存一覧、アーキテクチャ概要）を削り、落とし穴・理由・ツール既定と異なる規約を残す。v2.1.206 以降が必要
  • /compact 後、プロジェクトルートの CLAUDE.md はディスクから再読込されてセッションに再注入される。サブディレクトリのネストした CLAUDE.md と paths: frontmatter を持つ rule は自動では再注入されず、次にそのサブディレクトリのファイルやパターンに一致するファイルを読んだときに再読込される

関連

  • facts/claude-code/settings.md
  • facts/claude-code/skills.md
  • facts/claude-code/hooks.md
  • facts/claude-code/sub-agents.md
  • facts/claude-code/context-window.md
  • facts/claude-code/commands.md
  • facts/claude-code/cli-reference.md
  • facts/claude-code/env-vars.md