編集者注：2026年1月、アンドレジ・カルパティのClaudeによるコード作成への不満が、AIプログラミングワークフローにおいて極めて重要な1つのファイル、CLAUDE.mdを生み出した。フォレスト・チャンはその後、これらの問題を4つの行動規則に整理し、Claudeがコード作成時によく犯す誤り——沈黙の仮定、過剰な設計、無関係なコードへの影響、明確な成功基準の欠如——を制約しようと試みた。

しかし数ヶ月後、Claude Code の使用シナリオはもはや「モデルにコードを書かせる」だけではなくなった。マルチステップエージェント、フックによる連鎖的トリガー、スキルのロード、複数コードリポジトリ間の協力が標準的なものとなり、新たな失敗パターンも出現し始めた：長時間タスクにおけるモデルの制御喪失、テストは通過するが実際のロジックを検証していない、移行は完了したがエラーを静かにスキップした、異なるコードスタイルが誤って混在した。

著者は6週間で30のコードリポジトリをテストし、Karpathyの元の4つのルールに8つのルールを追加して、AIプログラミングが単一の補完からエージェントによる協働へ移行した際に生じる新たな課題をカバーしようとしました。

以下が原文です：

2026年1月下旬、アンドレジ・カルパティはツイッターのスレッドを投稿し、Claudeのコード作成方法について不満を述べた。彼は三つの典型的な問題を指摘した：説明なしに誤った仮定をすること、過剰に複雑化すること、そして変更する必要のないコードに無関係な破壊を引き起こすこと。

フォレスト・チャンはこのツイートのスレッドを見て、不満を4つの行動規則に整理し、単独のCLAUDE.mdファイルに記載してGitHubに公開した。このプロジェクトは公開初日で5,828個のStarを獲得し、2週間以内に60,000回保存され、現在では120,000個のStarを獲得し、2026年で最も成長が速い単一ファイルのコードリポジトリとなった。

その後、私は6週間の間に30のコードリポジトリでそれをテストしました。

この4つのルールは確かに効果があります。過去約40％の確率で発生していたエラーは、これらのルールが有効なタスクでは3％以下に低下しました。しかし問題は、このテンプレートが1月のClaudeがコードを書く際に発生したエラーを解決するために作られたことにあることです。

2026年5月までに、Claude Codeエコシステムが直面する問題は異なっていた：エージェント間の衝突、フックの連鎖的トリガー、スキルのロード衝突、およびセッション間のマルチステップワークフローの中断など。

したがって、さらに8つのルールを追加しました。以下が完全な12ルール版CLAUDE.mdです。それぞれのルールを追加した理由と、オリジナルのKarpathyテンプレートがどこで静かに機能しなくなるかを説明します。

説明をスキップして、そのままコピーして使いたい場合は、完全なファイルを本文の最後に掲載しています。

なぜこれが重要なのか

Claude Code の CLAUDE.md は、AI プログラミング技術スタックの中で最も過小評価されているファイルである。多くの開発者は通常、以下の3つの誤りを犯す：

まず、それを好みのゴミ箱として扱い、すべての習慣を詰め込み、最終的に4000以上のトークンに膨れ上がらせ、ルール遵守率を30%まで低下させる。

第二に、まったく使わず、毎回新しいプロンプトを入力すると、トークンが5倍無駄になり、セッション間の一貫性が失われます。

第三に、テンプレートをコピーした後、一切手を付けない。それは2週間は機能するかもしれないが、コードベースが変更されるにつれて、気づかないうちに機能しなくなる。

Anthropicの公式ドキュメントには明確に記載されています：CLAUDE.mdはあくまで提案的なものです。Claudeは約80％の時間、それに従います。200行を超えると、重要なルールがノイズに埋もれるため、従う割合が明確に低下します。

Karpathyのテンプレートはこの問題を解決します：1つのファイル、65行、4つのルール。これが最低基準です。

しかし、上限はさらに高められる。以下の8つのルールを追加すると、これはKarpathyが2026年1月に不満を述べたコード作成の問題だけでなく、2026年5月に初めて現れたAgent編成の問題もカバーするようになる——これらの問題は元のテンプレートが作成された時点では存在しなかった。

元の4つのルール

Forrest Changのリポジトリをまだ見ていない場合は、この基本版をご覧ください：

ルール1：エンコードする前に考えましょう。

