ai-docs

How Claude remembers your project

Properties1
tagsclaude-code, context, memory, claude-md, rules, configuration

原典: How Claude remembers your project ／ 日本語版

一行要約

セッションを跨いで知識を運ぶ手段は CLAUDE.md（自分が書く指示） と auto memory（Claude が書く学習） の2系統で、どちらも「強制される設定ではなく context」なので、必ず守らせたいことは hook にするしかない。

要点

CLAUDE.md と auto memory の違い

Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead.

Claude はそれらを、強制される設定ではなく context として扱う。Claude の判断によらず動作をブロックしたいなら、代わりに PreToolUse hook を使え。

これが最も重要な前提。CLAUDE.md も auto memory も「指示」であって「強制」ではない。

CLAUDE.mdAuto memory
誰が書くか自分Claude
中身指示とルール学習とパターン
スコーププロジェクト / ユーザー / 組織リポジトリ単位（worktree 間で共有）
ロード毎セッション毎セッション（先頭 200行 または 25KB）
用途コーディング規約、ワークフロー、アーキテクチャビルドコマンド、デバッグの知見、Claude が発見した好み

The more specific and concise your instructions, the more consistently Claude follows them.

指示が具体的かつ簡潔であるほど、Claude はより一貫してそれに従う。

いつ CLAUDE.md に書くか

Treat CLAUDE.md as the place you write down what you’d otherwise re-explain.

CLAUDE.md は、書いておかなければ何度も説明し直すことになるものを書き留める場所だと考えよ。

  • Claude が同じ間違いを2回目にしたとき
  • コードレビューが「このコードベースについて Claude が知っておくべきだったこと」を指摘したとき
  • 前のセッションでも打った訂正や補足を、またチャットに打ち込んだとき
  • 新しいチームメイトが生産的になるのに同じ文脈が要るとき

逆に、多段の手順やコードベースの一部にしか関係しないものは、skill か path-scoped rule に移す。

置き場所と読み込み順

上から下へ、広いスコープから具体的なスコープへ。後に読まれるものほど Claude に近い。

スコープ場所共有範囲
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。./AGENTS.md がこれらの代わりに（または並んで）読まれる条件は下の「AGENTS.md を直接読むようになった」節チーム（version control 経由）
Local instructions./CLAUDE.local.md自分だけ（.gitignore に入れる）

解決順の詳細:

  • 作業ディレクトリからルートに向かって遡り、各階層の CLAUDE.md と CLAUDE.local.md を集める
  • 集めたものは上書きではなく連結される
  • 順序はファイルシステムのルート側が先、作業ディレクトリ側が後。つまり起動地点に近い指示ほど最後に読まれる
  • 各階層内では CLAUDE.local.md が CLAUDE.md の後に付く
  • サブディレクトリの CLAUDE.md は起動時ではなく、そのディレクトリのファイルを読んだときにロードされる

効果的な指示の書き方

サイズ: 1ファイル 200行未満を目標にする。長いほど context を食い、遵守率が下がる。推奨の長さを超えたファイルがあると、起動時と /status で警告が出る。1本ずつは収まっていても、起動時の合計が上限を超えると警告が出る（CLAUDE.md・rule のファイル・@path の import はそれぞれ別のファイルとして数える）。

Splitting into @path imports helps organization but doesn’t reduce context, since imported files load at launch.

@path の import に分割すると整理には役立つが、context は減らない。import されたファイルは起動時にロードされるからである。

import は整理には効くが context 削減にはならない。減らしたいなら path-scoped rule を使う。

構造: markdown の見出しと箇条書きでグループ化する。

Claude scans structure the same way readers do: organized sections are easier to follow than dense paragraphs.

Claude は人間の読み手と同じように構造を走査する。整理された節のほうが、密な段落より辿りやすい。

具体性: 検証できるくらい具体的に書く。

❌✅
Format code properlyUse 2-space indentation
Test your changesRun npm test before committing
Keep files organizedAPI handlers live in src/api/handlers/

一貫性: 矛盾する2つのルールがあると、Claude はどちらかを恣意的に選ぶ。定期的に見直して古い・矛盾する指示を削る。monorepo では claudeMdExcludes で他チームの CLAUDE.md を除外する。

