原文タイトル：Karpathy’s 4 CLAUDE.md rules cut Claude mistakes from 41% to 11%. After 30 codebases, I added 8 more
原文作者：@Mnilax
编译：Peggy，BlockBeats

編者注：2026年1月、アンドレイ・カルパシーはClaudeのコーディング方法に対して愚痴をこぼし、非常に小さく見えるがAIプログラミングワークフローにおいて極めて重要なファイル：CLAUDE.mdを浮き彫りにした。フォレスト・チャンはこれらの問題点を整理し、Claudeのコーディング時に頻出する誤り：黙って仮定すること、過度なエンジニアリング、関係のないコードへの誤った干渉、明確な成功基準の欠如を制約するための4つの行動ルールにまとめ、GitHubに公開した。このプロジェクトはリリース初日にスター5,828を獲得し、2週間で6万回保存され、現在は12万スターを超え、2026年最速成長の単一ファイルコードリポジトリとなっている。

その後、私は6週間で30のコードベースを用いてテストを行った。

これらの4つのルールは確かに効果的だった。従来約40％の確率で発生していた誤りが、これらのルールが有効なタスクでは3％未満に減少した。しかし問題は、このテンプレートが最初に2026年1月のClaudeのコード作成時に発生した誤りを解決するために作られたことにある。

2026年5月には、Claude Codeのエコシステムはすでに異なる問題に直面していた：エージェント間の衝突、フックの連鎖トリガー、スキルのロード衝突、複数セッションにまたがる多段階ワークフローの中断などだ。

そこで、私はさらに8つのルールを追加した。以下は完全な12ルール版のCLAUDE.md：それぞれのルールがなぜ必要か、また原版のKarpathyテンプレートがどの4つのポイントで静かに失効するかを解説している。

もし解説を飛ばして直接コピーしたい場合は、最後に掲載した完全版を参照されたい。

なぜこれが重要なのか

Claude CodeのCLAUDE.mdは、AIプログラミング技術スタックの中で最も過小評価されているファイルだ。ほとんどの開発者は三つの誤りを犯しがちだ。

第一に、それを好みのゴミ箱とみなして、すべての習慣を詰め込み、最終的に4000トークン超に膨れ上がり、ルール遵守率が30％に落ちる。

第二に、完全に使わず、毎回新たにプロンプトを作り直す。これによりトークンの浪費が5倍になり、セッション間の一貫性も失われる。

第三に、テンプレートをコピーしたら放置する。効果は2週間持つかもしれないが、コードリポジトリの変化に伴い、知らぬ間に無効になる。

Anthropicの公式ドキュメントは明確に述べている：CLAUDE.mdはあくまで推奨に過ぎない。Claudeは約80％の時間をこれに従うが、行数が200行を超えると遵守率は著しく低下し、重要なルールがノイズに埋もれてしまう。

カルパシーのテンプレートはこの問題を解決した：1ファイル、65行、4ルール。これが最低限の基準だ。

しかし、上限はさらに高められる。以下の8ルールを追加することで、2026年1月にカルパシーが愚痴ったコード作成の問題だけでなく、2026年5月に出現したエージェントの調整問題もカバーできる。これらの問題は元のテンプレート作成時には存在しなかった。

原始の4ルール

もしフォレスト・チャンのリポジトリを未見なら、まずこの基本版を見てほしい。

ルール1：コーディング前に考える。

黙って仮定しない。仮定を明示し、トレードオフを露出させる。推測する前に質問を投げかける。よりシンプルな方案がある場合は積極的に反対意見を述べる。

ルール2：シンプル優先。
問題解決に必要な最少コードを使う。想像上の機能を追加しない。使い捨てのコードには抽象化を設計しない。経験豊富なエンジニアが過剰と判断すれば、簡素化すべきだ。

ルール3：外科的修正。
必要な部分だけを修正する。隣接するコードやコメント、フォーマットの「最適化」は避ける。壊れていない部分のリファクタリングも控える。スタイルに一貫性を持たせる。

ルール4：目標指向の実行。
成功基準を最初に定義し、検証までループする。Claudeに一歩一歩のやり方を指示せず、成功のイメージを伝え、自己反復させる。

この4ルールは、無監督のClaude Codeセッションで約40％の失敗を防ぐことができる。残りの約60％は以下の空白地帯に潜む。

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

