Karpathy 氏の CLAUDE.md ルールで Claude のミスを 41% から 11% に削減。30 以上のコードベースを経て、さらに 8 つのルールを追加しました

2026年1月下旬、Andrej Karpathy が Claude のコードの書き方について不満を述べたスレッドを投稿しました。3つの失敗モード：暗黙の誤った仮定、過度な複雑化、触れるべきでないコードへの余計な変更。

Forrest Chang がそのスレッドを読み、不満点を1つの CLAUDE.md ファイルに4つの行動ルールとしてまとめ、GitHub に公開しました。初日で5,828スターを獲得。2週間で60,000ブックマーク。現在120,000スター。 2026年で最も急成長した単一ファイルリポジトリです。

その後、私は6週間かけて30のコードベースでテストしました。

4つのルールは機能します。以前は約40%の確率で発生していたミスが、ルールの得意とするタスクでは3%未満に減少しました。しかし、このテンプレートは1月時点のコード作成ミスを修正するために作られたものです。

2026年5月の Claude Code エコシステムには異なる問題があります — エージェント間の競合、フックのカスケード、スキル読み込みの競合、セッションをまたいで壊れるマルチステップワークフロー。

そこで、さらに8つのルールを追加しました。以下：完全な12ルールの CLAUDE.md、各ルールがなぜ必要なのか、そして元の Karpathy テンプレートが静かに壊れる4つの箇所。

説明を飛ばして貼り付けたい場合は、完全なファイルは最後にあります。

なぜこれが重要なのか

Claude Code の CLAUDE.md は、AI コーディングスタック全体で最も活用されていないファイルです。ほとんどの開発者は、次のいずれかです：

• これまでに持ったすべての好みをダンプする場所として扱い、4,000トークン以上に肥大化し、コンプライアンスが30%に低下
• 完全にスキップして毎回プロンプト — 5倍のトークン無駄、セッション間の一貫性なし
• テンプレートを一度コピーして忘れる。2週間は機能するが、コードベースが変化すると静かに壊れる

公式の Anthropic ドキュメントは明確です：CLAUDE.md は参考情報です。Claude は約80%の確率で従います。200行を超えると、重要なルールがノイズに埋もれてコンプライアンスが急激に低下します。

Karpathy のテンプレートは、1ファイル、65行、4ルールでこれを解決しました。それが下限です。

上限はもっと高いです。さらに8つのルール（以下で説明します）を追加することで、Karpathy が不満を述べた2026年1月のコード作成問題だけでなく、テンプレート作成時には存在しなかった2026年5月のエージェントオーケストレーション問題もカバーできます。

元の4つのルール

Forrest Chang のリポジトリを読んでいない方のために、下限：

ルール1 — コードを書く前に考える。

暗黙の仮定をしない。仮定していることを明示する。トレードオフを明らかにする。推測する前に質問する。よりシンプルなアプローチが存在する場合は反論する。

ルール2 — シンプルさ第一。

問題を解決する最小限のコード。推測的な機能は不要。単回使用のコードに抽象化は不要。シニアエンジニアが過剰に複雑だと言うなら、簡略化する。

ルール3 — 外科的変更。

必要なものだけに触れる。隣接するコード、コメント、フォーマットを「改善」しない。壊れていないものをリファクタリングしない。既存のスタイルに合わせる。

ルール4 — 目標駆動型実行。

成功基準を定義する。検証されるまでループする。Claude に従うべき手順を指示するのではなく、成功の姿を伝えて反復させる。

これら4つは、私が監視なしの Claude Code セッションで見られる失敗モードの約40%をカバーします。残りの約60%は以下のギャップに存在します。

私が追加した8つのルール（とその理由）

それぞれのルールは、Karpathy の4つでは不十分だった実際の瞬間から生まれました。その瞬間と、ルールを示します。

ルール5 — モデルに言語以外の作業をさせない

Karpathy のルールはこれについて触れていません。モデルが決定論的なコードであるべきことを決定します（API 呼び出しをリトライするか、メッセージをどうルーティングするか、いつエスカレーションするか）。毎週異なる決定。トークンあたり$0.003の不安定な if-else。

