CLAUDE.md を正しく育てる ― Claude Code の「記憶」を活かす書き方と、GitHub 例を取り込むときの落とし穴

Claude Code を使い始めると、最初の数日で気づくことがあります。同じ指示を毎回チャットに貼り直している、あるいはルールを伝えたのに Claude が守らない場面が出てくる。そういった問題を解決するために用意されているのが CLAUDE.md です。

CLAUDE.md は、Claude Code がセッション開始時に毎回読み込む Markdown の指示ファイルです。人間が書き、Claude が読む。一度書いておけば、次のセッションでも同じコンテキストから始められます。GitHub には他者の CLAUDE.md が多数公開されており、そのまま取り込もうとする動きも出ています。ただし、取り込み方を間違えると逆効果になります。この記事では、効く書き方と、他者の例を活用するときの具体的な注意点を整理します。

CLAUDE.md の置き場所と適用範囲

CLAUDE.md は置く場所によって適用範囲が変わります。読み込み順は「広い→狭い」の順で、複数ある場合はすべて読み込まれます。

置き場所	適用範囲
/etc/claude-code/CLAUDE.md(Linux/WSL)または /Library/Application Support/ClaudeCode/CLAUDE.md(macOS)	組織全体。個人設定では除外できない
~/.claude/CLAUDE.md	自分のすべてのプロジェクトに適用
./CLAUDE.md または ./.claude/CLAUDE.md	プロジェクト単位。バージョン管理でチーム共有
./CLAUDE.local.md	自分だけの設定。.gitignore に入れて管理

作業ディレクトリより上位にある CLAUDE.md は起動時に全文読み込まれます。サブディレクトリの CLAUDE.md は、Claude がそのディレクトリのファイルを読む瞬間に on-demand で読み込まれます。

すでに AGENTS.md を使っているチームへの補足です。Claude Code は AGENTS.md を直接読みません。CLAUDE.md から @AGENTS.md でインポートするか、symlink を張ることで対応できます。

① 効く書き方のポイント

「200 行未満」を守る

公式ドキュメントは「1 ファイル 200 行未満を目標(target under 200 lines per CLAUDE.md file)」と明記しています。長くなるほどコンテキストを消費し、重要な指示が埋もれて遵守率が下がります。公式は「Bloated CLAUDE.md files cause Claude to ignore your actual instructions」とまで言っています。

200 行を超えてきたら分割を検討します。.claude/rules/ ディレクトリに YAML frontmatter の paths: を持つファイルを置くと、特定のファイルやディレクトリを触るときだけ読み込まれるパススコープルールとして機能します。頻度の低いルールをここに移せば、メインの CLAUDE.md をコンパクトに保てます。

入れるべきこと / 入れないこと

公式の Best practices では、以下の対比が明示されています。

入れるべきこと:

• Claude が推測できないコマンド(ビルド手順、テストランナーの呼び方)
• コードを読んでも分からないスタイル規約
• ブランチ名・PR タイトルの規約など、リポジトリ固有の作法
• 開発環境の癖(必要な環境変数など)
• 非自明な落とし穴

入れないこと:

• コードを読めば分かること
• 言語の標準的な慣習
• 詳細な API ドキュメント(リンクで足りる)
• 頻繁に変わる情報
• 「きれいに書け」のような自明な指示

判断軸は一つです。「これを消したら Claude がミスするか?」という問いを各行に当てて、Noならば削る。これを続けると CLAUDE.md は自然に引き締まります。

強調と具体性

「IMPORTANT」「YOU MUST」といった強調語は、遵守率を上げる効果があると公式が明記しています。ただし乱発すると効果が薄れます。本当に外してほしくないルールに絞って使うのが実際の運用です。

具体性も重要です。「Format code properly」より「Use 2-space indentation」のように、検証できる粒度で書くことが推奨されています。

たまにしか使わない知識は skill へ

公式は「たまにしか要らない知識は CLAUDE.md ではなく skill に」と整理しています。skill は必要時にだけ読み込まれる仕組みで、毎回コンテキストを消費しません。逆に、必ず実行してほしい動作は CLAUDE.md(助言的)ではなく hook(決定論的)が適切です。この使い分けは後述します。

/init と /memory を活用する

/init コマンドを使うと、コードベースを解析してビルドコマンドやテスト手順などを検出し、CLAUDE.md の雛形を自動生成してくれます。既存の CLAUDE.md がある場合は上書きせず、改善提案という形で出力されます。

現在どの CLAUDE.md が読み込まれているかを確認するには /memory コマンドを使います。CLAUDE.md、CLAUDE.local.md、パススコープルールが一覧で表示されます。ファイルが増えてきたときの棚卸しに使えます。

② GitHub の CLAUDE.md を取り込むときの注意点

「型を借りる」と「丸ごとコピー」は別物

他者の CLAUDE.md は、その人のスタック・チーム規約が前提になっています。丸ごとコピーすると、自分のプロジェクトに無関係なルールが混じり、コンテキストが肥大化します。200 行を超えると遵守率が下がるという公式の警告がここで効いてきます。