それぞれのルールは、実際の場面から生まれたものだ：カルパシーの最初の4ルールは十分ではなかった。以下にそのシナリオと対応ルールを示す。

ルール5：モデルに非言語的作業をさせない

Claudeに処理させる：分類、起草、要約、非構造化テキストからの情報抽出。
させない：ルーティング、リトライ、ステータスコード処理、決定的変換。
ステータスコードが回答済みなら、普通のコードに任せる。

カルパシーのルールはこれをカバーしていなかった。その結果、モデルは本来決定性コードで処理すべき問題：APIリトライの判断、メッセージのルーティング、処理のアップグレードタイミングを自ら決め始めた。結果、毎週判断が異なり、1トークンあたり0.003ドルの不安定なif-elseになった。

例：あるコードがClaudeに「503時にリトライすべきか判断させる」ものだった。最初は良好に動作していたが、2週間後に突然不安定になった。なぜなら、モデルがリクエスト本文も判断の文脈に含め始めたからだ。リトライ戦略はランダムになり、promptもランダム化された。

ルール6：トークン予算を設定し、例外を設けない

単一タスクの予算：4,000トークン。
セッション全体の予算：30,000トークン。
予算に近づいたら、現状を要約し、再スタートする。無理に続行しない。予算超過の問題を明示する方が黙って超過するより良い。

予算制約のないCLAUDE.mdは、空白の小切手と同じだ。各ループで制御不能になり、50,000トークンのコンテキストダンプに陥る可能性がある。モデルは自ら停止しない。

例：デバッグセッションが90分続き、Claudeは同じ8KBのエラー情報を何度も反復し、既に試した修正案を忘れ始める。最後には、否定した40の提案を再び出してくる。予算があれば、12分目で中断すべきだった。

ルール7：衝突を明示し、妥協しない

既存の二つのパターンが矛盾している場合、それらを混在させてはいけない。
一方のパターンを選び、更新済みまたはよりテストされた方を優先し、その理由を示す。もう一方は後で整理する必要があるとマークする。
両方を満たそうとする「平均コード」は最悪のコードだ。

矛盾したコード部分があると、Claudeは両方を満たそうとし、結果的に一貫性のないコードになる。

例：エラー処理にasync/awaitとtry/catchを使うパターンと、グローバルエラー境界のパターンが混在しているリポジトリで、Claudeは両方を併用した新コードを書き、エラーが二重に捕捉される事態に。30分かけて原因を理解した。

ルール8：読むことから始める

新たにコードを追加する前に、そのファイルのエクスポート内容、呼び出し側、共有ツール関数を読む。
既存コードの構成理由が理解できなければ、質問し、理解してから追加する。
「関係ないと思う」は最も危険な一言だ。

カルパシーの「外科的修正」は、隣接コードを変更しないことを教えるが、「理解してから修正する」ことは教えていない。これがないと、30行外の既存コードと衝突する新規コードを書いてしまう。

例：既存関数の横に、全く同じ機能の関数を追加したが、元の関数を読まずに作成したため、両者は同じことをしている。importの順序の関係で、新関数が旧関数を上書きし、旧関数は6ヶ月間唯一の標準として存在していた。

ルール9：テストは必須だが、テストが目的ではない

すべてのテストには、「なぜこの動作が重要か」を記述する。
例：expect(getUserName()).toBe(‘John’)は価値がない。なぜなら、その関数がハードコーディングされたIDを受け取るからだ。
ビジネスロジックの変化に耐えるテストを書けなければ、その関数は誤りだ。

カルパシーの「目標指向の実行」は、テストを成功の基準とできると示唆しているが、実際にはClaudeは「テスト合格」を唯一の目標とし、浅いテストを通じて他を破壊するコードを書きがちだ。

例：Claudeは認証関数に12個のテストを書き、すべて通過したが、実運用の認証ロジックは壊れていた。これらのテストは、「関数が何かを返す」ことだけを検証し、正しい値を返すかどうかは検証していなかった。関数は定数を返していたため、テストに合格した。

ルール10：長時間動作する操作にはチェックポイントを

複数段階のタスクでは、各ステップ完了ごとに、何をしたか、何を検証したか、何が残っているかを要約し、確認する。
理解できていない状態から次に進まない。迷ったら停止し、現在の状態を再度整理する。

