| name | claude-md-memory |
| description | CLAUDE.md / CLAUDE.local.md / `.claude/rules/` / auto memory —— Claude Code の記憶ファイルを 書く・削る・移す・レビューするときのガイド。何を書き何を書かないか、どのスコープに置くか、 CLAUDE.md ではなく hook / `permissions.deny` に移すべきか、200 行をどう守るかを判断できる。 以下のいずれかのとき必ず読むこと —— (1) CLAUDE.md / CLAUDE.local.md を新規作成・追記・整理・レビューする、`/init` の生成物を仕上げる、 (2) 「これを覚えておいて」「ルール化して」「規約に追加して」と頼まれた、 (3) ルート CLAUDE.md か、パッケージ直下の CLAUDE.md か、path スコープの `.claude/rules/` か、 skill かで置き場所に迷う、 (4) 「指示に従ってくれない」「必ず守らせたい」「CLAUDE.md が効かない／大きすぎる／compact 後に 消えた」を調べる、 (5) `@path` import・AGENTS.md 連携・`claudeMdExcludes`・auto memory の仕組みを扱う。 記憶ファイルに触るならまずこれを読む。
|
CLAUDE.md のあるべき姿
前提: CLAUDE.md は「強制」ではなく「コンテキスト」
CLAUDE.md はシステムプロンプトではない。システムプロンプト直後の user メッセージとして毎
セッション全文が届くだけで、遵守は保証されない。曖昧・冗長・矛盾しているほど従われなくなる。
ここから 2 つの帰結が出る。これがこのガイドの土台。
- 品質の基準は「正しいことが書いてあるか」ではなく「毎回必ず従わせられるか」。正しいが冗長な
1 行は、周りの 199 行の遵守率を下げる純損失。書いてある量ではなく、効いている量で評価する。
- 絶対に守らせたいものは CLAUDE.md に書かない。「必ず〜する」「〜は禁止」と書いても確率的に
破られる。強制が要るなら hook（ライフサイクルで必ず走る）か settings の
permissions.deny（ツール実行自体を止める）にする。CLAUDE.md は「破られたら困る」ではなく
「知らないと毎回間違える」ことのための場所。
書く基準（これ以外は書かない）
「これが無いと Claude が毎回間違える／毎回同じ説明をさせられる」——それだけを書く。既存の
CLAUDE.md をレビューするときも同じ問いを行ごとに当て、満たさない行は消す。
追加の合図（公式ドキュメントの「when to add」）:
- Claude が同じミスを 2 回した。
- コードレビューが、Claude が知っておくべきだったことを指摘した。
- 先週と同じ訂正をまたチャットに打ち込んだ。
- 新しいチームメンバーが生産的になるのに同じ前提説明が要る。
書いてはいけないもの（＝レビューの問い）
CLAUDE.md が肥大化する原因はほぼこの 9 つ。書き足す前に、既存の記述をこの 9 つで行ごとに問う。
1 つでも該当したら、書き換えるか消す。
- コードを読めば分かること — ディレクトリ一覧、ファイルの逐語説明、
package.json を見れば
分かるスクリプト。Claude は読める。書くのは「読んでも分からないこと」だけ。→ 消す。
- 一般論・ベストプラクティス — 「読みやすいコードを書く」「テストを書く」「DRY にする」。
モデルは既に知っている。純粋なノイズで、周りの本当のルールの遵守率を下げる。→ 消す。
- 検証できない形容 — 「適切に」「きれいに」「必要に応じて」。読んだ後に従えたか判定できない
指示は指示ではない。→ 「2 スペースインデント」「コミット前に
pnpm test」まで具体化する。
- 経緯・変更履歴 — 「かつて〜だった」「〜を撤去したため」。それは git の仕事。CLAUDE.md は
常に現在の状態と、いま守るべきことだけを書く。→ 消す。
- 長文の設計仕様・根拠 — 設計の全体像は
docs/specs/*.md に置き、CLAUDE.md からはリンク
1 行で参照する。両方に書くと必ず drift する。→ docs/specs へ出してリンクにする。
- 手順（複数ステップのワークフロー） — 必要なときだけロードされ、常時コンテキストを食わない
のが skill。→
.claude/skills/ へ移す。
- 一部のディレクトリでしか効かないルールをルートに書く — ルートは全ディレクトリで必要なもの
だけ。→ そのディレクトリ直下の CLAUDE.md か path スコープの rule へ移す。
- 同じ内容の二重記述 — ルートと下位 CLAUDE.md、CLAUDE.md とコードコメント、CLAUDE.md と
README。二重化した瞬間から片方は腐る。→ 正典を 1 か所に決め、他はリンクにする。
- 禁止だけ書いて代替を示さない — 「X するな」は、Claude を「では何を?」で止める。
→ 「X ではなく Y する」と書く。
加えて、行ごとに「破られたら困るか?」を問う。Yes なら CLAUDE.md に残しても保証されないので、
hook / permissions.deny に移す（「前提」の通り）。
1 ルールの書き方
- 命令形・断定・1 ルール 1 行。段落で説明しない。
- 検証可能な粒度まで落とす（「整理する」→「API ハンドラは
src/api/handlers/ に置く」）。
- 理由（why）が遵守に効くなら同じ行に短く添える。理由が長くなるなら docs/specs へ出して
リンクする。CLAUDE.md 内で理由を語り始めたら、それは仕様書のシグナル。
書き換え例
| ✗ 書かれがちな行 | ○ 直した行 | 何を直したか |
|---|
| エラーは適切にハンドリングする | 失敗は throw せず Result で返す（.claude/rules/result-type.md） | 検証できない形容 → 検証可能な粒度 |
git commit --no-verify は使用禁止 | --no-verify は使わない。フックが落ちたら原因を直して再コミットする | 禁止だけ → 代替の明示 |
apps/frontend は React + Vite + Tailwind のディレクトリ。src/ 配下に app/ pages/ … | フロントは FSD v2.1。詳細は apps/frontend/CLAUDE.md | コードを読めば分かること → リンク 1 行 |
依存を足すときは registry がプロキシで minimumReleaseAge があるので、まず 21 日待って…（10 行の説明） | 依存や lockfile を触るときは pnpm-dependencies skill を読む | 手順 → skill へ |
どこに置くか（決定表）
| 書きたいもの | 置き場所 |
|---|
| 全体に効く恒久ルール（構成・共通コマンド・コミット規約） | ルート CLAUDE.md |
| 特定パッケージ／ディレクトリにしか効かないルール | そのディレクトリ直下の CLAUDE.md（そこのファイルを読むときだけロードされる） |
| 特定のファイル型／パスのときだけ効かせたいルール | .claude/rules/*.md の paths: frontmatter |
| 手順的で、必要なときだけ読めばよいもの | .claude/skills/<name>/ |
| 設計の根拠・仕様の全体像（長文） | docs/specs/*.md（CLAUDE.md からリンク。両方に書かない） |
| 個人的・非共有の設定 | CLAUDE.local.md（.gitignore 済み） |
| 破られたら困るもの | hook / settings の permissions.deny（CLAUDE.md ではない） |
ロード順（broadest → most specific で concat）・サブディレクトリの遅延ロード・@path import・
claudeMdExcludes は references/loading-and-placement.md。
.claude/rules/ と path スコープの詳細は references/rules-and-scoping.md。
サイズと構造
- 1 ファイル 200 行未満を目安。CLAUDE.md は長さに関わらず全文が毎セッション載る
（auto memory の
MEMORY.md にある「先頭 200 行 / 25KB」の打ち切りは効かない）。長いほど
コンテキストを食い、遵守率が落ちる。
- 超えたら、削るか、下位 CLAUDE.md / path スコープ rule に逃がす。
@path import は
整理にはなるがコンテキストは減らない（import 先も launch 時に全部載る）。
- 見出しと箇条書きで束ねる。密な段落にしない。
- 人間のメンテナ向けメモは HTML コメント（
<!-- ... -->）で書ける。コンテキスト注入前に
除去されるのでトークンを消費しない。
このリポジトリでの適用
- 日本語で書く（ルート CLAUDE.md「ドキュメントの言語」）。
- 新しいパッケージに CLAUDE.md を足したら、ルート CLAUDE.md の「ドキュメントの置き場所」節の
リンク一覧にも追記する。ルートに詳細を持ち込まず、リンクで参照する。
- 既存の CLAUDE.md がこのガイドに反していたら、ガイドではなく CLAUDE.md を直す。既存記述に
合わせて基準を緩めない。
作った後
/memory — いまロードされている CLAUDE.md / CLAUDE.local.md / rules を一覧・編集する。
「効かない」ときはまずここでそのファイルがロードされているかを確認する。/init — コードベースを解析して CLAUDE.md の叩き台を生成する。生成物は「コードを読めば
分かること」を大量に含むので、そのまま置かず上の 9 つの問いで削ってから残す。
強制の境界（hook / settings との使い分け）・トラブルシュート（効かない／大きすぎる／compact 後に
消えた）・auto memory の仕組み・/init /memory の細かい挙動は
references/writing-and-troubleshooting.md。
