CLAUDE.mdとは？rulesとの違い・書き方まで完全ガイド

CLAUDE.mdとは、Claude Codeがセッション開始時に自動で読み込む「プロジェクトの指示書」となるMarkdownファイルです。ビルドコマンドやコーディング規約を書いておけば、毎回説明しなくても前提を把握した状態で作業が始まります。

Claude Codeを使いはじめて1ヶ月くらい経った頃、「同じ指示を毎回打つの、地味にしんどくない？」と気づきました。

コミットメッセージは日本語で、シークレットはコミット禁止、Pythonはuv使って…。毎セッション説明していた頃が懐かしいです。

それを解決するのがCLAUDE.mdで、書く量が増えてきたら .claude/rules/ という仕組みに分けていきます。

ただ、CLAUDE.mdとrulesは似ているようで役割が違い、SkillsやSubagentsとも線引きが曖昧で、最初は正直「結局どれに何を書けばいいの？」と混乱しました。

結論はこうです。CLAUDE.mdは「常に読まれる就業規則」、rulesは「テーマ別に分けられる業務マニュアル」。paths を付けたrulesだけ、該当ファイルを読むときに追加で読み込まれます。

書き方は5原則で足ります——断言形で書く、短くテーマごとに分ける、pathsで自動ロードを絞る、放っておくと間違えることだけ書く、月1で棚卸しする。

CLAUDE.mdの置き場所と読み込み順、コピペで使えるテンプレート、2026年8月にrulesへ分けてから運用してたどり着いたこの5原則に加えて、Python/Git/セキュリティ向けにそのまま使えるrulesテンプレート3種と、rulesが効かないときのチェックリストも実例つきで置いておきます。

読み終わる頃には、自分のプロジェクトに最初の1ファイルを置けるはずです。

CLAUDE.mdとは？書き方の前に押さえる基本

rulesの前に、まずCLAUDE.md自体の役割を確認しておきます。

CLAUDE.mdとは、Claude Codeがセッション開始時に自動で読み込む、プロジェクトの文脈をまとめたMarkdownファイルです。アーキテクチャの説明、コーディング規約、頻繁に使うコマンドなど、毎回説明するのが面倒な情報を先に書いておけます。

Claude Codeが起動時に自動で読み込む仕組み

Claude CodeはプロジェクトルートのCLAUDE.mdを起動時に検出し、会話の最初のユーザーメッセージとしてコンテキストに注入します。特別な設定は不要で、ファイルを置くだけで有効になります。プロジェクトの構造やルールを、まるでAIの手元にあるユーザーマニュアルのように使える仕組みです。

なぜ毎回同じ説明を繰り返さずに済むのか

CLAUDE.mdが無い状態だと、「any型を使わないでください」と伝えても次のセッションでまた同じ指摘が必要になります。CLAUDE.mdに書いておけば、Claudeは最初から型安全なコードを提案するようになります。一度書けば、以降のセッションすべてに効いてくるのが最大の利点です。

よく比べられるREADME.mdは「人間向けの説明書」、CLAUDE.mdは「Claude向けの作業指示書」と読み手が違います。両者の書き分けを実際のリポジトリで見直した経緯はCLAUDE.mdとrulesとREADMEを見直した話にまとめています。

CLAUDE.mdの書き方は/initコマンドが最速

手書きで一から書くよりも、まずは自動生成から始めるほうが早く形になります。

ゼロから手書きする必要はありません。Claude Codeには、プロジェクトを解析してCLAUDE.mdの雛形を自動生成する/initコマンドが用意されています。

自動生成される内容と、生成後に手直しすべきポイント

/initを実行すると、プロジェクトタイプ・ディレクトリ構成・技術スタック・ビルドツールなどを自動検出してCLAUDE.mdに書き出します。まずはこれを土台にするのが手っ取り早い進め方です。すでにCLAUDE.mdがある場合は上書きせず改善案を提示してくれるので、既存プロジェクトで実行しても安心です。環境変数 CLAUDE_CODE_NEW_INIT=1 を設定してから実行すると、CLAUDE.mdに加えてSkillsやHooksも含めて質問しながら組み立てる対話型のフローになります。