@path import

  • 相対パスと絶対パスの両方が使える。相対パスは import を書いたファイルからの相対（作業ディレクトリ基準ではない）
  • 再帰的に import できるが最大4ホップ
  • コードスパンとコードブロック内は import されない。`@README` はリテラル、@README は import
  • パスに空白があるなら、空白ごとにバックスラッシュを置く（@Design\ Docs/api-conventions.md）。無いと最初の空白でパスが切れる（import だけの行でも）。引用符で囲んだパスは、バックスラッシュの有無に関わらず import されない
  • 外部 import の承認ダイアログ: プロジェクトレベルの memory ファイルが作業ディレクトリの外を指す import を持つ場合、初回に承認ダイアログが出る。断ると以後無効のままになる。これは他人が共有プロジェクトにコミットしたファイルから守るための仕組み。user スコープ（~/.claude/CLAUDE.md など）の import は自分が書いたものなのでダイアログなし

AGENTS.md を直接読むようになった（v2.1.277 以降）

以前は「Claude Code が読むのは CLAUDE.md であって AGENTS.md ではない」だったが、逆になった。 他のコーディングエージェント向けに整えたリポジトリは、CLAUDE.md も import も設定も足さずにそのまま動く。

リポジトリにあるものClaude が読むもの
AGENTS.md があり、作業ディレクトリとその上に CLAUDE.md も CLAUDE.local.md も無いAGENTS.md
AGENTS.md と、作業ディレクトリかその上に CLAUDE.md / CLAUDE.local.md があるCLAUDE.md だけ
CLAUDE.md がすでに AGENTS.md を import しているCLAUDE.md（import 経由で AGENTS.md も入る）

「CLAUDE.md がある」の判定に数えるものと数えないもの:

  • 数える（あると AGENTS.md の代わりにそちらが読まれる）—— 作業ディレクトリとその上の CLAUDE.md / .claude/CLAUDE.md / CLAUDE.local.md
  • 数えない（AGENTS.md と並んでロードされ続ける）—— ~/.claude/CLAUDE.md、組織の managed CLAUDE.md、.claude/rules/

CLAUDE.local.md が数えられるのが落とし穴。 AGENTS.md に頼っているプロジェクトに、自分用の未コミット指示として CLAUDE.local.md を1つ足すと、そのせいで AGENTS.md が読まれなくなる。両方要るなら下の設定を claude-md-and-agents-md にする。

読まれるもの / 読まれないもの:

  • セッション開始時 —— 作業ディレクトリとその上にある AGENTS.md と .claude/AGENTS.md すべて。対話セッションでは no CLAUDE.md found; AGENTS.md loaded: ... の行が出る
  • 作業中 —— サブディレクトリのファイルを Read したとき、そのディレクトリに3種の CLAUDE.md が無ければ、そこの AGENTS.md
  • AGENTS.md の中 —— @path import は展開され、claudeMdExcludes も効き、プロジェクト指示を読まない subagent はこれも読まない
  • 読まれない —— AGENTS.local.md、AGENTS.override.md、.agents/ 配下

どのファイルを読むかの設定（/config の Project instructions）:

値読むもの
claude-md-or-agents-md既定。CLAUDE.md、無ければ AGENTS.md
claude-md-and-agents-md両方。各ディレクトリで CLAUDE.md が先、AGENTS.md が後。すでに読んだ AGENTS.md は飛ばすので import や symlink があっても二重に読まれない
claude-mdCLAUDE.md だけ
managed-only起動時は組織の managed CLAUDE.md と auto memory だけ。project / local / user の CLAUDE.md、.claude/rules/、AGENTS.md は入らない（サブディレクトリの CLAUDE.md と .claude/rules/、パス指定の rule は、そこのファイルを読んだ時点で今までどおりロードされる）

設定ファイルに書くなら pluginConfigs の agents-md@builtin の options.instructionFiles。~/.claude/settings.json・--settings・managed settings でのみ有効で、project / local settings では無視される。

使えないセッション（CLAUDE.md だけを読み、/config に Project instructions が出ない）: v2.1.277 より前、/plugin で agents-md を無効にした場合、アップグレード直後の最初のセッション（feature flag 未取得のため。常にではないが起こりうる。次のセッションからは読む）。v2.1.281 より前は Bedrock やテレメトリ無効のセッションも該当した。

