Karpathy の 4 CLAUDE.md ルールに 8 追加した「12 ルール版」
— ミス率 41% → 3% の実証データ
2026 年 1 月、Andrej Karpathy が X で「Claude のコード生成の癖」について不満を投稿した。それを Forrest Chang が 4 ルールの CLAUDE.md に整理して GitHub に置いたところ、初日で 5,828 スター、2 週間で 6 万ブックマーク、現在 12 万スター。2026 年最速で伸びた単一ファイル repo になった。
@mnilax はその 4 ルールを 30 codebase × 6 週間でテストし、現代のエージェント時代に合わせた 8 ルールを追加。結果、ミス率 41% → 3%。「CLAUDE.md は wishlist ではなく behavioral contract（行動契約）である」という考え方を、実証データで裏付けた記事。
1. なぜ CLAUDE.md なのか
Anthropic 公式ドキュメントには明記されている: CLAUDE.md は advisory（参考扱い）で、Claude は約 80% の確率で守る。200 行を超えるとコンプライアンスが急落する。
多くの開発者は CLAUDE.md を 3 通りの間違った使い方をしている。
よくある CLAUDE.md の失敗パターン
- 全部入りダンプ: 自分の好みを全部書いて 4,000+ トークンに肥大化 → コンプライアンス 30% まで落ちる
- 完全スキップ: 毎回プロンプトに直書き → トークン 5 倍消費、セッション間で一貫性なし
- コピペで放置: 一度テンプレを入れて忘れる → 2 週間動いた後、コードベースの変化で静かに壊れる
Karpathy のテンプレが「最低ライン（floor）」を 65 行・4 ルールで示した。@mnilax の主張は、天井（ceiling）はもう少し高いということ。エージェント時代特有の失敗モードを 8 ルールで追加する。
2. Karpathy オリジナル 4 ルール（基礎）
これだけで「教師なし Claude Code セッションの失敗の約 40%」がカバーされる。基礎なので必ず入れる。
| ルール | 何を防ぐか | 具体例 |
|---|---|---|
| 1. Think Before Coding | 静かな仮定で実装が始まる | 「仮定を明示」「不明なら聞く」「反論する」「迷ったら止まる」 |
| 2. Simplicity First | 過剰実装・推測機能の追加 | 「最小コードで解決」「単発コードに抽象化なし」「シニアが見て複雑と言うか」 |
| 3. Surgical Changes | 関係ない隣のコードを勝手に「改良」 | 「必要な所だけ触る」「動いてるものは refactor しない」「既存スタイル踏襲」 |
| 4. Goal-Driven Execution | 弱い成功条件・手順指示で迷子になる | 「成功条件を定義してループ」「手順を指示しない、何が成功かだけ伝える」 |
3. @mnilax が追加した 8 ルール（エージェント時代の落とし穴）
各ルールの背後に「実際に起きた事件」がある。これが説得力の核心。
Rule 5 — Use the model only for judgment calls
判断（分類・要約・抽出）には使う。決定論的処理（リトライ・ステータスコード判定）はコードで書く。「503 でリトライするか Claude に判断させる」コードが、リクエスト本体を文脈として読んで挙動がランダム化した事件から。
Rule 6 — Token budgets are not advisory
per-task 4,000 tokens / per-session 30,000 tokens。予算に近づいたら要約してリセット。90 分のデバッグセッションで 40 メッセージ前に却下したアイデアを再提案するループから。
Rule 7 — Surface conflicts, don't average them
コードベースに 2 つの矛盾するパターンがあるとき、Claude は両方混ぜようとする。新しい方・テストされてる方を選んで、他方を cleanup フラグ。「2 つのエラーハンドリングを混ぜて二重に握りつぶした」事件から。
Rule 8 — Read before you write
書く前に exports / 直接呼び出し元 / 共有 utility を読む。既存の同等関数を読まずに新規追加し、import 順で新しい方が優先、6 ヶ月の「正の値」が消えた事件から。「Looks orthogonal」は最も危険な台詞。
Rule 9 — Tests verify intent, not just behavior
テストは「なぜその挙動が重要か」を encode する。Auth 関数に 12 テスト全 pass、しかし本番で auth が壊れていた事件から。「何かを返す」しか検証していなかった。
Rule 10 — Checkpoint after every significant step
各ステップ後に 「何をやった / 何が verified / 何が残ってる」 を要約。6 ステップのリファクタリングが step 4 で間違い、気付いた時点で 5, 6 まで破壊状態の上に積まれていた事件から。
Rule 11 — Match codebase conventions
「自分が好む書き方」より 既存規約に従う。クラスコンポーネントの codebase に hooks を導入、`componentDidMount` 前提のテスト基盤を破壊した事件から。Conformance > taste。
Rule 12 — Fail loud
「完了」「pass」を簡単に言わない。DB マイグレーション「成功」報告の裏で、制約違反で 14% のレコードがサイレントスキップ、11 日後に発覚した事件から。不確実性は隠さず surface する。
4. 実証データ（30 codebase × 6 週間）
50 の代表タスクを 3 つの設定で比較。
| 設定 | ミス率 | コンプライアンス |
|---|---|---|
| CLAUDE.md なし | 約 41% | — |
| Karpathy 4 ルール | 約 12% | 78% |
| 12 ルール（4 + 8） | 約 3% | 76% |
注目ポイントは 「4 → 12 ルールでコンプライアンスがほぼ変わらない」こと。追加 8 ルールは別の失敗モードを潰すので、attention budget で競合しない。
記事内で 18 ルールまでテストしたが、14 ルール超でコンプライアンスが 76% → 52% に急落。Anthropic 公式の「200 行ルール」は経験則ではなく、計測で確認できる現象。
5. 効かなかったこと（貴重な失敗データ）
記事の白眉はここ。「やってみたけど効かなかった」を系統的に列挙している。
CLAUDE.md に書いても効かないパターン
- Reddit / X で見たルール — 大半が Karpathy 4 の言い換え、または局所特化（"always use Tailwind"）で汎用性なし
- 14 ルール超え — コンプライアンスが 76% → 52% に急落。「ルールあること」だけパターンマッチして読まなくなる
- ツール依存ルール — "Always use eslint" → eslint がない環境で silent fail。「match the codebase's enforced style」と抽象化すべき
- CLAUDE.md 内の例示 — 例示 3 個 ≒ ルール 10 個分のコンテキストコスト、過剰フィット。ルールは抽象、例は具体。ルールを書け
- "Be careful" / "think hard" / "really focus" — 検証不能。コンプライアンス 30%。「state assumptions explicitly」のような具体的命令文に置き換える
- "Be a senior engineer" — Claude は既に「自分は senior」と思っている。identity prompt は無意味、imperative rule が効く
6. メンタルモデル: CLAUDE.md は behavioral contract
CLAUDE.md is not a wishlist. It's a behavioral contract that closes specific failure modes you've observed.
Every rule should answer: what mistake does this prevent?
これが最も大事な思想。「あったらいいな」を書く場所ではなく、「実際に観測した失敗を再発させない」ための契約書。各ルールには「これが防ぐ失敗モード」が紐付いていなければならない。
これは自分が普段から実践してる運用の理論的裏付けでもあって、グローバル CLAUDE.md を 200 行以下に保つ、Skill / Hook / docs に分解して常時層を軽くする、ナレッジ索引で必要時だけ読み込む — これらは全部「behavioral contract」の発想と一致してる。そして未取り込みだった Rule 5（モデルを判断にのみ使う）/ 7（規約衝突を平均化しない）/ 12（Fail loud）の 3 つは、ぱるぷんてスクールの school-starter プラグイン v1.12.0 に取り込み済み。受講生は /plugin update school-starter でアップデートするだけで development.md に自動適用される。加えて、「CLAUDE.md に何書けばいい？」と聞けば /school-starter:claude-md スキルが起動して、12 ルール一覧と「自分の失敗モードに当てて育てる」手順をガイドしてくれる。「読んだけど自分で全部設定するのは大変…」となる必要なし、セットアップだけで一通り効く状態になってる。
結びの一言
CLAUDE.md は「あったらいいなリスト」ではなく、自分の失敗ログから生まれた行動契約。12 ルールを丸ごとコピペするのではなく、「自分が実際にやらかしたミス」と照合して必要な分だけ取り込むのが正しい使い方。
そして 200 行制限は経験則ではなく実証済みの構造的限界。足し算ではなく引き算で、自分の失敗モードに合った最小限のルールセットを育てていく。それが behavioral contract の本質。