自動生成された内容をそのまま使うのはおすすめしません。「componentsフォルダにコンポーネントを置く」のような一般的な情報は、Claudeがすでに知っている場合が多く不要です。プロジェクト固有の「変わった部分」だけを残し、あとは削るくらいの気持ちで手直ししてください。

CLAUDE.mdには何を書くべき？WHAT・WHY・HOWの3視点

何を書けばよいか迷ったら、WHAT・WHY・HOWの3視点で整理すると過不足なくまとまります。

WHYを書いておくと、予期しない判断が必要な場面でもClaudeが適切に対応しやすくなります。「何」だけでなく「なぜ」まで伝えるのがコツです。

検証手段・完了条件も書いておく

CLAUDE.mdには、変更が正しいかどうかを機械的に確認できる検証手段も書いておくと効果的です。「コードを変更したらテストを実行する」「型チェックを必ず通す」のように具体的に指示しておかないと、AIは何をもって作業完了とすべきかの基準を持てません。

HOWのセクションにlint・型チェック・単体テストの実行コマンドを含めておけば、コマンド集としての役割と検証手段の指示を同時に満たせます。

強調語（IMPORTANT・YOU MUST）は数行だけに絞る

絶対に守ってほしいルールには、IMPORTANT（重要）やYOU MUST（必ず行う）のような強調語を付けると、通常の説明文と区別しやすくなります。ただし、すべての行を強調すると効果が薄れるため、本当に譲れない数行だけに絞るのがポイントです。

人間向けのメモはHTMLコメントで残す

CLAUDE.mdの中に <!-- この行を足した経緯 --> のような形で書いたHTMLコメントは、Claudeに渡す前に取り除かれます。ルールを足した理由や担当者へのメモはコメントにしておけば、コンテキストを消費せずにファイルの中に残せます。

ただし、コードブロックの中に書いたコメントは取り除かれず、そのままClaudeに渡ります。

コピペで使えるCLAUDE.mdテンプレート

WHAT・WHY・HOWと検証手段をまとめると、最小構成のCLAUDE.mdは次のような形になります。Python + FastAPIを例にしていますが、見出しはそのままに中身を自分のプロジェクトに置き換えれば使えます。

# プロジェクト概要（WHAT）
- Python 3.12 + FastAPI のWeb API。依存管理は uv
- `src/api/` にエンドポイント、`src/core/` に共通処理を置く

# 設計方針（WHY）
- DBアクセスは必ず `src/core/db.py` 経由にする（接続管理を1か所に集約するため）

# よく使うコマンド（HOW）
- テスト: `uv run pytest`
- リント: `uv run ruff check .`

# 作業ルール
- コードを変更したら、完了報告の前にテストとリントを実行する
- IMPORTANT: `.env` やAPIキーを含むファイルはコミットしない

# 詳細ルール
- Git運用 @docs/git-workflow.md

最後の @docs/git-workflow.md は、別ファイルを読み込ませるインポート記法です（詳しくは後述の「@インポートで分割する」を参照）。最初はこの程度の30行未満から始め、Claudeに同じ指摘を2回したら1行足す、くらいのペースで育てると肥大化しません。

CLAUDE.md書き方の実例｜運営リポジトリの構成

理屈だけでは伝わりにくい部分もあるため、このブログの自動化スクリプト群を管理するリポジトリで、実際に使っているCLAUDE.mdの構成を紹介します。

• 作業ベースディレクトリ
• アーキテクチャの概要
• 行動原則（共通モジュールを使う・秘密情報をコミットしない等）
• テスト・リントの実行コマンド

個別ルールは.claude/rules/配下に分割し、secrets-safety.mdのような常時参照すべきものと、該当パスを操作するときだけ読み込まれるものを分けています。

このCLAUDE.mdは2026年10月時点で75行です（9月は60行でした）。「最初は30行程度」という目安からは増えていますが、公式が推奨する200行以内には収まっています。

Claude Codeのrulesとは｜1分でわかる結論

Claude Code rulesとは、Claudeに守らせたいプロジェクト固有の約束事を書いたMarkdownファイル群のことです。

.claude/rules/ ディレクトリに置くのが標準で、CLAUDE.mdを補完する形で動きます。

結論の比喩をもう少し具体的にすると、こうなります。