取り込み方のポイントは、「ファイルではなく型(パターン)を借りる」ことです。他者の CLAUDE.md を見て「なぜこの指示が入っているか」を読み解き、自分のプロジェクトに必要な形に書き直す。丸ごとペーストで済まそうとすると、検証していない指示を取り込むことになります。公式も「specific でない/矛盾する指示は遵守が不安定」と明記しています。

@path インポートの承認ダイアログを反射的に許可しない

CLAUDE.md はインポート構文 @path/to/file で別ファイルを取り込めます。インポートは再帰対応で最大 4 ホップ可能です。重要な点として、インポートは「コンテキスト削減にはなりません」。インポート先も起動時にすべて展開されます。

他者の CLAUDE.md を取り込んだとき、その中に @path が書いてあると、意図しないファイルまで読み込まれる可能性があります。Claude Code は外部インポートを初めて検出した際に「対象ファイル一覧の承認ダイアログ」を表示します。このダイアログが出たら、反射的に OK を押さず、何が読み込まれるかを一つひとつ確認してください。

プロンプトインジェクションのリスクを知っておく

信頼できない出所の指示やコンテンツをエージェントに渡すと、埋め込まれた指示に従わされる危険があります。これはプロンプトインジェクションと呼ばれ、OWASP Top 10 for LLM Applications で第 1 位のリスクとして位置づけられています。

関連する具体的な事例として、Microsoft のセキュリティブログ(2026-06-05)は、Anthropic の Claude Code GitHub Action におけるプロンプトインジェクションで権限チェックを回避できた脆弱性を報告しています(この脆弱性は短期間で修正済みです)。これは GitHub Action 上での事案であり、CLAUDE.md ファイルそのものが攻撃経路だったという話ではありません。ただし「外部由来のコンテンツをエージェントに渡す」構図が持つリスクを示す事例として参照できます。

不特定多数が公開している CLAUDE.md を、出所を確認せずに取り込むことも同じ構図です。取り込む前に全行を目視でレビューし、自分のスタックに合わないルール・過剰に許可的な指示がないかを確認してください。

取り込んだ後もコードと同じように扱う

公式の Best practices は「CLAUDE.md をコードと同じように扱う」ことを推奨しています。おかしくなったら見直し、定期的に剪定し、実際に挙動が変わるかで効果を検証する。取り込んだ指示がいつの間にか形骸化していることは珍しくありません。

③ CLAUDE.md でやるべきこと / やるべきでないこと — hook・skill との使い分け

CLAUDE.md は「Claude がその通り動こうとする指示」です。公式の原文を引くと「CLAUDE.md instructions shape Claude's behavior but are not a hard enforcement layer」とあります。つまり、CLAUDE.md は「強制設定」ではなく「コンテキスト」です。

この性質から、次の使い分けが導かれます。

CLAUDE.md が適切なもの:

• チームのコーディング規約や命名規則
• プロジェクト固有のアーキテクチャ上の判断
• テストランナーやビルドコマンドの呼び方
• ブランチ名・コミットメッセージの形式
• 開発環境の非自明な設定

hook に移すべきもの:

必ず実行/禁止させたい動作は hook で担保します。公式原文:「To block an action regardless of what Claude decides, use a PreToolUse hook instead」。たとえば「本番データベースへの直接書き込みを絶対に実行させない」といった強制停止は、CLAUDE.md に書いても Claude が判断次第で実行してしまう可能性があります。hook はその判断より前に割り込む仕組みです。

skill に移すべきもの:

たまにしか使わない手順や知識は skill に移します。毎回コンテキストに展開するのではなく、必要なときだけ読み込まれる形にすることで、CLAUDE.md のコンパクトさを維持できます。

ここまでをまとめると、CLAUDE.md は「毎回必要な判断の文脈」を渡す場所であり、「絶対に守らせる強制設定」は hook、「たまに必要な知識」は skill が担います。それぞれの役割を混同すると、CLAUDE.md が肥大化するか、重要なルールが守られないかのどちらかに陥ります。

まとめ

CLAUDE.md を有効に使うための要点は三つです。

一つ目、200 行未満に保つ。肥大化したら .claude/rules/ のパススコープルールに分割し、hook や skill に移せるものは移す。

二つ目、GitHub の他者 CLAUDE.md は「型を借りる」と割り切り、丸ごとコピーしない。取り込む前に全行レビューし、@path インポートの承認ダイアログは内容を確認してから許可する。

三つ目、CLAUDE.md はコンテキストであり強制設定ではない。「絶対に守らせる」ものは hook で担保する。

CLAUDE.md はチームで git 管理して育てるものです。書いた時点での価値よりも、実際の作業で「Claude がミスした」「この指示は効いた」を積み重ねながら剪定し続けることで価値が積み上がります。

出典

• Claude Code 公式 ― How Claude remembers your project(CLAUDE.md / memory): https://code.claude.com/docs/en/memory
• Claude Code 公式 ― Best practices for Claude Code: https://code.claude.com/docs/en/best-practices
• Microsoft Security Blog, "Securing CI/CD in an agentic world: Claude Code GitHub Action case"(2026-06-05): https://www.microsoft.com/en-us/security/blog/2026/06/05/securing-ci-cd-in-agentic-world-claude-code-github-action-case/
• OWASP Top 10 for LLM Applications: https://owasp.org/www-project-top-10-for-large-language-model-applications/