1## ルール5 — モデルは判断が必要な場合のみ使用する
2Claude を使用する場面：分類、下書き、要約、非構造化テキストからの抽出。
3Claude を使用しない場面：ルーティング、リトライ、ステータスコード処理、決定論的変換。
4ステータスコードがすでに答えを提供しているなら、プレーンなコードで答えを出す。

実際の事例： Claude に「503でリトライすべきか判断させる」コードは2週間は完璧に動作しましたが、その後モデルがリクエストボディを判断のコンテキストとして読み始めたため不安定になりました。プロンプトがランダムだったため、リトライポリシーもランダムになりました。

ルール6 — 厳格なトークン予算、例外なし

予算のない CLAUDE.md は白紙の小切手です。すべてのループは50,000トークンのコンテキストダンプに発展する可能性があります。モデルは自ら停止しません。

1## ルール6 — トークン予算は参考ではない
2タスクごとの予算：4,000トークン。
3セッションごとの予算：30,000トークン。
4タスクが予算に近づいたら、要約して新しく始める。無理に続けない。
5超過を明らかにすること > 静かに超過すること。

実際の事例： デバッグセッションが90分間続きました。モデルは同じ8KBのエラーメッセージを繰り返し処理し、すでに試した修正を徐々に見失っていきました。最後には、40メッセージ前に却下した修正を提案していました。トークン予算があれば12分で止められたでしょう。

ルール7 — 競合を表面化させ、平均化しない

コードベースの2つの部分が矛盾する場合、Claude は両方を満足させようとします。結果は一貫性を失います。

1## ルール7 — 競合を表面化させ、平均化しない
2コードベース内の既存の2つのパターンが矛盾する場合、それらを混ぜ合わせない。
3一方（より新しい/よりテストされた方）を選び、その理由を説明し、もう一方をクリーンアップ対象としてフラグを立てる。
4両方のルールを満たす「平均的な」コードは最悪のコードです。

実際の事例： コードベースに2つのエラーハンドリングパターンがありました — 1つは明示的な try/catch 付きの async/await、もう1つはグローバルエラーバウンダリです。Claude は両方を行う新しいコードを書きました。エラーハンドラが二重になりました。エラーが2回飲み込まれた理由を解明するのに30分かかりました。

ルール8 — 書く前に読む

Karpathy の「外科的変更」は Claude に隣接コードに触れないよう指示します。しかし、隣接コードを理解するようには指示しません。これがないと、Claude は30行離れた既存コードと競合する新しいコードを書きます。

1## ルール8 — 書く前に読む
2ファイルにコードを追加する前に、そのファイルのエクスポート、直接の呼び出し元、および明らかな共有ユーティリティを読む。
3既存のコードがなぜそのように構成されているか理解できない場合は、追加する前に質問する。
4「私には直交しているように見える」は、このコードベースで最も危険なフレーズです。

実際の事例： Claude が、読んでいない既存の同一関数の隣に関数を追加しました。両方の関数は同じことを行っていました。新しい関数がインポート順序のために優先されました。古い関数は6ヶ月間の信頼できる情報源でした。

ルール9 — テストはオプションではないが、目標でもない

Karpathy の「目標駆動型実行」はテストを成功基準として暗に示しています。実際には、Claude は「テスト合格」を唯一の目標として扱い、浅いテストに合格するが他のすべてを壊すコードを書きます。

1## ルール9 — テストは意図を検証するものであり、単なる動作ではない
2すべてのテストは、動作が何をするかだけでなく、なぜ重要なのかをコード化しなければならない。
3`expect(getUserName()).toBe('John')` のようなテストは、関数がハードコードされたIDを受け取る場合、無価値です。
4ビジネスロジックが変更されたときに失敗するテストを書けないなら、その関数は間違っています。

実際の事例： Claude が認証関数に対して12のテストを書きました。すべて合格しました。本番環境では認証が壊れていました。テストは関数が何かを返すことをテストしており、正しいものを返すかどうかはテストしていませんでした。関数は定数を返していたため合格しました。

ルール10 — 長時間実行操作にはチェックポイントが必要