勝手に仮定を立てないでください。あなたの仮定を明確にし、トレードオフを示してください。推測する前にまず質問してください。よりシンプルな解決策がある場合は、積極的に反対意見を述べてください。

ルール2：シンプルを優先する。
問題を解決するための最小限のコードを使用する。想像上の機能を追加しない。一回限りのコードに抽象化レイヤーを設計しない。熟練したエンジニアが過剰に複雑だと感じるなら、簡素化すべきである。

ルール3：外科的手術のような修正。
必要な部分のみ変更してください。隣接するコード、コメント、フォーマットを勝手に「最適化」しないでください。壊れていないものは再構成しないでください。既存のスタイルと一致させてください。

ルール4：目標指向で実行する。
成功基準を定義し、検証が完了するまで繰り返しイテレーションする。Claudeに各ステップの実行方法を指示せず、成功の結果がどのようなものであるべきかを示し、自らイテレーションさせる。

この4つのルールにより、無監督のClaude Codeセッションで見られる約40％の失敗モードを解決できます。残り約60％の問題は、以下の空白領域に隠れています。

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

各ルールは、実際の瞬間から生まれたものだ：Karpathyの元の4つのルールでは不十分になった。以下では、まずその状況を説明し、その後に対応するルールを示す。

Karpathyのルールはこの点をカバーしていません。そのため、モデルは決定論的なコードで処理すべき問題——API呼び出しを再試行するか、メッセージをどのようにルーティングするか、処理をいつアップグレードするか——を自ら決定し始めました。その結果、毎週の判断が異なります。あなたが得るのは、1トークンあたり0.003ドルで課金される、不安定なif-elseです。

その瞬間、503エラーが発生した際に再試行すべきかを判断するためにClaudeを呼び出すコードがありました。このコードは最初の2週間は問題なく動作していましたが、その後、モデルがリクエスト本文も判断のコンテキストとして扱い始めて、突然不安定になりました。プロンプト自体がランダムになったため、再試行戦略もランダムになってしまいました。

予算制約のないCLAUDE.mdは、空白の小切手と同じです。毎回のループが制御を失い、50,000トークンのコンテキストの洪水になる可能性があります。モデルは自ら停止することはありません。

その瞬間、デバッグセッションは90分間続いた。モデルは、8KBのエラーメッセージの同じ部分を繰り返し反復し、これまでに試した修正案を次第に忘れていった。最終的に、それは40メッセージ前にもう却下した提案を再び提示し始めた。トークン予算があれば、このプロセスは12分目に終了すべきだった。

コードベースの二つの部分が矛盾している場合、Claudeは両方を満足させようとして、整合性のないコードを生成してしまう。

その瞬間、コードベースには二つのエラーハンドリングパターンが存在していた：一つはasync/awaitと明示的なtry/catch、もう一つはグローバルエラーボーダーだった。Claudeが書いた新しいコードは両方を同時に使用していた。その結果、エラーハンドリングが二重に実行されてしまった。私は30分かけて、なぜエラーが二度も無視されたのかを理解した。

カルパティの「外科手術的な修正」はClaudeに隣接するコードを変更しないように指示しているが、隣接するコードをまず理解するようには教えていない。この点が欠けていれば、Claudeは30行離れた既存のコードと矛盾する新しいコードを書き上げてしまう。

その瞬間、Claude は元の関数を読まずに、完全に同じ機能を持つ新しい関数を追加しました。二つの関数は同じことをしますが、import の順序のため、新しい関数が古い関数を上書きしてしまいました。一方、古い関数はすでに6か月間、事実上の唯一の基準として存在していました。

Karpathyの「目標指向の実行」は、テストを成功の基準として使用できることを示唆している。しかし実際には、Claudeは「テストの通過」を唯一の目標と見なし、表面的なテストは通過するが他の部分を破壊するコードを書き上げてしまう。

そのとき、Claudeは認証関数のために12個のテストを書きましたが、すべてパスしました。しかし、本番環境の認証ロジックは壊れていました。そのテストは、関数が「何かを返している」ことを確認しているだけで、正しいものを返しているかどうかを検証していませんでした。関数がテストに合格したのは、定数を返していたからです。

Karpathyのテンプレートのデフォルトのインタラクションはワンタイムです。しかし、実際のClaude Codeの作業は複数ステップにわたることが多いです：20個のファイルにまたがるリファクタリング、1つのセッション内で機能を構築、複数のコミットにまたがるデバッグ。チェックポイントがなければ、1ステップで間違えると、それまでのすべての進捗が失われる可能性があります。