読み込みタイミングで言うと、CLAUDE.mdは起動ディレクトリと親ディレクトリにあるものがセッション開始時に読まれます。rulesは、paths を指定しなければ同じく起動時に読み込まれ、指定した場合だけ一致するファイルを読んだタイミングで読み込まれます。

rulesに書くのは「約束事」

rulesに書く内容は、コーディング規約・命名規則・禁止事項・運用フローなど、Claudeが放っておくと忘れたり間違えたりすることが中心です。

たとえば「秘密情報をコミットしない」「決済連携はステージング環境で検証する」など、ミスると痛い系の指示が向いています。テストは通常、隔離したテスト用DBやモックを使い、実DBでの検証が必要な場合だけ対象・権限・復旧手順を明記してください。

ただしrulesはClaudeへの行動指示であり、技術的な強制機構ではありません（詳しくは後述の「Hooksとの違い」を参照）。

逆に「丁寧に書いてください」みたいな抽象的なお願いは、Claudeが判断しにくく、守られにくくなります。

「いつ・何を・どうするか」を検証できる形で、断言形と具体例を使って書くのがコツです。

CLAUDE.md・Skills・Subagentsの違い

Claude Codeには「設定っぽいファイル」が複数あって、最初はマジで混乱します。どの機能から覚えればいいかは、Claude Code学習ロードマップに順番を書いています。

私も最初はCLAUDE.mdとrulesの区別がついていませんでした。役割を一段上から見るとこんな感じです。

CLAUDE.mdとREADME.mdの違い｜rulesとの役割分担

CLAUDE.mdとREADME.md、.claude/rulesの違いと役割分担を、300行超に肥大化したルールを整理し直した体験から紹介。公式準拠のpaths指定の書き方、200行の目安、書く内容・削る内容もまとめます。

AGENTS.mdとの違い

もう一つ紛らわしいのが AGENTS.md です。

これはClaude Code専用の仕組みではなく、複数のAIコーディングツールで使われる指示ファイルです。Claude Code v2.1.277以降は、作業ディレクトリとその上位に CLAUDE.md・CLAUDE.local.md が無ければ AGENTS.md を代わりに読み込みます。両方ある場合、既定では CLAUDE.md だけが読まれ、AGENTS.md は無視されます。

Claude Skillsとは？使い方・作り方と標準スキル一覧を解説

Claude Skillsとは何かを実例つきで解説。仕組み・使い方・作り方に加え、標準スキル一覧やAPI/Web/Claude Codeの実行環境の違いも網羅。導入判断に迷わない完全ガイドです。

Hooksとの違い｜アンチパターン4つ

rules・CLAUDE.mdはどこまでいっても「Claudeへの言葉の指示」であり、Claudeが読んで解釈した上で従うかどうかを判断しています。一方Hooksは、特定のイベント（ファイル編集後・ツール実行前など）で決まったコマンドやスクリプトを確実に発火させる仕組みで、Claudeの判断を介さず機械的に強制できます。

この線引きについて、Anthropic公式ブログ「Steering Claude Code」が、CLAUDE.md・rulesに書くべきでない4つのアンチパターンを具体的に挙げています。

「絶対に守らせたい」と思った時点で、それはrulesではなくhooksの仕事です。

Claude Code hooksの使い方｜主要イベントと設定例・通知音の変え方

Claude Code hooksの使い方を、PreToolUse・PostToolUseなど主要イベントと2026年に増えた拡張イベントで整理して解説。settings.jsonの設定例、hookが動かない時の対処法、通知音をドラクエの効果音に変える実例も紹介します。

rulesとCLAUDE.mdの違いを表で整理

rules・CLAUDE.md・Skillsの違いを一番シンプルに言うと、「いつコンテキストに載るか」が違います。

セッション開始時か、一致するファイルを読むときか、必要だと判断されたときか、の3パターンです。なお、paths のないrulesはセッション開始時に読み込まれます。

読み込まれるタイミングと適用範囲の違い

3つを表にするとこうなります。コンテキスト消費量で並べると、選ぶ基準がはっきりします。

どう使い分けるかの判断フロー

私が普段やっている判断フローはこんな感じです。「常に意識してほしいか？」を最初に問うのがポイントです。

フローチャートにすると、こうなります。

Claude Codeサブエージェントの使い方