Karpathy のテンプレートは一回限りのインタラクションを想定しています。実際の Claude Code の作業はマルチステップです — 20ファイルにわたるリファクタリング、セッションを通じた機能構築、複数コミットにわたるデバッグ。チェックポイントがないと、1つの誤った方向転換ですべての進捗が失われます。

1## ルール10 — 重要なステップごとにチェックポイントを設ける
2マルチステップタスクの各ステップ完了後：何を行ったか、何が検証されたか、何が残っているかを要約する。
3私に説明できない状態から続行しない。
4見失った場合は、停止して再述する。

実際の事例： 6ステップのリファクタリングがステップ4で失敗しました。私が気づいたときには、Claude は壊れた状態の上にステップ5と6も実行していました。解きほぐすのに全体をやり直すよりも時間がかかりました。チェックポイントがあればステップ4で捕捉できたでしょう。

ルール11 — 慣習は新規性に勝る

確立されたパターンがあるコードベースでは、Claude は独自のパターンを導入したがります。たとえその方法が「より良い」場合でも、2つのパターンの導入はどちらか一方のパターン単独よりも悪いです。

1## ルール11 — コードベースの慣習に従う（たとえ同意しなくても）
2コードベースが snake_case を使用していて、あなたが camelCase を好む場合：snake_case。
3コードベースがクラスベースコンポーネントを使用していて、あなたがフックを好む場合：クラスベース。
4不同意は別の会話です。コードベース内では、適合性 > 好み。
5慣習が本当に有害だと思うなら、それを表面化させる。静かに分岐させない。

実際の事例： Claude がクラスコンポーネントのコードベースに React フックを導入しました。動作はしましたが、componentDidMount を前提としたコードベースのテストパターンも壊しました。削除と書き直しに半日かかりました。

ルール12 — 静かにではなく、目に見える形で失敗する

最もコストがかかる Claude の失敗は、成功に見えるものです。関数は「動作する」が間違ったデータを返す。マイグレーションは「完了」するが30レコードをスキップする。テストは「合格」するが、アサーションが間違っていたためだけ。

1## ルール12 — 大きな声で失敗する
2何かが機能したか確信が持てない場合は、明示的にそう言う。
330レコードが静かにスキップされた場合、「マイグレーション完了」は間違い。
4テストをスキップした場合、「テスト合格」は間違い。
5私が尋ねたエッジケースを検証しなかった場合、「機能は動作する」は間違い。
6不確実性を隠すのではなく、表面化させることをデフォルトにする。

実際の事例： Claude がデータベースマイグレーションは「正常に完了しました」と報告しました。制約違反に当たったレコードの14%を静かにスキップしていました。スキップはログに記録されましたが表面化されませんでした。11日後、レポートがおかしくなり始めて問題が発見されました。

数字

同じ50の代表的なタスクセットを30のコードベースで6週間追跡しました。3つの構成：

ミス率 = 意図に合わせるために修正または書き直しが必要だったタスク。カウント：暗黙の誤った仮定、過剰設計、直交的損害、静かな失敗、慣習違反、競合の平均化、チェックポイントの見逃し。

コンプライアンス = Claude が該当するルールを適用可能な場合に目に見えて適用した頻度。

興味深い結果は、見出しの41%から3%への低下ではありません。4ルールから12ルールに増やしてもコンプライアンスのオーバーヘッドがほとんど増えなかったこと（78%→76%）ですが、ミス率をさらに8ポイント削減しました。新しいルールは元の4つが対処しなかった失敗モードをカバーしています — 同じ注意予算を競い合うことはありません。

Karpathy のテンプレートが静かに壊れる箇所

新しいルールを追加する前でも、元の4ルールテンプレートでは不十分な4つの箇所：

1. 長時間実行エージェントタスク。

Karpathy のルールは Claude がコードを書いている瞬間を対象としています。Claude がマルチステップパイプラインを実行しているときに何が起こるかについては触れていません。予算ルールなし。チェックポイントルールなし。「大きな声で失敗する」ルールなし。パイプラインは漂流します。

2. マルチコードベースの一貫性。

「既存のスタイルに合わせる」は1つのスタイルを前提としています。12のサービスがあるモノレポでは、Claude はどのスタイルを選ぶか決めなければなりません。元のルールはその方法を指示しません。ランダムに選ぶか平均化します。

