CLAUDE.md の書き方と育て方 — 60行で出力品質を最大化する設計パターン集

CLAUDE.md が長いほど、Claude は言うことを聞かなくなる

Claude Code を使い始めた多くのエンジニアが最初にやること――それは CLAUDE.md にルールを山ほど書き込むことです。コーディング規約、コミットメッセージの形式、テストの書き方、ディレクトリ構成の説明……。気づけば 300 行を超える「プロジェクトの取扱説明書」が完成しています。

しかし、CLAUDE.md が長いほど Claude の遵守率は下がるという事実をご存知でしょうか。

公式ドキュメントによれば、思考モデル（Thinking LLMs）が合理的に従えるのは 約 150〜200 個の指示までです。さらに Claude Code 自体のシステムプロンプトが約 50 個の指示枠を消費するため、CLAUDE.md で使える「指示バジェット」は実質 100〜150 個しかありません。

この記事では、「CLAUDE.md を書いているのに Claude が思い通りに動かない」という課題を解決します。筆者が実際に Astro プロジェクトで運用している CLAUDE.md の設計パターンと、失敗から学んだ知見を共有します。特に claude.md 育て方 を探している人向けに、初版を書いて終わりではなく、違反が出たルールをどう育て直すかまで扱います。

Claude Code 全体の導入順や、CLAUDE.md を Hooks / Auto Mode とどう分担させるべきかを先に掴みたい方は、Claude Code 実践ガイドを起点に読むのが近道です。設定を「文章で伝える領域」と「機械的に強制する領域」に分ける感覚が先に入っていると、この記事の判断基準も腹落ちしやすくなります。

この記事で解決する課題

「CLAUDE.md にルールを書いているのに、Claude が無視する/矛盾した出力をする」 — この問題の根本原因と対策を、実践的なパターンとして体系化します。

筆者のポジションを先に明確にしておくと、CLAUDE.md は「短ければ短いほど良い」 です。60 行以下、できれば 40 行程度が理想。それ以上書く必要がある場合は、CLAUDE.md ではなく Skills や Hooks に分離すべきです。

パターン1: 「引き算」の設計思想

よくある誤解: 多く書けば賢くなる

CLAUDE.md を見かけるたびに感じるのが、「Claude が既に知っていること」を繰り返し書いているパターンの多さです。

# NG例: Claude が既に知っていることを書いている

- 変数名はキャメルケースにすること
- インデントはスペース2つ
- 関数は小さく保つこと
- コメントは英語で書くこと
- DRY原則に従うこと

これらは Claude がデフォルトで推論できるルールです。CLAUDE.md に書いても「指示バジェット」を消費するだけで、遵守率の向上にはほぼ貢献しません。

判断基準: 「この行がなかったら Claude は間違えるか？」

CLAUDE.md の各行に対して、この問いを投げかけてください。答えが No なら、その行は削除すべきです。

筆者のプロジェクトでは、以下のような「Claude が推測できない情報」だけを残しています:

# OK例: Claude が推測できない情報

- パッケージマネージャは pnpm（npm/yarn ではない）
- slug は frontmatter に手動記載（ランダム英数字12桁）
- 読了時間は日本語対応で約500文字/分で算出

実体験: 以前、200行超の CLAUDE.md を運用していたとき、「pnpm を使え」という指示が他のルールに埋もれて、Claude が npm install を実行してしまうことがありました。CLAUDE.md を 45 行に削減した結果、pnpm の使用率は体感 100% になりました。

パターン2: WHAT / WHY / HOW の 3 層構造

効果的な CLAUDE.md は、以下の 3 つの視点で構成します:

# WHAT: プロジェクトの正体

Astro 5 による静的サイト生成（SSG）。
ポートフォリオ + ブログ + お問い合わせの構成。

# WHY: なぜこの構成か（Claude が判断に使う文脈）

パフォーマンスとSEOを最優先。クライアントサイドJSは最小限。

# HOW: 具体的な作業ルール

pnpm run dev # 開発サーバー
pnpm run build # 本番ビルド

なぜこの構造が有効なのか？ Claude はタスクを受け取ると、まず「このプロジェクトで何が求められているか」を理解し、次に「なぜそのルールがあるか」から制約を推論し、最後に「どう実行するか」を決定します。WHY 層があると、明示されていないケースでも Claude が適切に判断できます。

たとえば、WHY に「クライアントサイド JS は最小限」と書いておくと、新しいコンポーネントを作る際に Claude が自主的に client:load を避け、静的レンダリングを選択するようになります。

パターン3: CLAUDE.md vs Hooks — 判断フロー

ここが他の記事が見落としているポイントです。CLAUDE.md は「助言」であり、Claude が従うのは約 80% の確率です。一方、Hooks は「強制」であり、100% 実行されます。

判断フローは以下のとおりです:

そのルールに Claude が違反したら、実害があるか？
├─ Yes → Hooks にする
│   例: ESLint の自動実行、マイグレーションフォルダへの書き込み禁止
└─ No → CLAUDE.md に書く
    例: コミットメッセージの形式、テストの優先順位

Hooks の実例