Claude Codeサブエージェントの使い方を2026年9月時点の仕様で解説。.claude/agentsでの作り方、YAML設定、呼び出し方、claude agentsコマンドやAgent SDKとの違い、テンプレートまで紹介。

指示ファイルの置き場所と使い分け

指示の置き場所は、共有するプロジェクト用・全プロジェクトに適用する個人用・このプロジェクトだけに適用する個人用に分けて考えると整理しやすくなります。

それぞれ置き場所と使いどころが違うので、まず全体像をマップにしておくとラクです。

プロジェクトルール配置

プロジェクトルールは .claude/rules/ 配下に置くMarkdownファイルです。

Gitで管理してチーム全員に共有するのが基本で、ファイル単位でトピックを分けるのが王道です。

私のリポジトリだと、2026年10月時点でこんな感じで8つに分けています。ブログ記事の規約は、記事のフォルダにだけ効くように paths を付けています。トピックを分けておくと、後から自分が見直すときも見つけやすいです。

.claude/rules/
├── secrets-safety.md          # 秘密情報の取り扱い（常時ロード）
├── browser-automation.md      # Playwright系の規約
├── python-common.md           # Python共通モジュールの使い方
├── launchd.md                 # 定期実行ジョブの規約
├── wp-manager.md              # ブログ管理スクリプトの規約
├── code-rebuild-worldview.md  # このブログの記事の書き方
├── systradefx-articles.md     # もう1つのブログの記事ルール
└── settings.md                # 設定ファイル運用ルール

グローバルルール（~/.claude/）

グローバルルールは ~/.claude/CLAUDE.md または ~/.claude/rules/ に書く、全プロジェクト共通の方針です。

「コメントは日本語」「TDDで進める」みたいな、自分の働き方そのものに関わるルールを置く場所です。

注意点として、グローバル側に書きすぎるとどのプロジェクトでも重く効きすぎて、固有のルールが霞んでしまいます。

私のグローバル側は、コメントの言語やGitの約束事など36行（2026年10月時点）に絞っています。

ローカル指示（CLAUDE.local.md）

自分のマシンだけで使うプロジェクト固有の指示は、プロジェクト直下の CLAUDE.local.md に書きます。

CLAUDE.local.md はGitignoreしておくのが基本です。チームに共有したくない個人の好みやローカル環境の前提を書きます。APIキーなどの秘密情報そのものは書かず、環境変数やシークレット管理サービスで扱ってください。.claude/settings.local.json は、権限などのClaude Code設定をローカルに上書きしたい場合に使います。

CLAUDE.mdの読み込み順と階層構造

CLAUDE.mdは置き場所によってスコープが変わり、公式ドキュメントでは次の4階層が定義されています。上ほど範囲が広く、先に読み込まれます。

ディレクトリ方向の読み込みルールも押さえておくと、モノレポで迷いません。起動したディレクトリとその親ディレクトリにあるCLAUDE.md・CLAUDE.local.mdは起動時にすべて読み込まれ、サブディレクトリにあるものは、Claudeがそのディレクトリのファイルを読んだときに追加で読み込まれます。

他のチームのCLAUDE.mdまで読み込まれてしまう大きなモノレポでは、設定の claudeMdExcludes に除外したいファイルのパスやglobパターンを書くと、そのファイルを読み込まなくなります。自分のマシンだけで除外するなら .claude/settings.local.json に書きます。組織の管理ポリシーのCLAUDE.mdだけは除外できません。

ポイントは、見つかったファイルが上書きではなく連結されることです。ルート側から順に並ぶため、起動ディレクトリに近い指示ほど後から読まれます。同じ階層では CLAUDE.md の後に CLAUDE.local.md が続きます。とはいえ「後に読まれた方が必ず勝つ」わけではないので、矛盾する指示はどちらかに寄せてください。

~/work/app で起動した場合の読み込み順を図にすると、次のようになります。

@インポートで分割する

CLAUDE.mdの中に @docs/git-workflow.md のように書くと、そのファイルの内容も起動時にあわせて読み込まれます。相対パスは作業ディレクトリではなく、インポートを書いたファイルからの相対で解決される点に注意してください。インポート先がさらに別ファイルをインポートすることもでき、最大4階層まで展開されます。

Auto memory（自動メモリ）との使い分け