3. テストの品質。

目標駆動型実行は「テスト合格」を成功と見なします。テストが意味のあるものでなければならないとは言いません。結果として、何も有用なことをテストしないが Claude を自信満々にするテストが生まれます。

4. 本番環境 vs プロトタイプ。

本番コードを過剰設計から保護する同じ4つのルールは、方向性を見極めるために推測的なスキャフォールディングが100行正当に必要なプロトタイプも遅くします。Karpathy の「シンプルさ第一」は初期段階のコードに過剰に発動します。

追加された8つのルールは Karpathy の4つを置き換えるものではありません。彼のモデル（2026年1月、オートコンプリートスタイルのコーディング）が2026年5月のエージェント駆動型、マルチステップ、マルチコードベースの作業に合わないギャップを埋めるものです。

うまくいかなかったこと

12ルールに落ち着く前に試したこと：

• Reddit や X で見たルールを追加する。ほとんどは Karpathy の4つの言い換えか、一般化できないドメイン固有ルール（「常に Tailwind クラスを使う」）でした。削除。
• 12ルール以上。最大18までテストしました。14ルールを超えるとコンプライアンスが76%から52%に低下。200行の上限は現実的です。それを超えると、Claude は実際に読まずに「ルールが存在する」というパターンマッチングを始めます。
• 存在しない可能性のあるツールに依存するルール。「常に eslint を使う」は eslint がインストールされていないと壊れます。ルールは静かに失敗します。機能に依存しない表現に置き換え：「eslint を使う」ではなく「コードベースで強制されているスタイルに合わせる」。
• ルールの代わりに CLAUDE.md に例を入れる。例はルールより重い。3つの例で約10ルール分のコンテキストを消費し、Claude はそれに過適合します。ルールは抽象的、例は具体的。ルールを使う。
• 「注意して」「よく考えて」「本当に集中して」。純粋なノイズ。これらへのコンプライアンスはテスト不可能なため約30%に低下。具体的な命令（「仮定を明示的に述べる」）に置き換え。
• Claude に「シニア」になるよう指示する。効果なし。Claude はすでに自分はシニアだと思っています。コンプライアンスのギャップは思考と行動の間にあります。命令形のルールがギャップを埋めます；アイデンティティプロンプトは埋めません。

完全な12ルール CLAUDE.md（コピペ準備完了）

1# CLAUDE.md — 12ルールテンプレート
2
3これらのルールは、明示的に上書きされない限り、このプロジェクトのすべてのタスクに適用されます。
4バイアス：重要でない作業ではスピードよりも慎重さ。重要でないタスクでは判断を使用。
5
6## ルール1 — コードを書く前に考える
7仮定を明示的に述べる。不確かな場合は、推測するよりも質問する。
8曖昧さがある場合は、複数の解釈を提示する。
9よりシンプルなアプローチが存在する場合は反論する。
10混乱したら停止する。何が不明確かを明確にする。
11
12## ルール2 — シンプルさ第一
13問題を解決する最小限のコード。推測的なものは一切不要。
14要求された以上の機能は不要。単回使用のコードに抽象化は不要。
15テスト：シニアエンジニアが過剰に複雑だと言うか？もしそうなら、簡略化する。
16
17## ルール3 — 外科的変更
18必要なものだけに触れる。自分の混乱だけを掃除する。
19隣接するコード、コメント、フォーマットを「改善」しない。
20壊れていないものをリファクタリングしない。既存のスタイルに合わせる。
21
22## ルール4 — 目標駆動型実行
23成功基準を定義する。検証されるまでループする。
24手順に従わない。成功を定義し、反復する。
25強力な成功基準があれば、独立してループできる。
26
27## ルール5 — モデルは判断が必要な場合のみ使用する
28私を使用する場面：分類、下書き、要約、抽出。
29私を使用しない場面：ルーティング、リトライ、決定論的変換。
30コードが答えられるなら、コードが答える。
31
32## ルール6 — トークン予算は参考ではない
33タスクごと：4,000トークン。セッションごと：30,000トークン。
34予算に近づいたら、要約して新しく始める。
35超過を明らかにする。静かに超過しない。
36
37## ルール7 — 競合を表面化させ、平均化しない
382つのパターンが矛盾する場合、一方（より新しい/よりテストされた方）を選ぶ。
39理由を説明する。もう一方をクリーンアップ対象としてフラグを立てる。
40矛盾するパターンを混ぜ合わせない。
41
42## ルール8 — 書く前に読む
43コードを追加する前に、エクスポート、直接の呼び出し元、共有ユーティリティを読む。
44「直交しているように見える」は危険。コードがなぜそのように構成されているか不明なら、質問する。
45
46## ルール9 — テストは意図を検証するものであり、単なる動作ではない
47テストは、動作が何をするかだけでなく、なぜ重要なのかをコード化しなければならない。
48ビジネスロジックが変更されたときに失敗できないテストは間違っている。
49
50## ルール10 — 重要なステップごとにチェックポイントを設ける
51何を行ったか、何が検証されたか、何が残っているかを要約する。
52私に説明できない状態から続行しない。
53見失った場合は、停止して再述する。
54
55## ルール11 — コードベースの慣習に従う（たとえ同意しなくても）
56コードベース内では、適合性 > 好み。
57慣習が本当に有害だと思うなら、それを表面化させる。静かに分岐させない。
58
59## ルール12 — 大きな声で失敗する
60何かが静かにスキップされた場合、「完了」は間違い。
61テストがスキップされた場合、「テスト合格」は間違い。
62不確実性を隠すのではなく、表面化させることをデフォルトにする。

