【Claude Code実践入門 第4回】CLAUDE.mdを育てる ― 設定ではなく指示、4つの置き場所、rules・@取り込み・/init、書くこと・書かないこと、守られる書き方、Skills・フックとの役割分担、ひな形

生成AI
スポンサーリンク
スポンサーリンク

「CLAUDE.md にルールを書いたのに、Claude Code が守ってくれないことがあります」
「Claude が間違えるたびにルールを足していたら、CLAUDE.md が長くなる一方です。何を書いて、何を書かないべきでしょうか」

CLAUDE.md は、Claude Code がセッションの開始時に毎回読み込む、プロジェクトのルールを書くファイルです。うまく使えば、毎回同じ説明をしなくて済みます。ただし、書けば書くほど効くわけではありません。短く、具体的に、間違えるたびに直すのがこの回の合言葉です。

第3回では、走らせながら止める・戻す・区切る操作を見ました。第4回では、Claude に毎回伝えておく指示のファイル、CLAUDE.md の置き場所、書くこと・書かないこと、守られる書き方、間違いを直す頼み方、Skills・フックとの役割分担、チームで共有するひな形（筆者の例）を扱います。

CLAUDE.mdは「設定」ではなく「指示」

CLAUDE.md は、セッションの開始時に毎回読み込まれる、プロジェクトのルールを書くファイルです。ここで押さえておきたいのは、CLAUDE.md が強制される設定ではなく、Claude が従おうとする指示だという点です。

短いCLAUDE.md（200行未満）には、タスク名にnameを付ける、変数はgroup_varsに書く、検証はlint → --check、prodには実行しない、の4行が並び「1行ずつが届く」。長いCLAUDE.mdには、ベストプラクティスに従う（灰色）、きれいに書く、IMPORTANT：必ず確認、IMPORTANT：慎重に（灰色）、変数はrolesに書く、変数はgroup_varsに書く、ディレクトリの説明…（灰色）、担当者の一覧…の8行が並び、灰色は守られにくくなった行。すべての行がClaudeの注意を取り合うので、引き締まっているほど多くの行が守られることを示す図

Claude Academy のレッスン「Claudeが従うCLAUDE.md」は、ほぼ全員がはまる落とし穴として、問題が起きるたびにルールを足し、ファイルが大きくなっていくことを挙げています。すべての行が Claude の注意を取り合うため、ファイルが長くなるほど、個々のルールは守られにくくなります。これは Claude の不具合ではなく、この仕組みの性質です。冒頭の1つ目の相談がこれです。

目標は全部を書くことではなく、ファイルを引き締めておくことです。公式の memory のページの目安は、1ファイルあたり200行未満です（”target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.”）。引き締まっているほど、Claude は多くの部分に従います。

  • CLAUDE.md は強制される設定ではなく、Claude が従おうとする指示
  • 長くなるほど、行どうしが注意を取り合い、守られにくくなる
  • 公式の目安は200行未満。引き締まっているほど守られる

なお、コンパクトの後も、プロジェクトのルートの CLAUDE.md はディスクから入れ直されます（第3回の「コンパクトの後に残るもの・消えるもの」）。

4つの置き場所

CLAUDE.md には、置き場所が4種類あります。

種類場所用途
管理ポリシーLinux・WSL：/etc/claude-code/CLAUDE.md、Windows：C:\Program Files\ClaudeCode\CLAUDE.md、macOS：/Library/Application Support/ClaudeCode/CLAUDE.md組織で配る。個人の設定では外せない
ユーザー~/.claude/CLAUDE.md自分の全プロジェクトに効く（連載「Claude活用入門」第4回「共通の指示：調査・事実確認のルール」）
プロジェクト./CLAUDE.md または ./.claude/CLAUDE.mdGit でチームと共有する。この回の最後のひな形はここ
ローカル./CLAUDE.local.md（.gitignore に入れる）このリポジトリだけの自分用のメモ
  • 4つは上書きではなく、すべてつながって読み込まれる（作業フォルダーに近いものほど後ろに来る）
  • サブディレクトリの CLAUDE.md は、Claude がそのディレクトリのファイルを読んだときに読み込まれる