rulesとよく混同されるのが、Auto memoryと呼ばれる自動記憶の仕組みです。

rulesは人間が明示的に書く固定ルールなのに対し、Auto memoryはClaudeが将来の作業に役立つと判断した情報を自動で記録する仕組みです。すべての会話内容を無条件に保存するわけではありません。保存先は ~/.claude/projects/<project>/memory/ で、索引ファイル MEMORY.md の先頭200行（または25KB）が毎セッション読み込まれます。オン・オフの切り替えや中身の確認は /memory から行えます。

使い分けの目安はシンプルです。

「必ず守らせたい約束事」はrulesに、「毎回思い出してほしい文脈（過去の経緯や好み）」はAuto memoryに任せる、と考えておけば迷いません。

rules・CLAUDE.md・Auto memoryの読み込み方は更新されることがあるため、導入時や挙動に迷ったときはClaude Code公式ドキュメント（Memory）も確認してください。

コンテキストエンジニアリングとは？CLAUDE.mdの実例で解説

コンテキストエンジニアリングとは、AIに渡す情報全体を設計する技術です。プロンプトエンジニアリングとの違いを具体例で比べ、構成要素、Anthropicが示す手法、今日からできる5ステップをClaude Codeの実例つきで解説します。

rulesの基本的な書き方｜5つの原則

rulesの書き方には、効くものと効かないものがハッキリ分かれます。2026年8月にCLAUDE.mdをrulesへ分けてから運用してきて、「これは外せない」と思った5つの原則を紹介します。

原則1：断言形で書く（「なるべく」は禁句）

断言形で書いてください。「なるべく」「できれば」「望ましい」みたいな曖昧表現は、Claudeにとって「やらなくてもいい」と同義になります。

「絶対にしない」「必ず使う」のように、白黒つけて書きましょう。日本語の婉曲表現は、AI相手だと不利に働く場面が多いです。

原則2：短く保ち、テーマごとに分ける

200行以内は、特にセッション開始時に読むCLAUDE.mdの目安です。rulesにも厳密な行数制限はありませんが、長くなればトピックごとに分け、必要ならpathsで対象を絞るとコンテキストのノイズを減らせます。「これ1行消したらClaudeが間違えるか？」を自問して、不要な行は容赦なく削るのもおすすめです。

原則3：pathsで自動ロード制御

paths frontmatterを使うと、一致するパスのファイルをClaudeが読むときだけrulesを追加で読み込ませることができます。

常時ロードを避けてコンテキストを節約できる、地味だけど一番効く機能です。

paths はYAMLリスト（またはカンマ区切りの文字列）で指定します。複数のパターンや、src/**/*.{ts,tsx} のようなbrace expansionも使えます。

読み込まれない場合は、paths のパターンと実際のファイルパスが一致しているかを確認してください。Claude Codeのrulesで使うフィールドは globs ではなく paths です。公式ドキュメント上、Claude Codeがrulesのfrontmatterから読むのは paths だけで、Cursor流の globs などほかのフィールドはエラーにならず黙って無視されます。

---
description: Playwright自動化スクリプトのコーディング規約
paths:
  - python/browser_automation/**/*.py
---

# ブラウザ自動化スクリプト ルール

- setup_context() を使ってコンテキストを生成すること
- time.sleep() ではなく human_delay() を使うこと

原則4：「放っておくと間違える」ことだけ書く

書く内容は「放っておくとClaudeが間違えること」に絞るのがコツです。「変数名はわかりやすく」みたいな当たり前のことは書く必要はありません。

Claudeは元からそれくらいできます。

私の場合、過去のセッションでClaudeにやらかされたことをメモしておいて、再発したらrulesに昇格させる運用にしています。

失敗ドリブンで育てるのが現実的です。

ちなみに、rulesの文面そのものも自分では書いていません。「こういう失敗があったので再発防止のrulesを書いて」とClaudeに指示して下書きさせ、出力された内容を読んで過不足を確認してから採用する運用にしています。断言形になっているか、対象が広すぎないかは、この確認の段階でチェックしています。

原則5：定期的に棚卸しして肥大化を防ぐ

rulesは放置すると確実に肥大化します。月1くらいで棚卸しして、もう要らない指示・重複している指示・抽象的すぎる指示を削るのを習慣にしましょう。