CLAUDE.md としてリポジトリルートに保存。12ルールの下にプロジェクト固有のルール（スタック、テストコマンド、エラーパターン）を追加。合計200行を超えないこと。超えるとコンプライアンスが低下します。

インストール方法

2つのステップ：

1# 1. Karpathy の4ルールベースラインを CLAUDE.md に追加
2curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md
3
4# 2. この記事のルール5〜12を以下に貼り付け

リポジトリルートに保存。>> が重要で、既存の CLAUDE.md に追加され、すでにあるプロジェクト固有のルールを上書きしません。

メンタルモデル

CLAUDE.md は願い事リストではありません。それは、あなたが観察した特定の失敗モードを塞ぐ行動契約です。

すべてのルールは次の問いに答えるべきです：これはどのようなミスを防ぐのか？

Karpathy の4つは、彼が2026年1月に見た失敗モードを防ぎます：暗黙の仮定、過剰設計、直交的損害、弱い成功基準。これらは基礎です。省略しないでください。

私が追加した8つは、2026年5月に出現した失敗モードを防ぎます：予算なしのエージェントループ、チェックポイントなしのマルチステップタスク、テストしないテスト、静かな失敗を隠す静かな成功。これらは追加的です。

結果は異なるかもしれません。マルチステップパイプラインを実行しない場合、ルール10は重要ではありません。コードベースにリンティングで強制された一貫したスタイルがある場合、ルール11は冗長です。12のルールを読み、実際に犯したミスに対応するものだけを保持し、残りは削除してください。

実際の失敗モードに合わせた6ルールの CLAUDE.md は、決して使わない6ルールを含む12ルールのものより優れています。

T H E _ E N D

Karpathy の2026年1月のスレッドは不満でした。Forrest Chang がそれを4つのルールに変えました。120,000人の開発者が結果にスターを付けました。そのほとんどは今でも4つのルールを実行しています。

モデルは改善されました。エコシステムは変わりました。マルチステップエージェント、フックのカスケード、スキル読み込み、マルチコードベース作業 — これらは Karpathy がスレッドを書いたときには存在しませんでした。4つのルールはそれらに対処していません。間違っているわけではなく、不完全なのです。

さらに8つのルール。30のコードベースで6週間のテスト。ミス率41%から3%へ。

これをブックマークして、今夜12のルールを CLAUDE.md に貼り付けてください。Claude の間違った方向転換を一週間分節約できたら、再投稿してください。

毎日の Claude 最適化のヒントのための Telegram：

*https://t.me/+_ZWrQN7GuDA3ZDEy*