CLAUDE.md と違うところ:

CLAUDE.md設定経由で読む AGENTS.md
InstructionsLoaded hook発火する発火しない（CLAUDE.md が import / symlink した AGENTS.md なら発火する）
--add-dir + CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MDそのディレクトリの CLAUDE.md が読まれるAGENTS.md は読まれない
作業ディレクトリ外への @path import承認ダイアログが出るすでにこのプロジェクトで外部 import を承認済みなら、プロンプト無しで読む

以前の回避策をどうするか:

  • @AGENTS.md を書いた CLAUDE.md —— 残してよい。どの設定値でも二重に読まれることはない。AGENTS.md を直接読めないセッションがあるなら残すほうが安全
  • 「AGENTS.md を読め」と文章で書いた CLAUDE.md —— それだと Claude がファイルを開く判断をしたときしか読まれない。CLAUDE.md を消すか、@AGENTS.md の import に置き換える
  • CLAUDE.md を AGENTS.md への symlink にしている —— そのままでも消してもよい。どちらも1回だけ読まれる。ただし symlink には2つ難がある: Edit / Write は symlink 越しの書き込みを拒否する（リンク先の AGENTS.md を直せと Claude に伝える）、Windows では作成に管理者権限か開発者モードが要り、core.symlinks が無効な clone ではただの1行テキストファイルとして落ちてくる（＝そのマシンには指示が無い状態になる）
  • AGENTS.md を流し込む SessionStart hook —— 外す。 直接読むようになった今、context に2つ目の写しが入る

/init は .cursor/rules/ / .cursorrules と .github/copilot-instructions.md を読んで取り込む。CLAUDE_CODE_NEW_INIT=1 を設定すると AGENTS.md、.devin/rules/、.windsurf/rules/ / .windsurfrules、.clinerules も読む。

.claude/rules/

大きなプロジェクト向けにトピック別ファイルへ分割する仕組み。.md は再帰的に発見されるので frontend/ backend/ のようにサブディレクトリで整理できる。

  • paths frontmatter がない rule は起動時にロードされ、優先度は .claude/CLAUDE.md と同じ
  • paths がある rule は、該当パターンのファイルに Claude が Read / Write / Edit ツールを使ったときにだけ発火する（すべてのツール使用時ではない）
  • ~/.claude/rules/ はマシン全体に適用される。user レベルの rule が先に読まれ、project rule のほうが優先度が高い
  • symlink をサポートする。共有ルール集をリンクして複数プロジェクトで使える。ただしリンク先がネットワークパス（UNC 共有 \\server\share、/net や /Network の下）だと読み込まれない（そのパスを引くだけで名指しされたホストに接続しうるため。\\wsl$ は対象外）。CLAUDE.md の symlink も同じ

Rules load into context every session or when matching files are opened. For task-specific instructions that don’t need to be in context all the time, use skills instead, which only load when you invoke them or when Claude determines they’re relevant to your prompt.

rule は毎セッション、あるいは該当するファイルを開いたときに context へロードされる。常時 context に置く必要のないタスク固有の指示には、代わりに skill を使え。skill は、自分が呼んだときか、Claude がプロンプトに関係すると判断したときにしかロードされない。

glob パターンの注意点（実装の細部だが踏むと痛い）:

パターンマッチするもの
**/*.ts任意のディレクトリの TypeScript ファイル
src/**/*src/ 配下の全ファイル
*.mdプロジェクトルートの Markdown
src/components/*.tsx特定ディレクトリの React コンポーネント
  • brace 展開は掛け算で増える。{a,b}/{c,d}/*.{ts,tsx} は8パターンに展開される。paths リスト全体で 1,000 パターン / 4 MiB の予算を共有し、超えるパターンは展開されないまま使われる（リテラルの波括弧は何にもマッチしない）。波括弧を含まないパターンは予算を消費しない
  • glob は [ を bracket expression の開始と解釈する。photos [2024/** のような不正なパターンは何にもマッチしない。リテラルの [ は photos \[2024/** とエスケープする

組織向けの一元管理

  • managed policy の場所に CLAUDE.md を置き、MDM / Group Policy / Ansible などで配布する
  • managed-settings.json の claudeMd キーに内容を直接書くこともできる。managed / policy 設定でのみ有効で、user / project / local に書いても効果がない
  • claudeMdExcludes で特定の CLAUDE.md を glob 除外できる。設定レイヤをまたいで配列はマージされる。ただし managed policy の CLAUDE.md は除外できない

設定と CLAUDE.md の使い分け:

関心事書く場所
特定のツール・コマンド・パスをブロックする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

Settings rules are enforced by the client regardless of what Claude decides to do. CLAUDE.md instructions shape Claude’s behavior but are not a hard enforcement layer.

設定ファイルのルールは、Claude が何をしようと決めるかによらずクライアントが強制する。CLAUDE.md の指示は Claude の振る舞いを形づくるが、強制の層ではない。

auto memory

Claude が自分のためにメモを書き溜める仕組み。ビルドコマンド、デバッグの知見、アーキテクチャのメモ、コードスタイルの好み、ワークフローの習慣。

Claude doesn’t save something every session. It decides what’s worth remembering based on whether the information would be useful in a future conversation.

Claude は毎セッション何かを保存するわけではない。その情報が将来の会話で役立つかどうかで、記憶する価値があるかを判断する。

ローカルのセッションでは既定でオン（self-hosted environment のセッションは、Claude Tag を除き既定でオフ）。/memory のトグル、autoMemoryEnabled 設定、または環境変数 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 で切れる。background セッションと、別の Claude Code セッションが起動したセッション（Claude が Bash で claude を走らせた場合など）では、トグルで切れても入れ直せない（off · can't be turned on here; … と出る）。入れ直すなら端末で直接 claude を起動してそこでトグルする。

保存場所: ~/.claude/projects/<project>/memory/。<project> は git リポジトリから導出されるので、同一リポジトリの全 worktree とサブディレクトリが1つの auto memory ディレクトリを共有する。git 管理外ではプロジェクトルートが使われる。autoMemoryDirectory で変更できる（user / project / local / policy / --settings のどのスコープからでも読まれる）。

  • CLAUDE_CONFIG_DIR と並べて CLAUDE_CODE_PROJECT_DIR_NAME を設定すると、どのリポジトリで起動しても <config dir>/projects/ のその名前が使われるので、その config ディレクトリで立てたプロジェクトが1つの auto memory を共有する（v2.1.234 以降）
  • auto memory はマシンローカル。 マシン間やクラウド環境では共有されない
  • cleanupPeriodDays の削除対象から除外されている。 古いセッション transcript が消えても、MEMORY.md とトピックファイルは誰かが編集か削除をするまで残る

仕組み:

  • MEMORY.md の先頭 200行、または 25KB のうち先に達したほうが毎会話の冒頭にロードされる。それを超える内容はロードされない
  • 書き込み後に Claude Code が上限を測り、近ければ「1エントリ1行にせよ、詳細はトピックファイルへ、古いものは統合か削除せよ」と Claude に促す。超えていれば書き込み自体は成功するがエラーを返す（次回ロード時に切り捨てられるため）
  • 測定対象は実際にロードされる内容のみ。YAML frontmatter とブロックレベルの HTML コメントは除去されてから測られる
  • この上限は MEMORY.md にだけ適用される。CLAUDE.md は長さに関わらず全文ロードされる
  • debugging.md のようなトピックファイルは起動時にはロードされない。必要になったとき Claude が通常のファイルツールで読む
  • メインの会話の auto memory は subagent にはロードされない。例外は fork（親の会話と system prompt を継承する）
  • frontmatter を持つ memory ファイルには、書き込み時刻が modified フィールドに ISO 8601 で記録される

トラブルシューティング

CLAUDE.md に従ってくれない

CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself.

CLAUDE.md の内容は、system prompt の一部としてではなく、system prompt の後に置かれる user メッセージとして届けられる。

CLAUDE.md は system prompt ではなく、system prompt の後に置かれる user メッセージとして届く。 だから厳密な遵守の保証はない。

デバッグ手順:

  1. /context を実行して Memory files の一覧に自分のファイルが載っているか確認する。載っていなければ Claude は見えていない
    • AGENTS.md を直接読ませている場合はこの手順で誤診する。 /memory を実行してパスが載っているかを見る。v2.1.280 より前は /memory も /context も直接読んだ AGENTS.md を一覧しなかったので、そのバージョンでは「プロジェクト指示に何が書いてあるか」を Claude に聞く
  2. ロードされる場所に置かれているか確認する
  3. 指示をより具体的にする
  4. CLAUDE.md 間で矛盾する指示を探す
  5. Claude Code が自分で足す指示と競合していないか確かめる。CLAUDE.md でコミットや PR の規則を決めているなら、組み込みの規則は includeGitInstructions で切り、帰属の文面は attribution で決める

特定の時点で必ず走らせたいこと（コミット前、ファイル編集後）は hook にする。system prompt レベルに置きたいなら --append-system-prompt（毎回渡す必要があるのでスクリプト向き）。

InstructionsLoaded hook を使うと、どの指示ファイルが・いつ・なぜロードされたかを記録できる。

古い指示・存在しない参照・ファイル間の矛盾を点検する — /doctor prompt-audit（v2.1.283 以降）。CLAUDE.md・CLAUDE.local.md・AGENTS.md と、.claude/ と ~/.claude/ の下の rule・skill・command・subagent・output style を読み、古いモデル向けに書かれた指示、無いファイルやコマンドへの参照、互いに矛盾するファイルを探す。結果は報告と修正案で、頼むまでファイルは変わらない。パスを渡せば1ファイル・1ディレクトリだけを点検する。同梱の /claude-api skill を使うので、それを skillOverrides や disableBundledSkills で切っていると使えない。

CLAUDE.md が大きすぎる — /doctor の健診が、コードベースから導出できる内容（ディレクトリ構成、依存一覧、アーキテクチャ概説）を削り、落とし穴・理由・ツール既定と異なる規約を残す trim を提案してくれる。

/compact の後に指示が消えた

compaction 後の挙動
プロジェクトルートの CLAUDE.md生き残る。ディスクから読み直して再注入される
サブディレクトリのネストした CLAUDE.md再注入されない。そのディレクトリのファイルを次に読んだときに再ロード
paths: frontmatter を持つ rule再注入されない。該当ファイルに次にマッチしたときに再ロード

消えたなら「会話でしか言っていなかった」「まだ再ロードされていないネスト CLAUDE.md」「まだマッチしていない path-scoped rule」のいずれか。

そのまま使える具体例

@path import:

See @README for project overview and @package.json for available npm commands for this project.
 
# Additional Instructions
- git workflow @docs/git-instructions.md

worktree をまたいで個人設定を共有する（CLAUDE.local.md は作った worktree にしか存在しないため）:

# Individual Preferences
- @~/.claude/my-project-instructions.md

既存の AGENTS.md を活かす:

@AGENTS.md
 
## Claude Code
 
Use plan mode for changes under `src/billing/`.
ln -s AGENTS.md CLAUDE.md

.claude/rules/ の構成:

your-project/
├── .claude/
│   ├── CLAUDE.md           # Main project instructions
│   └── rules/
│       ├── code-style.md   # Code style guidelines
│       ├── testing.md      # Testing conventions
│       └── security.md     # Security requirements

path-scoped rule:

---
paths:
  - "src/api/**/*.ts"
---
 
# API Development Rules
 
- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

複数パターンと brace 展開:

---
paths:
  - "src/**/*.{ts,tsx}"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---

ルールを複数プロジェクトで共有する:

ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md

managed settings に CLAUDE.md 内容を直接書く:

{
  "claudeMd": "Always run `make lint` before committing.\nNever push directly to main."
}

monorepo で他チームの CLAUDE.md を除外する（.claude/settings.local.json に置く）:

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

auto memory をプロジェクト単位で切る:

{
  "autoMemoryEnabled": false
}

auto memory ディレクトリの構成:

~/.claude/projects/<project>/memory/
├── MEMORY.md          # Concise index, loaded into every session
├── debugging.md       # Detailed notes on debugging patterns
├── api-conventions.md # API design decisions
└── ...                # Any other topic files Claude creates

--add-dir 先の memory ファイルも読ませる:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

原典で言及されている関連文書

バックリンク