その瞬間、6ステップのリファクタリングタスクが4ステップでエラーが発生しました。私が気づいたときには、Claude はエラー状態の上に5ステップと6ステップをすでに完了していました。エラーを分解して修正するのにかかった時間の方が、タスクを最初からやり直すよりも長くなりました。チェックポイントがあれば、4ステップで問題に気づけたはずです。

すでに成熟したモードを持つコードベースでは、Claude は自らの書き方を導入する傾向がある。たとえその書き方が「より良い」ものであっても、第二のモードを導入することは、いかなる単一のモードよりもはるかに悪影響を及ぼす。

その瞬間、ClaudeはclassコンポーネントベースのReactコードベースにhooksを導入しました。確かに動作しましたが、そのテストはcomponentDidMountに依存していたため、コードベースの既存のテストパターンを破壊しました。結局、削除して再実装するのに半日かかりました。

クラウドの最も高価な失敗は、成功のように見える失敗である。関数は「動く」が、誤ったデータを返す；マイグレーションは「完了」したが、30件のレコードをスキップした；テストは「合格」したが、アサーション自体が間違っていたためである。

その瞬間、Claudeはデータベースの移行が「成功しました」と述べた。しかし実際には、14%のトリガー制約違反レコードが黙ってスキップされていた。このスキップ動作はログに記録されていたが、明示的に明らかにされなかった。11日後、レポートデータに異常が生じ始めてから、私たちはこの問題に気づいた。

私は6週間の期間中に、30のコードリポジトリをカバーする同じ50の代表的なタスクを追跡し、3つの設定をテストしました。

エラー率とは、タスクが元の意図に一致するよう修正または再作成が必要であることを指します。含まれるエラーには、沈黙した誤った仮定、過剰な設計、無関係な破壊、沈黙した失敗、約束の違反、対立する妥協、チェックポイントの見落としがあります。

遵守率とは、あるルールが適用される場合に、Claudeがそのルールを明示的に適用する確率を指します。

興味深い結果は、エラー率が41%から3%に低下しただけではありません。より重要なのは、ルールを4本から12本に拡張しても、遵守の負担はほとんど増加せず、遵守率は78%から76%にわずかに低下したにすぎない一方で、エラー率はさらに8ポイント低下したことです。追加されたルールは、元の4本のルールでは対応できていなかった失敗モードをカバーしており、同じ注意リソースを競合することはありませんでした。

Karpathy テンプレートはどこで静かに機能しなくなるか

新しいルールを追加しなくても、元の4つのルールテンプレートは少なくとも4か所で不十分です。

まず、長時間実行されるAgentタスク。
カルパティのルールは、Claudeがコードを書いている瞬間に主に適用される。しかし、Claudeが複数ステップのパイプラインを実行しているときはどうなるか？元のテンプレートには予算ルールもチェックポイントルールも「大声で失敗する」ルールもない。その結果、パイプラインは徐々にずれていく。

第二に、複数のコードベースの一貫性。
「既存のスタイルに合わせる」はデフォルトで1つのスタイルのみを想定している。しかし、12のサービスを含むmonorepoでは、Claudeがどのスタイルに合わせるかを選択しなければならない。元のルールには、どのように選択すべきかの指示がなかった。そのため、Claudeはランダムに選択するか、複数のスタイルを均等に混合するしかない。

第三に、テストの品質。
「目標指向型に実行する」は「テスト通過」を成功と見なすが、テスト自体が意味を持たなければならないとは明示していない。その結果、Claudeはほとんど何を検証していないテストを書き、それらのテストによって自分自身が非常に自信があると誤解してしまう。

第四に、本番環境とプロトタイプ段階の違い。
同じ4つのルールは、本番コードが過剰に設計されるのを防ぐことができるが、プロトタイプ開発を遅らせる可能性もある。プロトタイプ段階では、方向性を確認するために一時的に100行の探索的なスキャフォールディングが必要な場合もあるからだ。Karpathyの「シンプル優先」は、初期のコードで過剰に適用されやすい。

この8つの新規則は、Karpathyの元の4つの規則を置き換えるものではなく、その空白を補うものです。元のテンプレートは2026年1月のような自動補完型のコード作成シナリオに対応していましたが、2026年5月にはClaude Codeはエージェント駆動の、複数ステップ・複数コードリポジトリの協働環境に移行しており、両者が直面する問題は異なります。