カルパシーのテンプレートは一回のやりとりを想定しているが、実際のClaude Codeは複数ステップにまたがることが多い。20ファイルのリファクタリングや、セッション内での機能構築、複数コミットのデバッグなどだ。チェックポイントがなければ、一つのミスで全体の進捗が失われる。

例：6段階のリファクタリング中、4段階でエラーが発生。気づいたときには、Claudeはすでに5・6段階を完了しており、修正に時間がかかる。チェックポイントがあれば、4段階で問題を発見できた。

ルール11：合意を優先し、新規性は二の次

既存のスタイルがsnake_caseなら、それを使う。
クラスベースのコンポーネントが標準なら、hooksを使わずクラスベースを選ぶ。
意見の相違は議論の対象だ。コードベース内では一貫性が最優先。
もし特定の規約が害になると本気で思うなら、明示的に提案すべきだ。黙って分岐させてはいけない。

既存のコードスタイルに反して、新たに自分のスタイルを導入しようとするClaudeは、最も良い方法ではない。二つのスタイルを併用すること自体が最悪の選択だ。

例：ClaudeがclassコンポーネントのReactコードにhooksを導入した。動作はしたが、既存のテスト（componentDidMountに依存）を破壊したため、最終的に削除・書き直しに半日かかった。

ルール12：明示的に失敗を示せ、黙って失敗させるな

何かが成功したと確信できない場合は、明示的に伝える。
30件のレコードを黙ってスキップしたら、「移行完了」とは言えない。
どんなテストもスキップしたら、「合格」とは言えない。
境界条件の検証を怠ったら、「機能は使える」とは言えない。
不確実性は隠さず、明示的に示すべきだ。

Claudeの最も高価な失敗は、成功したかのように見える失敗だ。関数が「動いた」ように見えて誤ったデータを返したり、移行が「完了」したと見せかけて30件のレコードを静かにスキップしたり、テストが「通った」ように見えて実は断言自体が誤っていたり。

例：Claudeが「データベース移行が成功した」と言ったが、実際には14％の制約違反レコードを黙ってスキップしていた。ログには記録されたが、明示的に示されていなかった。11日後、レポートデータの異常に気づき、問題を発見した。

データ結果

私は6週間で、50の代表的タスクを追跡し、30のコードベースをカバーし、3つの設定をテストした。

誤り率は：タスクを修正または書き直す必要がある誤りの割合。静かに仮定を誤る、過剰エンジニアリング、関係のない破壊、静かに失敗、規約違反、衝突の妥協、チェックポイントの漏れを含む。

遵守率は：ルールが適用されたときに、Claudeがどの程度の確率で明示的にそのルールを適用するか。

本当に興味深いのは、誤り率が41％から3％に下がったことだけではない。さらに、4ルールから12ルールに拡張した結果、遵守負担はほとんど増えず、遵守率は78％から76％にわずかに低下したが、誤り率は8ポイントも低下した。新たに追加したルールは、元の4ルールではカバーできなかった失敗パターンを補完しており、注意力の競合はしていない。

カルパシーのテンプレートはどこで静かに失効するか

たとえ新ルールを追加しなくても、元の4ルールのテンプレートは少なくとも4つの点で不十分だ。

第一、長時間動作するエージェントタスク。
カルパシーのルールは、Claudeがコーディングしている瞬間を対象としている。しかし、多段パイプラインを実行中のClaudeはどうなるか？
元のテンプレートには予算ルールもチェックポイントルールも、「大声で失敗」するルールもない。結果、パイプラインは徐々にズレていく。

第二、多コードベースの一貫性。
「既存スタイルに合わせる」デフォルトは一つだけだが、12サービスのモノレポでは、Claudeはどのスタイルに合わせるべきか選択しなければならない。
原始ルールはその選択方法を示していない。結果、ランダムに選ぶか、複数のスタイルを平均化して混ぜる。

第三、テストの質。
「目標指向の実行」は「テスト合格」を成功とみなすが、テスト自体の意味を明示していない。
その結果、Claudeはほとんど何も検証しないテストを書き、それをもって成功と誤認する。

第四、実運用とプロトタイプ段階の違い。
同じ4ルールは、実運用コードの過度なエンジニアリングを防ぐが、プロトタイプ開発には逆効果になることもある。
探索的なスケルトンを100行書く必要がある場合、カルパシーの「シンプル優先」は早期のコードでは過剰に働きやすい。