「足す」より「削る」のほうが効果が出やすいです。

棚卸しはClaudeに手伝わせることもできます。Claude Code v2.1.283以降なら、セッション中に /doctor prompt-audit を実行すると、CLAUDE.md・rules・Skillsなどを読んで、古くなった指示、存在しないファイルやコマンドへの参照、互いに矛盾する指示を探し、修正案つきのレポートを出してくれます。レポートの段階ではファイルは書き換わらないので、提案を読んでから採用を決められます。

AI設定あるあるとして、増やせば賢くなる気がしますが、実際は逆で、ノイズが増えると指示の遵守率が落ちます。

すぐ使えるrulesテンプレート3パターン

ここからは、私が実際に使っているテンプレートを3つ紹介します。コピーして自分のプロジェクトに合わせて削っていくのが、一番速い導入方法です。なお、frontmatterの description は人間が見て内容を把握するためのメモであり、Claudeの読み込み判定に使われるのは paths だけです。

Pythonプロジェクト向けテンプレート

Pythonプロジェクトでは、依存管理ツールと共通モジュールの強制が一番効きます。

Claudeは何も言わないと pip install や requirements.txt に流れがちなので、明示しておくと事故が減ります。

---
description: Pythonスクリプトのコーディング規約
paths:
  - "**/*.py"
---

# Python ルール

- 依存管理は uv を使う。requirements.txt は使わない
- 新規スクリプトは common/ の共通モジュールを使う
- 関数には docstring を日本語で書く
- 命名は PEP8 準拠（クラスはPascalCase、関数はsnake_case）

シークレット・安全運用ルール

シークレット系は事故ったときのダメージが大きいため、注意事項をrulesに1ファイル置く価値があります。

ただしrulesだけでは強制できません。秘密ファイルへのアクセス制限は permissions.deny やsandboxで設定し、コミット前の検査はhooksやCIのシークレットスキャンで担保してください。

---
description: 秘密情報・設定ファイル安全ルール
---

# 秘密情報の取り扱い

- .env / config.json / credentials.json は絶対にコミットしない
- 新規設定ファイルを作ったら .example も作る
- ログに秘密情報を出力しない
- ハードコードせず、環境変数か config_manager から読み込む

Git運用・コミットメッセージのルール

Git周りはチームの色が出やすい部分です。

コミットメッセージの言語・プレフィックス・PRの作り方など、好みを明文化しておくと毎回説明する手間が省けます。

---
description: Git操作とコミットメッセージのルール
---

# Git ルール

- コミットメッセージは日本語で書く
- プレフィックスは feat / fix / chore / doc / refactor を使う
- コミット前に pre-commit run --all-files を実行する
- --no-verify は使わない
- main ブランチへの force push は禁止

実運用のrules中身の実例

ここまでのテンプレートはあくまで最小構成です。2026年8月から実際に使っているrulesは、もっと具体的な「型」まで書き込んでいます。参考までに、私のPython用rules（python-common.md）から一部を抜粋します。

---
paths:
  - "python/**/*.py"
  - "python/**/pyproject.toml"
---

# Python共通モジュール利用ルール

## 既存の共通モジュールを必ず使う

新規スクリプト作成・既存スクリプト修正時は、`python/common/` の共通モジュールを
活用し、車輪の再発明を避けること。

### インポートパターン

```python
from pathlib import Path
import sys

_DIR = Path(__file__).parent
sys.path.insert(0, str(_DIR.parent / "common"))

from logger_utils import setup_logger
from discord_notifier import DiscordNotifier
from error_handler import handle_errors
```

### エラーハンドリング

- メイン関数には `@handle_errors("スクリプト名")` デコレータを付ける
- 手動で try/except + 通知処理を書かない（デコレータが自動処理する）

### リトライ

- 指数バックオフ付きのリトライは `retry_utils.py` の `@retry()` を使う
  （`for attempt in range(...)` の手書きループは禁止）

ポイントは、抽象的な「共通モジュールを使ってください」で終わらせず、具体的なインポート文・デコレータ名・禁止する書き方（手書きのtry/exceptやforループ）まで書いていることです。ここまで具体化して初めて、Claudeが毎回同じパターンで書いてくれるようになりました。逆に言うと、自分のプロジェクトでも「Claudeに何度も同じ修正を指摘している」パターンを見つけたら、それがそのままrulesに書くべき具体例になります。