どの方法が効果がなかったですか

この12のルールを最終決定する前に、他のいくつかの案も試しました。

Reddit / X で見つけたルールに従ってください。
そのほとんどは、Karpathyの元の4つのルールを異なる表現で繰り返しているか、「常にTailwind classを使用する」のような汎用化できない分野特有のルールであり、最終的にすべて削除した。

12条以上のルール。
私は最大で18条までテストしました。14条を超えると、遵守率は76%から52%に低下しました。200行の上限は実際に存在します。この長さを超えると、Claudeは規則を一つずつ読み込むのではなく、「ここに規則がある」とパターンマッチングを開始します。

特定のツールに依存するルール。
たとえば「常に eslint を使用する」というルールは、プロジェクトに eslint がインストールされていない場合、そのルールは無効になり、静かに失敗します。その後、私はこれを具体的なツールに依存しない表現に変更し、「eslint を使用する」を「プロジェクトで既に強制されているスタイルに従う」に置き換えました。

CLAUDE.md に例を示してください。
例はルールよりも文脈をより多く消費する。3つの例が消費する文脈は、約10のルールに相当し、Claudeは例に過剰適合しやすい。ルールは抽象的であり、例は具体的である。したがって、ルールを使用すべきである。

気をつけてください。よく考えてください。集中してください。
これらはすべてノイズである。このような指示の遵守率は約30％に低下した。なぜなら、それらは検証できないからである。その後、私はそれらを「仮定を明確に述べる」などのより具体的な命令形のルールに置き換えた。

Claudeに、経験豊富なエンジニアのように振る舞うように伝えてください。
これは役に立たない。Claudeは元々自分をシニアエンジニアだと感じている。真正の問題はそれがそう思っているかどうかではなく、実際にそう行動しているかどうかである。命令的なルールはこのギャップを縮小できるが、アイデンティティのプロンプトではできない。

完全な12のルール版 CLAUDE.md

以下は、そのままコピーして貼り付けることができる完全なバージョンです。

このコンテンツは飛書ドキュメント外では表示できません。

それをリポジトリのルートディレクトリに 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 は願望リストではなく、あなたが観察した具体的な失敗パターンを防ぐための行動契約である。

各ルールは、どのようなエラーを防ぐかという質問に答えるべきである。

Karpathyの4つのルールは、2026年1月に彼が見ていた失敗パターン、すなわち沈黙の仮定、過剰なエンジニアリング、無関係な破壊、弱い成功基準を防ぐためのものである。これらは基本であり、省略してはならない。

私が追加した8つのルールは、2026年5月以降に発生する新たな失敗モードを防ぐためのものです：予算制約のないエージェントのループ、チェックポイントのない複数ステップタスク、テストしたように見せかけて重要なロジックを実際にテストしていないケース、そして沈黙した失敗を沈黙した成功として装う問題です。これらは増分パッチです。

もちろん、効果は個人によって異なります。複数ステップのパイプラインを実行しない場合、ルール10はそれほど重要ではありません。コードベースが一貫したスタイルであり、既にlintによって強制されている場合、ルール11は重複します。この12のルールを読んだ後、実際に犯したミスに実際に該当するルールのみを残し、それ以外を削除してください。

6つのルールで構成された、実際の失敗パターンに特化したCLAUDE.mdの方が、12のルールを含みそのうち6つは決して使わないバージョンよりも優れている。

まとめ

Karpathyが2026年1月に投稿したツイートは、本質的に不満の表明だった。Forrest Changはそれを4つのルールにまとめた。最終的に、12万人の開発者がこの結果にStarを付けた。しかし、その大半は、今日でもまだその4つのルールのみを使用している。

モデルは進化し、エコシステムも変わった。マルチステップエージェント、フックによる連鎖的トリガー、スキルのロード、複数コードリポジトリの協力——これらは、Karpathyがそのツイートを投稿した当時は存在しなかった。元の4つのルールは、これらの課題を解決していない。それらが間違っているわけではないが、不完全である。

8つの新しいルールを追加。6週間で30のコードベースをテスト。エラーレートが41％から3％に低下。

今晚この記事を保存し、この12のルールをあなたのCLAUDE.mdに貼り付けてください。これがClaudeの学習時間を1週間短縮するのに役立つなら、ぜひ共有してください。