公式の memory のページでは、見つかったファイルはすべて1つにつなげてコンテキストに入れられ、ディレクトリ階層ではファイルシステムのルートから作業フォルダーに向かう順に並ぶと説明されています。macOS の管理ポリシーのパスは、上の表のとおり公式の文書にあります。CLAUDE.local.md は、公式の表では「Local instructions」（プロジェクトごとの個人の設定。.gitignore に追加する）として載っています。

管理ポリシーは組織向けで、個人の Pro・Max で使うのは、ユーザー・プロジェクト・ローカルの3つです。

プロジェクトの指示ファイルは CLAUDE.md だけとは限りません。同じページに、./AGENTS.md が CLAUDE.md の代わり、または一緒に読み込まれる場合を説明する節があり、版の記載（Claude Code v2.1.277 以降）もあります。AGENTS.md を使うリポジトリでは、その節も見てください。

出典は公式の memory のページ（https://code.claude.com/docs/en/memory）です。

分ける・取り込む・確かめる

CLAUDE.md が長くなりそうなときの整理の道具と、読み込まれたかの確かめ方です。

  • ルールを分ける：.claude/rules/ にトピックごとの md を置ける。frontmatter に paths: を書くと、該当するファイルに触れたときだけ読み込まれる（例：roles/** のルールは playbook を編集するときだけ）
  • ファイルを取り込む：@パス で別のファイルを取り込める（4段まで）
  • 取り込みの注意：取り込んだファイルも起動時に全部読み込まれる。整理には役立つが、コンテキストは減らない
  • 読み込まれたか確かめる：/context の Memory files 欄で見る（CLI では /memory でも一覧を見られる。Code タブでは /memory は使えない）
  • メモ書き：ブロック単位の HTML コメント（<!-- -->）は読み込みの前に取り除かれる。人向けのメモに使える
  • 下書きを作る：/init でリポジトリを解析して下書きを作れる。既存の CLAUDE.md は上書きせず、改善案を出す

出典は公式の memory のページと、Claude Academy のレッスン「Claudeが従うCLAUDE.md」です。公式の文書の書き方は、次のとおりです。

  • 取り込み（@path/to/import）：取り込んだファイルは展開されて、それを参照する CLAUDE.md と一緒に起動時にコンテキストへ読み込まれる。取り込んだファイルがさらに別のファイルを取り込む再帰も使え、深さは最大4段（”four hops”）
  • HTML コメント：ブロック単位のコメントはコンテキストに入れる前に取り除かれる。コードブロックの中のコメントは残る
  • 確かめ方：/context を実行して、Memory files の一覧で、起動時に読み込まれるはずの CLAUDE.md・CLAUDE.local.md を確認する。起動時にどの CLAUDE.md とルールのファイルが読み込まれたかも /context で分かる
  • /memory：公式の commands のページでは「CLAUDE.md を編集する、auto memory のオン・オフを切り替える、auto memory の内容を見る」コマンド

/context は、筆者の Code タブでも使えました（2026年10月18日に確認）。/memory は、筆者の Code タブでは「/memory isn’t available in this environment.」と表示され、使えませんでした（同日に確認）。Code タブでは、CLAUDE.md はファイルを開いて直接編集するか、Claude に「CLAUDE.md に追記して」と頼みます。筆者は CLI の claude -p の中で /context を使い、Memory files の欄を確かめています。

/init で下書きを作る（筆者が試したら）

/init は、Claude がコードベースを解析して、ビルドのコマンド・テストの手順・見つけた規約を書いた CLAUDE.md を作るコマンドです。すでに CLAUDE.md がある場合は、上書きせずに改善案を出します。公式の commands のページには、環境変数 CLAUDE_CODE_NEW_INIT=1 を設定すると、スキル・フック・個人のメモのファイルまで案内する対話的な流れになること、OpenAI Codex や Google Gemini CLI の設定を見つけたら /import で引き継ぐことを提案することも書かれています。

筆者が練習用の Ansible のリポジトリ（NTP の参照先を設定する小さな playbook）で /init を試したところ、下書きは37行（英語）でした。ここから書かないこと（次の節）に当たる行を削って、22行にしました。削った行と残した行の一覧、削った後の /context の結果は、第8回の演習の手順1の囲みに載せています。自分の手で試すなら、手順1です。

書くこと・書かないこと

何を CLAUDE.md に書くかの基準は、「Claude が推測できないか」です。

書く書かない
Claude が推測できないコマンド（例：ansible-playbook --check --diff -i inventory/stg site.yml）ファイルを読めば分かること（ディレクトリの構成など）
標準と違う規約（例：変数名は〈role名〉_ で始める）一般的な規約、ベストプラクティス
検証の手順と「完了」の定義製品の詳しいドキュメント（リンクで足りる）
環境の癖（例：Claude Code から ansible 系のコマンドを実行すると、Ansible requires blocking IO で止まることがある。2>&1 | cat を付ける。終了コードは cat の0になるので、成否は PLAY RECAP で判断させる）よく変わる情報（担当者、日付、IP アドレスの一覧）
落とし穴（例：handler の名前を変えると通知が届かない）ファイルごとの説明

書き足すきっかけは、次のいずれかです。

  • 同じ間違いが2回目
  • レビューで指摘された
  • 前回も同じ訂正をした

出典は公式のベストプラクティス（https://code.claude.com/docs/en/best-practices）と memory のページです。

「環境の癖」の例は、筆者が見たものです。Claude Code に ansible-playbook などを実行させると、「Ansible requires blocking IO on stdin/stdout/stderr」と出て終了コード1で止まることがありました。デスクトップアプリの Code タブ（2026-10-04、手元の Linux の ansible-core 2.20.1）と、CLI の claude -p（2026-10-18、ansible-core 2.20.1）の両方で見ており、Code タブだけの癖ではありません（Claude が自分で、出力をファイルに向ける・2>&1 | cat を付けるなどで回避しました。端末から自分で打つときは起きません）。公式の文書や issue には、このメッセージの記述を見つけられませんでした。このように、Claude が推測できない環境の癖は、CLAUDE.md に書く価値のよい例です。

守られる書き方

同じ内容でも、書き方で守られやすさが変わります。

原則守られにくい書き方守られる書き方
具体的で、守れたか確かめられる「Ansibleのベストプラクティスに従う」「すべてのタスクにnameを付け、handlerの名前は Restart 〈サービス名〉 にする」
禁止だけでなく代わりを書く「shellモジュールを使わない」「shellモジュールではなく、専用モジュール（ansible.builtin.lineinfile など）を使う」
強調は予算すべての行に「必ず」「IMPORTANT」破られると本当に困る2〜3個だけに使う
矛盾させない「変数はgroup_varsに書く」と「変数はroleのdefaultsに書く」が両方あるどちらの場合にどちらを使うかを書く

出典は Claude Academy のレッスン「Claudeが従うCLAUDE.md」と、公式の memory のページです。

  • 矛盾する指示があると、Claude がどちらかを勝手に選ぶことがある
  • 強調を控える点は、連載「Claude活用入門」第4回「5.x世代で変わった点」の「強い言い回しは効きすぎる」とも一致する

補足：日本語のタスク名と ansible-lint の name[casing]

ansible-lint の規則 name[casing] は、タスクなどの名前が大文字で始まらないと指摘します（公式の規則のページ：「すべての名前は、大文字のある言語では大文字で始めること」）。ansible-lint 26.1.1・ansible-core 2.20.1 で確かめると、指摘されるのは、名前が英小文字で始まるときでした。「時刻の参照先を設定する」のように日本語の文字で始まる名前は指摘されず、chronyの参照先を設定する のように英小文字の英単語で始まる名前だけが指摘されました。日本語のタスク名でも、英単語で始めるなら name[casing] に引っかかります。

筆者の演習で ansible-lint が指摘したのも、タスク名が chrony で始まる chronyの参照先を設定する でした。/goal でこれを .ansible-lint の skip_list に入れさせたところ、lint は通りましたが、CLAUDE.md への追記までは Claude はしませんでした。「CLAUDE.md に追加して」と頼むのは人の仕事です（次の節）。なお、公式のページは skip_list を「違反が出力から隠れるので勧めない」としています。skip_list に入れるなら、そのことも CLAUDE.md に書いておくようにします。タスク名を日本語の文字で始めるか、英語なら大文字で始めれば、skip_list は要りません。

間違いはCLAUDE.mdのバグとして直す

CLAUDE.md は、一度書いて終わりではなく編集し続けるファイルです。Claude Academy のレッスンは、Claude が間違えたときに手で直して終わりにせず、CLAUDE.md のバグ報告として扱うよう勧めています。「いまの間違いを防ぐルールを、CLAUDE.md に追加して」と頼めば、Claude がルールを書き、問題が起きるたびにファイルが良くなっていきます。

Claudeが間違えた、「CLAUDE.mdに追加して」と頼む、ルールが書かれる、差分を見てコミット、チーム全員に効く、という流れ。「覚えておいて」とだけ頼むと、auto memory（端末ごとのメモ）に書かれることがあり、チームには共有されない。共有したいことは「CLAUDE.mdに」と明示する、ことを示す図

ただし、頼み方に注意が必要です。Claude Code には、Claude が自分でメモを残す auto memory という仕組みがあり、ローカルのセッションでは既定でオンです。「覚えておいて」とだけ頼むと、CLAUDE.md ではなく、端末ごとの auto memory に書かれることがあり、チームには共有されません。共有したいことは「CLAUDE.md に追加して」と明示し、追加された行は差分を見てからコミットします。

  • Claude が間違えたら「CLAUDE.md に追加して」と頼み、ルールを書かせる
  • 「覚えて」だけだと、端末ごとの auto memory に書かれることがある（チームに共有されない）
  • 追加した行も差分を確かめてからコミットする

公式の memory のページの auto memory の節には、次のように書かれています。

  • 「always use pnpm, not npm」「remember that the API tests require a local Redis instance」のように、Claude に何かを覚えるよう頼むと、auto memory に保存される。代わりに CLAUDE.md に追加したいときは、「add this to CLAUDE.md」のように Claude に直接頼むか、/memory（CLI。Code タブでは使えない）から自分でファイルを編集する
  • auto memory はマシンごと。同じ Git リポジトリの worktree とサブディレクトリは1つの auto memory のディレクトリを共有する。ファイルは、マシンやクラウド環境の間では共有されない
  • 保存先はプロジェクトごとに ~/.claude/projects/<project>/memory/
  • オン・オフは、CLI のセッションで /memory を開いて auto memory のトグルで切り替える（ユーザーの設定 ~/.claude/settings.json の autoMemoryEnabled に保存される）。Code タブでは /memory が使えないので、autoMemoryEnabled を直接書く。環境変数で無効にするなら CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

auto memory は、連載「Claude活用入門」第5回「auto memory」でも触れています。

CLAUDE.md・Skills・フックの役割分担

置き場所向いているもの強さ
CLAUDE.mdいつも当てはまる規約（命名、置き場所、検証の手順の要約）指示。たいてい守られる
Skills特定の種類の作業の手順と資料（playbook のレビュー、リリース前の確認）指示。必要なときだけ読み込まれる
フック絶対に飛ばしてはいけないルール（main への push の禁止、本番のインベントリへの実行の確認）コードで強制する。Claude は飛ばせない

出典は Claude Academy のレッスン「検証スキル」「Hooks」と、公式の costs のページ（https://code.claude.com/docs/en/costs）です。

公式は、CLAUDE.md にある専門的な手順は Skill に移し、CLAUDE.md を200行未満に保つよう勧めています。costs のページには、「CLAUDE.md はセッションの開始時にコンテキストへ読み込まれる。PR レビューやデータベースの移行のような特定の作業の詳しい手順が入っていると、関係のない作業のときもそのトークンが載る。Skills は呼び出されたときだけ読み込まれるので、専門的な指示を Skills に移すと基本のコンテキストが小さく保てる。本当に必要なものだけにして、CLAUDE.md を200行未満に収めることを目指す」と書かれています。

Skills・フックの仕組みは、連載「Claude活用入門」第5回「拡張の仕組み」にあります。作り方は、続きの連載「Claude Codeスキル入門」（2026年11月3日から）と「Claude Codeフック入門」（11月28日から）で扱います。フックは、守らせたいことの重さで CLAUDE.md と使い分けます。権限のルールで止める話は第5回・第6回で扱います。

チームで共有するCLAUDE.mdのひな形（筆者の例）

ここまでを組み合わせた、Ansible のリポジトリ向けのひな形です。公式の推奨ではなく、筆者の例です。リポジトリのルートの CLAUDE.md に置き、Git で共有します。

# 〇〇システム 構成管理
## 目的と範囲
- 〇〇システムのAnsibleによる構成管理。対象は inventory/stg と inventory/prod
## よく使うコマンド（この順番で書く）
- 静的検査：ansible-lint 2>&1 | cat
- 構文確認：ansible-playbook --syntax-check -i inventory/stg site.yml 2>&1 | cat
- 差分確認：ansible-playbook --check --diff -i inventory/stg site.yml 2>&1 | cat
## 規約（標準と違うものだけ）
- 変数名は <role名>_ で始め、group_vars に書く
- shell モジュールではなく、専用モジュールを使う
## 完了の定義
- ansible-lint の指摘が0件。--check --diff の結果を貼って報告する
## してはいけないこと
- inventory/prod への実行はしない。コマンドを示して人に頼む
## 環境の癖
- ansible 系のコマンドは末尾に 2>&1 | cat を付ける（付けないと「Ansible requires blocking IO」のエラーで止まることがある）
- パイプを付けると終了コードは cat の 0 になる。成否は PLAY RECAP の failed=0・unreachable=0 で判断する
- stg へは踏み台 bastion-stg を経由する（~/.ssh/config に設定済み）
  • 見出しの並びは、前の節の基準のとおり。コマンド・標準と違う規約・完了の定義・してはいけないこと・環境の癖・落とし穴を書き、読めば分かることは書かない
  • 「よく使うコマンド」は、検証の順番（静的検査 → 構文確認 → 差分確認）に並べる
  • すべてを 2>&1 | cat で終わらせているのは、前の節の「環境の癖」のため

環境の癖の説明です。Claude Code から ansible-playbook などを実行すると、「Ansible requires blocking IO on stdin/stdout/stderr」で終了コード1になることがありました（筆者が2026-10-04に Code タブで、2026-10-18に CLI の claude -p で確認。手元の Linux の ansible-core 2.20.1）。2>&1 | cat を付けると正常に動きます。ただし、終了コードは cat のもの（0）になるため、成否は出力（PLAY RECAP）で判断させます。原因は、Claude Code がコマンドの標準出力・標準エラーをノンブロッキングの状態で渡すため、と筆者は考えていますが、公式の文書では確かめられていません。

考えてみよう

  1. 手元の CLAUDE.md（なければ /init の下書き）は何行ありますか。ファイルを読めば分かること、一般的な規約、担当者や IP アドレスの一覧など、書かないことに当たる行はどれでしょうか。
  2. 「ベストプラクティスに従う」のような守られにくい行が、自分の CLAUDE.md にありませんか。「具体的で、守れたか確かめられる」書き方に直すと、どうなりますか。
  3. Claude が同じ間違いを2回したとき、「覚えておいて」と頼むのと「CLAUDE.md に追加して」と頼むのとで、何が変わりますか。
  4. 「main への push の禁止」は、CLAUDE.md・Skills・フックのどれに書きますか。

ヒント：「書くこと・書かないこと」「間違いはCLAUDE.mdのバグとして直す」「CLAUDE.md・Skills・フックの役割分担」の節を見直してください。

まとめ

  • CLAUDE.md は強制される設定ではなく、Claude が従おうとする指示。長くなるほど守られにくいので、200行未満に引き締める
  • 置き場所は4種類（管理ポリシー・ユーザー・プロジェクト・ローカル）。上書きではなくすべてつながって読み込まれる
  • 分ける（.claude/rules/）・取り込む（@パス、ただしコンテキストは減らない）・確かめる（/context。/memory は CLI だけ）。下書きは /init
  • 書くのは推測できないこと（コマンド・標準と違う規約・完了の定義・環境の癖・落とし穴）。守られる書き方は、具体的、代わりも書く、強調は予算、矛盾させない
  • 間違いは「CLAUDE.md に追加して」と頼んで直す。「覚えて」だけだと auto memory に書かれ、チームに共有されない
  • 絶対に飛ばせないルールは CLAUDE.md ではなくフックで強制し、特定の作業の手順は Skills に移す

この回の内容は、第8回の演習の手順1（/init の下書きから書かないことを削る）で試せます。

次回は、権限モードと auto mode を扱います。Claude が確認なしに進める範囲を、どう選ぶかを見ていきます。

連載「Claude Code実践入門」全9回

  1. 任せる前に知っておくこと
  2. 作業範囲を決める
  3. 走らせながら操縦する
  4. CLAUDE.mdを育てる（この記事）
  5. 権限モードとauto mode
  6. allow・ask・denyのルールと設定ファイル
  7. 検証で終わらせる
  8. 演習（前編）：準備から実装と検証まで
  9. 演習（後編）：巻き戻し・差分・権限と振り返り

コメント

タイトルとURLをコピーしました