筆者が実際に使っている Hook を紹介します。ファイル編集後に自動で Prettier を実行する PostToolUse Hook です:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hook": "cd /path/to/project && pnpm run format --write {{filePath}} 2>/dev/null || true"
      }
    ]
  }
}

これを CLAUDE.md に「Prettier で整形すること」と書くだけだと、Claude が忘れるケースが約 20% 発生します。Hook にしてからは 0% です。

重要な知見: CLAUDE.md に書いていたルールのうち、3 回以上違反が発生したものは、Hook に移行するべきです。CLAUDE.md は「違反しても致命的でないルール」の置き場所と割り切りましょう。

Hook の書き方や、PreToolUse / PostToolUse / Stop の実務での使い分けをコード付きで確認したいなら、Claude Code Hooks の使い方実践ガイドがそのまま次の一歩になります。逆に「承認プロンプトをどこまで自動化してよいか」を詰めたい場合は、Claude Code Auto Mode 徹底解説も併読すると、CLAUDE.md と権限設計の境界が整理しやすいです。

パターン4: プログレッシブ・ディスクロージャー

CLAUDE.md に全てを詰め込む代わりに、必要なときだけ読み込まれる仕組みを活用します。

Skills による分離

Claude Code の Skills 機能を使えば、ドメイン知識をオンデマンドで読み込めます:

# .claude/skills/blog-writing/SKILL.md

---

name: blog-writing
description: ブログ記事の執筆ルールとSEO設定

---

# ブログ記事ルール

- slug はランダム英数字12桁
- frontmatter: title, slug, date, emoji, type, topics, excerpt
- type: tech | idea | business | study | career | life
- 3000〜5000文字程度
- ターゲットキーワードをtitle・H2・冒頭100文字に含める

ブログ記事の執筆時だけ自動的に読み込まれ、通常のコーディング作業ではコンテキストを消費しません。

@import による参照

CLAUDE.md から外部ファイルを参照する @ 構文も有効です:

# CLAUDE.md（本体は 30 行程度）

See @README.md for project overview.
See @package.json for available commands.

これにより、CLAUDE.md 自体は最小限に保ちつつ、Claude が必要に応じて詳細情報を取得できます。

パターン5: コンパクション戦略

長時間のセッションでは、Claude が自動的にコンテキストを要約（コンパクション）します。このとき、何を保持し何を捨てるかを CLAUDE.md で制御できることはあまり知られていません。

# CLAUDE.md に追記

When compacting, always preserve:

- The full list of modified files
- All test commands and their results
- Current branch name and PR context

この指示があるとないとでは、長いコーディングセッション後の出力品質に大きな差が出ます。特に「修正したファイル一覧を忘れてコミットが不完全になる」という問題が劇的に減りました。

実例公開: 筆者の Astro プロジェクト CLAUDE.md

最後に、筆者が実際に運用している CLAUDE.md の構造を公開します（45 行）:

# CLAUDE.md

## プロジェクト概要

nidoneko のポートフォリオサイト兼ブログ。Astro 5 SSG。
パフォーマンスとSEOを最優先。クライアントJSは最小限。

## コマンド

pnpm run dev # 開発サーバー
pnpm run build # 本番ビルド
pnpm run format # Prettier 整形

## アーキテクチャ

- Astro 5 + TypeScript strict + CSS カスタムプロパティ
- Content Layer API（src/content.config.ts）で blog コレクション管理
- slug は frontmatter に手動記載（ランダム英数字12桁）

## 規約

- テストフレームワーク・リンター未導入。パッケージマネージャは pnpm
- lang="en"、インデント2スペース
- Prettier + prettier-plugin-astro

## ブログ記事追加

1. src/content/blog/ に Markdown 作成
2. frontmatter: title, slug, date, emoji, type, topics, excerpt
3. type: tech | idea | business | study | career | life

ポイントは以下の 3 つです:

45 行以下: 指示バジェットの消費を最小化
Claude が推測できない情報のみ: pnpm、slug の生成ルール、Content Layer API の使用
WHY の明示: 「パフォーマンスと SEO を最優先」で、Claude の判断基準を提供

まとめ: CLAUDE.md 設計の 5 原則

引き算で設計する: 各行に「これがなかったら Claude は間違えるか？」を問う
WHAT / WHY / HOW で構造化: 特に WHY が Claude の自律判断を支える
80% ルールは CLAUDE.md、100% ルールは Hooks: 違反の実害で判断する
プログレッシブ・ディスクロージャー: Skills と @import で必要な情報だけ読み込む
コンパクション戦略を入れる: 長時間セッションでの品質低下を防ぐ

CLAUDE.md は「書いて終わり」ではなく、コードと同じように継続的にリファクタリングするものです。Claude の出力が期待と異なるとき、まず CLAUDE.md を疑ってみてください。たいていの場合、問題は「ルールが足りない」のではなく「ルールが多すぎる」ことにあります。

次に読む順番としては、全体像を押さえるなら Claude Code 実践ガイド、強制力のある自動化に進むなら Claude Code Hooks の使い方実践ガイド、権限承認の摩擦を減らしたいなら Claude Code Auto Mode 徹底解説がおすすめです。