rulesが効かない原因と対処法｜よくある4パターン

「rules書いたのにClaudeが守ってくれない…」というケースは、だいたい4パターンに集約されます。

順にチェックしていけば、ほぼ原因が特定できます。

paths指定とファイル配置のミスマッチ

一番多いのは、paths のglobパターンが実ファイル配置とズレているパターンです。

src/**/*.ts と書いたつもりが、実際は app/src/ 配下だった、みたいなやつです。

paths指定なしのrulesは常時ロードになるので、まずはpathsを外して効くか試してから、効いたらpathsで絞り込むのが安全な手順です。

読み込み経路によってrulesが発火しない

paths付きrulesは、一致するファイルをClaudeが読むことをきっかけにロードされます。Read・Write・Editツールのほか、2026年10月時点の公式ドキュメントでは、Bashの cat・head・tail・sed -n・grep・rg などで1つのファイルを読んだ場合も「読んだ」とみなされ、ロードされます。

気付きにくいので、新しいセッションで対象ファイルを扱った後に /context を実行し、該当ruleが実際に読み込まれたか確認しましょう。継続的に追跡したい場合は、InstructionsLoaded フックを使うと、どのCLAUDE.md・rulesがいつ・なぜ読み込まれたかをログに残せます。

絶対に守る必要があるルールはpaths付きrulesだけに依存せず、常時ロードのCLAUDE.mdまたはrulesに置いたうえで、権限設定・hooks・CIでも技術的に担保するのが安全です。

指示が抽象的すぎて無視されるパターン

「丁寧にコードを書く」「保守性を意識する」みたいな抽象指示は、判断基準が曖昧で守られにくくなります。

Claudeが行動に落とし込みにくく、ほかの具体的な指示に埋もれやすくなるためです。

具体的な動詞と対象を入れて、「〇〇のときは〇〇する」の形にリライトすると効きます。

たとえば「関数が30行を超えたら分割する」のように、判定可能な形にするのがコツです。

CLAUDE.mdとの重複・矛盾を解消する

CLAUDE.mdとrulesで指示が矛盾すると、Claudeがどちらかを任意に選ぶことがあります。優先順への期待に頼らず、同じ内容は1か所に集約してください。

意図せず古いルールが効きっぱなしになることもあります。

定期的に grep で同じキーワードを横断検索して、重複や矛盾を見つけたら片方に寄せるのが運用上のコツです。

よくある質問（FAQ）

Q1. CLAUDE.mdはどのくらいの長さが適切ですか？

A1. 最初は30行程度で十分です。長すぎるCLAUDE.mdは自分でも管理できなくなるため、使っていて何度も言い直すことになった項目だけを、あとから追記していくのがおすすめです。200行を超えてきたら、paths付きのrulesへの分割を検討します。

Q2. CLAUDE.local.mdは使うべきですか？

A2. 非推奨ではなく、現役の機能です。Gitにコミットしたくない個人用の設定（サンドボックスURLやテストデータなど）を書くためのファイルとして、公式ドキュメントでも案内されています。プロジェクトルートに置いて.gitignoreに追加すれば、CLAUDE.mdと一緒に読み込まれます。

Q3. チームで使う場合、誰がCLAUDE.mdを更新すべきですか？

A3. 特定の担当者を決めるより、開発中に「また同じことを説明した」と感じたメンバーがその場で追記するほうが機能します。Gitで管理されているため、変更内容は通常のプルリクエストと同じ流れでレビューできます。

Q4. CLAUDE.mdは日本語と英語どちらで書くべきですか？

A4. どちらでも構いません。Claudeは日本語のCLAUDE.mdも問題なく解釈します。コミットメッセージや普段のやり取りを日本語で統一しているなら、CLAUDE.mdも日本語で書くほうが記述・レビューの両面で扱いやすくなります。私のリポジトリもすべて日本語です。

Q5. CLAUDE.mdが読み込まれているか確認するには？

A5. セッション中に /context を実行し、「Memory files」の一覧に対象のCLAUDE.mdが表示されているかを確認します。/memory を使うと、読み込み対象のCLAUDE.md・CLAUDE.local.mdの一覧からファイルを選んでエディタで開けます。