これらの8ルールは、カルパシーの原始4ルールを置き換えるものではなく、補完するものだ。
原テンプレートは2026年1月の自動補完的コード作成シナリオに対応しているが、2026年5月以降のエージェント駆動、多段階、多コードベース協調の環境では、問題の性質が異なる。

効果がなかった方法

最終的に12ルールに到達する前に、いくつかの他の案も試した。

Reddit / Xで見かけたルールを追加。
ほとんどはKarpathyの4ルールの言い換えか、特定領域のルール（例：「Tailwindクラスを常に使う」）だったため、最終的に削除。

12超のルールを試す。
最大18ルールまで試したが、14を超えると遵守率は76％から52％に低下。200行制限は確かに存在し、これを超えるとClaudeはルールをパターンマッチングとみなす傾向が強まる。

特定ツールに依存するルール。
例：「eslintを常に使う」。プロジェクトにeslintがなければ静かに無効化される。これを「コードスタイルに従う」に変更。

例示をルールの代わりに配置。
例はコンテキストを多く消費し、3つの例で約10ルール分の情報量に相当し、Claudeは過剰適合しやすい。ルールは抽象的、例は具体的。

「気をつけて」「真剣に考える」「集中する」などの指示はノイズだ。
これらは遵守率が30％程度に低下。具体的な命令に置き換えた。

Claudeに「経験豊富なエンジニア」のように振る舞うよう指示。
これは効果が薄い。Claudeはすでに自分を経験豊富なエンジニアとみなしている。
実行の差を縮めるには命令式ルールが有効だが、身分提示は効果薄。

完全な12ルール版CLAUDE.md

以下は、そのままコピー＆ペーストできる完全版だ。

※現状、Feishuドキュメント外には掲載不可。

リポジトリのルートにCLAUDE.mdとして保存し、そこにこの12ルールとともに、技術スタックやテストコマンド、エラーのパターンなど、プロジェクト固有のルールを追加する。全体で200行以内に収めること。超えると遵守率が著しく低下する。

インストール方法

簡単な2ステップ。

1. Karpathyの4ルールをCLAUDE.mdに追記
   curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

2. 本文のルール5～12を貼り付け

ファイルはリポジトリのルートに保存。>>は既存のCLAUDE.mdに追記するためのもので、既存ルールを上書きしない。

心のモデル

CLAUDE.mdは願望リストではなく、行動契約だ。既知の具体的な失敗パターンを封じるためのもの。

各ルールは、「何を防ぐか」に答えるべきだ。

カルパシーの4ルールは、2026年1月に見た失敗：静かに仮定、過剰エンジニアリング、関係のない破壊、成功基準の薄さを防ぐ。これらは基礎だ、飛ばしてはいけない。

私が追加した8ルールは、2026年5月以降に出現した新たな失敗：予算なしのエージェントループ、チェックポイントなしの多段階、重要なロジックを測定せずに通過するテスト、静かに失敗を成功に見せかける問題を防ぐ。これらは増分的な修正だ。

もちろん、効果は人による。多段パイプラインを走らせないならルール10は不要だし、スタイルが統一されていてlintが強制しているならルール11も冗長だ。これらを踏まえ、自分の誤りに直結するルールだけを残し、不要なものは削除すべきだ。

12ルールの中から、自分の失敗に効いたものだけを残すのが最良だ。

結び

2026年1月のカルパシーのツイートは、根底に不満があった。それをフォレスト・チャンが4ルールに昇華させ、最終的に12万開発者がスターを付けた。多くは今も4ルールだけを使っている。

モデルは進化し、エコシステムも変わった。多段エージェント、フックの連鎖、スキルのロード、多コードベースの協調は、あのツイート時には存在しなかった。元の4ルールは不完全だった。

8つの新ルールを追加し、30コードベースのテストを6週間行い、誤り率は41％から3％に低下した。

今夜、この文章を保存し、これら12ルールをCLAUDE.mdに貼り付けてほしい。少しでもClaudeの無駄な時間を省けたなら、ぜひ拡散を。

[原文リンク]

律動BlockBeatsの求人情報はこちら：

Telegram登録グループ：https://t.me/theblockbeats

Telegram交流グループ：https://t.me/BlockBeats_App

Twitter公式アカウント：https://twitter.com/BlockBeatsAsia