Claude Codeを使っていて、こんな経験はありませんか。
- 「
any型は使わないで」と毎回書いているのに、平気でanyを使ってくる - 「mainに直接コミットしないで」と言ったのに、いつの間にかmainにコミットされている
- 同じミスを何度も指摘していて、毎回同じ説明をし直している
-
CLAUDE.mdは書いてあるのに、肝心なところでルールが無視される
これ、モデルが言うことを聞かないわけでも、賢くないわけでもありません。原因のほとんどは「ルールの書き方が曖昧だから」です。
ある調査では、具体的に書かれたルールの遵守率は89%、曖昧なルールの遵守率は35% という差が出ています。同じ CLAUDE.md でも、書き方ひとつで言うことを聞く確率が2.5倍変わるということです。
この記事では、Claude Codeが実際にルールを守るようになる CLAUDE.md の設計方法を、Before/Afterの具体例つきで紹介します。すべてコピペして今日から試せます。
そもそも CLAUDE.md とは「AIへのオンボーディング文書」
まず前提を整えます。多くの人は CLAUDE.md を「人間向けのREADME」のように書いてしまいます。これが間違いの出発点です。
CLAUDE.md は、新しく入ったチームメンバー（=AI）に渡すオンボーディング文書です。読む相手は人間ではなくClaude Codeなので、
- 「察してほしい」前提は通用しない
- 抽象的な精神論（「クリーンに書く」）は判断基準にならない
- 具体的なコマンド・パス・禁止事項を明示する必要がある
という発想で書く必要があります。ここを切り替えるだけで、書く内容が大きく変わります。
原因：曖昧なルールはAIに「解釈の余地」を与えてしまう
Claude Codeは指示が曖昧だと、自分にとって都合のいい（=最短で終わる）解釈を選びます。これは悪意ではなく、判断基準が示されていないからです。
| ❌ 無視されやすい（曖昧） | ✅ 守られやすい（具体的） |
|---|---|
| 「クリーンなコードを書く」 | 「変数は camelCase、Reactコンポーネントは PascalCase」 |
| 「ちゃんとテストする」 | 「変更後に毎回 npm test を実行。utils/ は80%カバレッジ必須」 |
| 「TypeScriptを使う」 | 「strict mode 必須。any 型の使用禁止」 |
| 「gitに気をつける」 | 「タスクごとに新ブランチ。mainへの直接コミット禁止」 |
左側はすべて「正しいこと」を言っていますが、AIが従ったかどうかを検証できません。検証できないルールは、守られているか確認しようがないので、実質的に機能しません。
ポイントは「そのルールを守ったか/破ったかを、第三者が機械的に判定できるか」です。判定できないなら、それはまだルールになっていません。
解決策1：WHAT / WHY / HOW フレームワークで構造化する
何をどう書けばいいか迷ったら、CLAUDE.md を3つのブロックに分けます。
# myapp CLAUDE.md
## WHAT（何を作っているか）
- プロジェクト：B2B向けの請求管理SaaS
- スタック：React 18.3 + TypeScript 5.4 + Vite 5 + Prisma 5.2
- 構造：src/components/, src/api/, src/utils/, tests/
- 重要ファイル：src/middleware/auth.ts（認証ロジック。変更前に必ず読む）
## WHY（守るべきルールと理由）
- 変数は camelCase、Reactコンポーネントは PascalCase
- MUST use TypeScript strict mode. MUST NOT use `any` type
- NEVER commit to main directly. Always create a feature branch
- Conventional Commits: feat:, fix:, refactor:, docs:
## HOW（どう動かすか）
- Build: `npm run build`
- Test: `npm test` — コード変更のたびに実行する
- Lint: `eslint . --fix` — コミット前に毎回実行する
- PR: 作業完了時に `gh pr create`
ここで効くテクニックが2つあります。
1. バージョン番号まで書く
「Reactを使う」ではなく「React 18.3」と書きます。バージョンを書かないと、AIは古い書き方や新しすぎる書き方を混ぜてきます。
2. 強制語彙 MUST / NEVER / ALWAYS を使う
英語の強い命令語を使うと遵守率が上がります。「使わないでほしい」より「MUST NOT use」のほうが、AIにとってルールの強度が明確に伝わります。
解決策2：5つのスコープを使い分ける（後勝ちルール）
CLAUDE.md は1つではありません。配置場所によって役割とスコープが変わり、より深い階層が上位を上書きします（後勝ち）。
| スコープ | パス | 用途 | Git管理 |
|---|---|---|---|
| グローバル | ~/.claude/CLAUDE.md |
個人の全プロジェクト共通デフォルト | しない |
| プロジェクトルート | ./CLAUDE.md |
プロジェクト共通ルール | する |
| ローカル秘密 | ./CLAUDE.local.md |
個人メモ・機密パス | .gitignore |
| フォルダ | ./src/CLAUDE.md |
モジュール固有ルール（遅延読み込み） | する |
| サブエージェント | ./AGENTS.md |
マルチエージェント・他ツール横断用 | する |
例えば「API実装のときだけ守ってほしいルール」を全体の CLAUDE.md に書くと、無関係なフロント作業のときにもトークンを消費し、ノイズになります。代わりに src/api/CLAUDE.md に置けば、その配下を触るときだけ遅延読み込みされます。
機密情報（本番DBのパスやAPIキーのありか）は CLAUDE.local.md に書いて .gitignore に登録します。チームのルールと個人のメモが混ざらず、誤ってコミットする事故も防げます。
解決策3：肥大化させない（200行・2,000トークンが目安）
「ルールは多いほど守られる」と思いがちですが、逆です。CLAUDE.md が長くなりすぎると、重要なルールが埋もれてスキップされます。
| 指標 | 推奨値 | 超えたときの対処 |
|---|---|---|
| 行数 | 200行以下 |
@imports で分割 |
| トークン | 2,000以下 | 優先度の低いルールを削る |
| セクション数 | 3〜5 | WHAT/WHY/HOW に絞る |
参考までに、Claude Code作者のBoris Cherny氏の CLAUDE.md は約100行・2,500トークン程度と紹介されています。「全部書く」ではなく「効くものだけ残す」が正解です。
長くなってきたら @imports でファイルを分割します。
# CLAUDE.md（ルート）
@.claude/rules/git-conventions.md
@.claude/rules/security-rules.md
@docs/architecture.md
ルートをスリムに保ちつつ、ルールごとにファイルを分けて他プロジェクトでも再利用できます。
解決策4：Compound Engineering ループで「二度と同じミスをさせない」
ここが CLAUDE.md 運用の一番おいしい部分です。
PRレビューやコードレビューでClaude Codeのミスを見つけたら、感情的に指摘し直すのではなく、そのミスを具体的なルールとして CLAUDE.md に1行追記するだけにします。
PRレビューでClaudeのミスを発見
↓
そのミスを「具体的なルール」として CLAUDE.md に追記
↓
同じミスが二度と繰り返されない
↓
1ヶ月後：よくあるミスが消える
3ヶ月後：CLAUDE.md = チームの暗黙知の文書化
たとえば「日付処理でタイムゾーンを考慮し忘れる」ミスがあったら、
## 日付処理
- 日付は MUST すべて UTC で保存する
- 表示時のみ `formatInTimeZone` でローカル変換する（src/utils/date.ts を使う）
と追記します。これを繰り返すと、CLAUDE.md が**「このプロジェクトで二度と踏みたくない地雷リスト」**として自動的に育っていきます。指摘するたびに賢くなる仕組みなので、運用するほど指示出しが楽になります。
CLAUDE.md だけで足りないところを補う3つの仲間
CLAUDE.md は「常に効いている土台ルール」ですが、これだけでは届かない領域があります。実務では次の3つと組み合わせると効果が跳ね上がります。
1. 個別タスクは「アジャイルチケット型」で渡す
CLAUDE.md に書くのは普遍的なルール。一方、その都度のタスクは Context / To-dos / Not-to-dos / Acceptance Criteria の4ブロックで渡すと、スコープ外の改変を止められます。
## Context
JWTリフレッシュトークンを実装する。src/auth/session.ts のパターンに従う。
## To-dos
- POST /auth/refresh を追加
- アクセストークンの有効期限は15分
## Not-to-dos
- src/auth/oauth.ts は変更しない（別PRで対応）
- 独自の暗号化を書かない（jsonwebtokenを使う）
## Acceptance Criteria
- [ ] npm test -- --grep "jwt refresh" が通る
- [ ] 期限切れトークンが401を返す
特に効くのが Not-to-dos です。これがないとAIはスコープ外のファイルを勝手に「改善」してしまいます。
2. 実装は PIV（Plan → Implement → Verify）ループで進める
いきなり実装させず、(1) 計画だけ立てさせて承認 → (2) 承認した計画だけ実装 → (3) テストで検証、と3フェーズに分けます。「計画が良ければコードも良い」ので、計画と実行を分離するだけで誤実装が激減します。
3. コミットは「1タスク=1セーブポイント」で刻む
AIは高速かつ広範囲にコードを変えるため、まとめてコミットすると問題発覚時の巻き戻しコストが跳ね上がります。タスク完了ごとに Conventional Commits 形式で即コミットしておけば、いつでも安全に戻せます。
git add src/auth/jwt.ts tests/auth/jwt.test.ts
git commit -m "feat(auth): JWTリフレッシュトークンのローテーション実装"
この4つ（CLAUDE.md設計 / アジャイルプロンプト / PIVループ / コミット戦略）が噛み合うと、「プロのClaude Code開発1周分」のワークフローになります。
まとめ：今日からできる5ステップ
-
CLAUDE.mdを「READMEではなくAIへのオンボーディング文書」として捉え直す - 曖昧なルールを「機械的に検証できる具体ルール」に書き換える（
MUST/NEVERを使う） - WHAT/WHY/HOW で構造化し、200行・2,000トークン以内に収める
- モジュール固有ルールはフォルダ別
CLAUDE.mdに逃がす - レビューで見つけたミスを毎回1行ずつ追記して育てる（Compound Engineering）
「Claude Codeが言うことを聞かない」と感じたら、まずプロンプトを疑う前に CLAUDE.md を疑ってみてください。多くの場合、モデルではなく設定の問題です。
おまけ：4つの型をまとめた無料スキル集を公開しています
この記事で触れた CLAUDE.md設計 / アジャイルチケット型プロンプト / PIV開発ループ / AIコミット戦略 の4つを、そのまま自分のプロジェクトにコピーして使える形（手順・プロンプト例・アンチパターンつき）でGitHubに無料公開しています。ライセンスは CC BY 4.0 で、商用利用も改変も自由です。
👉 claude-code-skills-starter（GitHub）
git clone https://github.com/noguso245-jpg/claude-code-skills-starter
cp claude-code-skills-starter/skills/ja/claude-md-architecture.md your-project/.claude/skills/
4本はそれぞれ単体で実用でき、組み合わせると「計画→実装→検証→コミット→CLAUDE.mdで統治」という1つの開発ループになります。
役に立ったら、リポジトリに ⭐ をいただけると新しい無料スキルを追加する励みになります。記事への質問・「次はこのテーマを掘ってほしい」という要望もコメントで歓迎です。