Q6. rulesとCLAUDE.mdの優先順位は？

A6. 全体に常に効かせたい方針はCLAUDE.md、特定領域だけに効かせたい規約はpaths付きのrulesです。pathsのないrulesもセッション開始時に読まれるため、トピックごとに分割した全体ルールとして使えます。矛盾した指示は優先順に頼らず、どちらか一方に集約しましょう。

Q7. .mdcファイル（Cursor形式）は使える？

A7. Claude Codeは標準で .md を読みます。Cursorの .mdc 形式をそのまま使う必要はなく、frontmatter付きの .md に書き換えるのが素直です。/init は .cursor/rules/ や .cursorrules を読み取り、関連する内容を生成するCLAUDE.mdに取り込んでくれるので、移行の起点に使えます。Cursor互換の運用が必要なら、両方置いて差分を最小化する手もあります。

Q8. rulesは何個まで作っていい？

A8. 個数制限はありません。ただしpathsのないrulesが増えるほど、セッション開始時のコンテキストを消費します。常時必要なものだけを残し、領域固有のルールにはpathsを指定して必要なときだけ読み込む運用が無難です。

Q9. rulesはどこに書けばいい？

A9. プロジェクト固有のルールなら .claude/rules/ 配下、全プロジェクト共通の方針なら ~/.claude/CLAUDE.md または ~/.claude/rules/、自分だけのプロジェクト固有の指示なら CLAUDE.local.md に書きます。.claude/settings.local.json は権限などの設定用です。迷ったら、まずチームで共有したい内容かどうかで判断すると早いです。なお ~/.claude/rules/（ユーザーレベル）はプロジェクトの .claude/rules/ より先に読み込まれますが、どちらかがもう一方を上書きするわけではありません。競合するとClaudeがどちらに従うかは決まらないため、内容をそろえておきましょう。

Q10. rulesが効かないときはどうすればいい？

A10. まずpathsのパターンが実ファイル配置とズレていないか確認します。次に/contextで対象ruleが実際に読み込まれたかを確認します。パイプ付きのBashコマンドや複数ファイルの一括検索で読んだ場合は、paths付きrulesが読み込まれないことがあるためです。そのうえで指示が「丁寧に書く」のような抽象表現になっていないかを見直し、最後にCLAUDE.mdとの重複・矛盾がないかをgrepで横断検索します。

Q11. AGENTS.mdとCLAUDE.mdはどう使い分ける？

A11. Claude Codeだけで使うならCLAUDE.mdで十分です。Codex・Cursor・Gemini CLIなど複数のAIツールを併用するなら、共通ルールをAGENTS.mdにまとめます。CLAUDE.mdが無ければClaude Code（v2.1.277以降）はAGENTS.mdをそのまま読みますが、CLAUDE.mdも置く場合は先頭に @AGENTS.md と書いてインポートしないとAGENTS.mdは読まれません。

Q12. Auto memoryとrulesの違いは？

A12. rulesは人間が明示的に書く固定ルール、Auto memoryはClaudeが将来役立つと判断した情報を自動で記録する仕組みです。「必ず守らせたい約束事」はrulesに、「毎回思い出してほしい文脈」はAuto memoryに任せるのが使い分けの目安です。

まとめ｜rulesは「Claudeとの契約書」として育てる

rulesは一度書いて終わりではなく、Claudeとの付き合いの中で少しずつ育てていく「契約書」みたいなものです。

最初から完璧を目指さず、まずは secrets-safety.md のような注意事項を1ファイル置いてみるのがおすすめです。秘密情報の保護は、rulesに加えて権限設定・hooks・CIでも担保してください。

私自身も8月にrulesへ分けてから、たまに棚卸しして削るたびに「あ、最初から要らなかったな」というルールが出てきます。

それくらいでちょうどよくて、AIの設定は引き算の美学だと最近思っています。明日からあなたのプロジェクトでも、最小の1ファイルから始めてみてください。

途中経過は、また書きます。

※本記事の内容は2026年10月時点のClaude Code仕様に基づきます。rules・CLAUDE.md周りは仕様変更が比較的頻繁なため、最新の挙動は公式ドキュメントも合わせてご確認ください。