ai-docs

How Claude remembers your project

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

17 min read

一行要約

セッションを跨いで知識を運ぶ手段は 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チーム（version control 経由）
Local instructions./CLAUDE.local.md自分だけ（.gitignore に入れる）

解決順の詳細:

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

効果的な指示の書き方

サイズ: 1ファイル 200行未満を目標にする。長いほど context を食い、遵守率が下がる。

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
  • 外部 import の承認ダイアログ: プロジェクトレベルの memory ファイルが作業ディレクトリの外を指す import を持つ場合、初回に承認ダイアログが出る。断ると以後無効のままになる。これは他人が共有プロジェクトにコミットしたファイルから守るための仕組み。user スコープ（~/.claude/CLAUDE.md など）の import は自分が書いたものなのでダイアログなし

AGENTS.md との関係

Claude Code が読むのは CLAUDE.md であって AGENTS.md ではない。 既に AGENTS.md があるなら、それを import する CLAUDE.md を作る。symlink でもよい（ただし Windows では管理者権限か開発者モードが要るので import を使う）。

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

.claude/rules/

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

  • paths frontmatter がない rule は起動時にロードされ、優先度は .claude/CLAUDE.md と同じ
  • paths がある rule は、該当パターンのファイルを Claude が読んだときにだけ発火する（すべてのツール使用時ではない）
  • ~/.claude/rules/ はマシン全体に適用される。user レベルの rule が先に読まれ、project rule のほうが優先度が高い
  • 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. rule は毎セッション、あるいは該当するファイルを開いたときに context へロードされる。常時 context に置く必要のないタスク固有の指示には、代わりに skill を使え。

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

既定でオン。/memory のトグル、autoMemoryEnabled 設定、または環境変数 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 で切れる。

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

仕組み:

  • 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 は見えていない
  2. ロードされる場所に置かれているか確認する
  3. 指示をより具体的にする
  4. CLAUDE.md 間で矛盾する指示を探す

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

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

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

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

未取得の派生リンク

グラフビュー

バックリンク