karpathy が X で claude について不満を述べた。forrest chang がその不満を 4 つのルールと GitHub リポジトリにまとめた。そのリポジトリは数週間で 12 万スターを獲得した。この記事を読んでいるほとんどの開発者は、今でもその 4 つのルールだけを使っている。問題は、それらが 1 月に書かれたことだ。今は 2026 年半ばであり、claude code のエコシステムは変化している。
この記事では、完全な 12 ルールの CLAUDE.md、各ルールが存在する理由、それが防ぐ障害、そして元のテンプレートが暗黙のうちに間違っている点を紹介する。最後に貼り付けて使えるようにしてある。
CLAUDE.md とは何か、そしてほとんどの人がなぜ間違っているのか
CLAUDE.md は、リポジトリのルートに配置するファイルだ。claude code はセッションごとにこれを読み込む。これはプロンプトではない。設定リストでもない。これは、claude がコードベース内でどのように振る舞うかというオペレーティングシステムである。
ほとんどの開発者は、3 つの間違った方法のいずれかを取る。これまでに持ったすべての設定をファイルに詰め込み、4,000 トークンを超えて肥大化させ、重要なルールが埋もれてコンプライアンスが 30% に低下する。完全にスキップして毎回プロンプトを再入力し、5 倍のトークンを無駄にし、一貫性をゼロにする。テンプレートを一度貼り付けて忘れ、コードベースの変化に伴い数週間で静かに壊れていくのを放置する。
公式の anthropic ドキュメントは明確に述べている：CLAUDE.md は助言的なものである。claude は 200 行未満であれば約 80% の確率で従う。200 行を超えると、コンプライアンスは急激に低下する。有用な CLAUDE.md ファイルの上限は、短く、正確で、提案ではなく直接的なルールによって強制されることにある。
元の 4 つのルール：何もないならここから始めよう
テスラの元 AI ディレクターであり OpenAI の共同設立者である andrej karpathy は、2026 年 1 月に claude code での集中的な作業の後、スレッドを投稿した。フレームワークではない。不満だ。彼が繰り返し直面した 3 つの障害モード：claude が尋ねる代わりに黙って仮定する、最小限を解決する代わりに過剰に構築する、依頼されていないコードに触れる。
forrest chang はそのスレッドを読み、ルールとして書き留めた。1 つのファイル、65 行、翌日には GitHub に上がっていた。以下がその 4 つである。
ルール 1 - コードを書く前に考える
コードを書く前に仮定を述べる。トレードオフを明らかにする。推測する前に尋ねる。よりシンプルなアプローチが存在する場合は反論する。未確認の仮定に基づいて構築してはならない。
ルール 2 - シンプルさを最優先
問題を解決する最小限のコードを書く。推測による機能は不要。1 回しか使わないコードのための抽象化は不要。シニアエンジニアが複雑すぎると言うなら、シンプルにせよ。
ルール 3 - 外科的な変更
タスクに必要なものだけに触れる。隣接するコード、コメント、フォーマットを改善してはならない。壊れていないものをリファクタリングしてはならない。既存のスタイルに完全に合わせる。
ルール 4 - 目標駆動型の実行
開始する前に成功の定義を明確にする。成功が確認されるまでループする。claude に従う手順を列挙してはならない。完了の状態を伝え、claude に道を見つけさせる。
これら 4 つのルールは、監視なしの claude code セッションにおける障害モードの約 40% を防ぐ。残りの 60% は、元のテンプレートが対処していないギャップに存在する。なぜなら、karpathy がスレッドを投稿した時点では、それらの問題は完全には存在していなかったからだ。
元のテンプレートを拡張する必要がある理由
4 つの karpathy ルールは、単一エージェントのコード作成セッションを修正するために作られた。2026 年の claude code エコシステムは、マルチエージェント設定、フック、スキルライブラリ、セッションをまたがるマルチステップワークフローを実行する。元のテンプレートは、それらのいずれについても何も述べていない。
元のルールには 4 つの具体的なギャップが現れる。第一に、エージェント間の競合：所有権ルールなしに同じファイルを編集する 2 つのエージェントが、互いの変更を静かに上書きする。第二に、フックのカスケード：すべてのツール呼び出しで発火するフックが、200 トークンのリクエストを 8,000 トークンに変え、それを止める予算がない。第三に、スキル読み込みの競合：類似した説明を持つ複数のスキルがディスパッチャを混乱させ、間違ったものを読み込む。第四に、マルチステップセッションの中断：6 ステップのリファクタリングがステップ 4 で失敗するが、ステップ 5 と 6 はそのまま実行され、壊れた状態の上に構築される。
元の 4 つのルールは間違っていない。不完全なのである。以下の 8 つの追加ルールが、これらの具体的なギャップを埋める。
8 つの新しいルール：それぞれが何を防ぐか
ルール 5 - 言語以外の作業にモデルを使用しない
決定論的な判断は決定論的なコードに属する。リトライロジック、ルーティングしきい値、エスカレーションルール、ステータスベースの分岐：これらのいずれも LLM 呼び出しであるべきではない。モデルは毎週、コンテキストウィンドウ内の内容に基づいて異なる判断を下す。一貫した動作に見えるものは、実際にはまだ表面化していないばらつきである。
具体的なインシデント：「503 でリトライするかどうかを判断する」LLM 呼び出しは 2 週間正常に動作した後、モデルがリクエスト本文をリトライ判断のコンテキストとして読み始めたため、ランダムな動作を生成し始めた。実効的な入力がランダムになったため、ポリシーはランダムになった。
これを CLAUDE.md に追加せよ：
ルーティング、リトライロジック、ステータスベースの分岐、しきい値の判断は、モデル呼び出しではなくコードに属する。判断の出力が二値的であるか、固定ルールに従う場合は、そのルールをコードで記述せよ。
ルール 6 - 厳格なトークン予算、例外なし
すべてのエージェントループにはスパイラルする可能性がある。claude は 90 分のデバッグセッションを自ら停止することはない。反復するように指示されているため、反復し続ける。トークン予算は、強制停止を強制する唯一のメカニズムである。
具体的なインシデント：同じ 8KB のエラーメッセージを 90 分間ループするデバッグセッション。終盤には、claude は 2 時間前に試して放棄した修正を提案していた。コンテキストが満杯で、自身の推論を見失っていた。
これを追加せよ：
すべてのエージェントセッションには厳格なトークン予算がある。予算に達しても検証済みの解決策がない場合は、調査結果をファイルに要約して終了せよ。予算を超えて続行してはならない。
ルール 7 - 1 エージェント、1 ディレクトリ
2 つのエージェントが同時に同じディレクトリに触れると、静かな状態破損が発生する。一方のエージェントがファイルを書き込んでいる間に、もう一方がそれを読み取る。結果は、どちらのエージェントも予期せず、気付かないデータとなる。
git worktrees を使用せよ。2 つ目のエージェントを起動する前に git worktree add ../agent-2-branch feature-branch を実行せよ。各エージェントは、自身のブランチを指す独立した作業ディレクトリを取得する。エージェントはファイルシステムを共有しない。
これを追加せよ：
並行して実行されるエージェントは、別々の git worktree で作業する。2 つのエージェントが同時に同じディレクトリに触れてはならない。各エージェントは自身のブランチを所有する。
ルール 8 - マルチステップ作業にはチェックポイントファイルを書く
3 ステップより長いタスクにはチェックポイントファイルが必要である。claude は各ステップの後、完了したこと、発見したこと、次に行うことをファイルに書き込む。セッションがステップ 4 で終了または中断した場合、次のセッションはチェックポイントを読み取り、ステップ 4 から続行する。チェックポイントがないと、再起動するたびにステップ 1 に戻る。
マルチステップタスクを開始する前に、作業ディレクトリに PROGRESS.md というファイルを作成せよ。CLAUDE.md で claude に指示せよ：
3 ステップより長いタスクの場合、各ステップの後に PROGRESS.md ファイルを書け。含める内容：何をしたか、何を見つけたか、次に何をするか、何がブロックされているか。セッションが完了前に終了した場合、次のセッションは最初に PROGRESS.md を読み、中断したところから続行する。
ルール 9 - 大きく失敗するか、まったく失敗しないか
claude は成功しているように見せかける強い傾向がある。実際には気にしていることをテストしていないテストをパスする。エラーが発生したファイルを静かにスキップしながらマイグレーションを完了する。80% しか完了していないタスクを「完了」と報告する。
ルール：成功基準が検証できない場合、タスクは完了していない。ステップが失敗した場合、続行する前に停止し、具体的な内容を報告せよ。エラーをごまかしてはならない。
これを追加せよ：
失敗したステップを超えて続行してはならない。テストがパスしても実際の動作をカバーしていない場合は、その旨を述べよ。マイグレーションがファイルをスキップした場合は、スキップされたファイルをリストアップして停止せよ。成功とは、報告されたことではなく、検証可能であることである。
ルール 10 - スキルの説明は一意でなければならない
スキルは説明のマッチングによって読み込まれる。2 つのスキルに重複する説明がある場合、ディスパッチャは任意に一方を選択する。間違ったスキルが読み込まれ、タスクは誤った指示で実行され、エラーはスローされないため、エラーは決して表示されない。
他のどのスキルとも一致しない言語で、各スキルの役割を命名せよ。「データベースクエリヘルパー」と「データベースマイグレーションヘルパー」は競合する。「本番データベースに対して読み取り専用の SQL クエリを実行する」と「ロールバック付きのスキーママイグレーションスクリプトを実行および検証する」は競合しない。
これを追加せよ：
各スキルの説明は、その役割を一意に識別できなければならない。同じタスクに適用できる可能性のある説明を持つスキルが 2 つあってはならない。2 つのスキルが類似しているように聞こえる場合、デプロイ前にそのうちの 1 つを改名する必要がある。
ルール 11 - リサーチャーとライターを分離する
コンテキスト汚染は現実である。claude が同じセッションでリサーチとライティングを行うと、リサーチノイズがライティングを低下させる。脱線を取り込み、必要のない結論を曖昧にし、新たに始めた場合に持っていたであろう明確な議論の筋を失う。
5 つ以上のファイルを読むか、2 つ以上のソースにクエリを実行する必要があるタスクには、リサーチサブエージェントを起動せよ。構造化されたレポートを取得せよ。コンテキストにレポートのみを含めて、ライティングまたは実装のためのクリーンなセッションを開始せよ。
これを追加せよ：
リサーチと実装は別々のセッションである。リサーチャーサブエージェントがファイルを読み、クエリを実行し、構造化されたサマリーを返す。実装セッションは、そのサマリーを唯一の入力として新たに開始する。リサーチとライティングを 1 つのセッションに決して統合してはならない。
ルール 12 - フックにも予算が必要
フックはすべてのツール呼び出しで発火する。ファイル書き込みごとにリンター、フォーマッター、ログライター、セキュリティスキャンを実行するフックは、ツール呼び出しごとに 4 つのプロセスを実行している。200 回のツール呼び出しがあるセッションでは、800 のプロセスがバックグラウンドで実行され、そのほとんどは冗長で、すべてがトークンを消費する。
追加するすべてのフックにはスコープ条件が必要である：特定のディレクトリへのファイル書き込みでのみ実行、特定のファイル拡張子が触れられた場合のみ実行、すべてのツール呼び出し後ではなくセッション終了後にのみ実行。スコープ条件のないフックは、セッションパフォーマンスを目に見えない形で低下させる。
これを追加せよ：
すべてのフックには明示的なスコープ条件がある。どのフックも、すべてのツール呼び出しで無条件に実行されてはならない。ログはセッション終了時にバッチ処理せよ。リンターは変更されたファイルのみで実行せよ。セキュリティチェックはテストディレクトリ外のファイルのみで実行せよ。
完全版 12 ルール CLAUDE.md - これを貼り付けよ
このファイルをリポジトリルートにコピーせよ。括弧でマークされたセクションを埋めよ。ファイル全体は 100 行未満に保ち、コンプライアンスを 80% 以上に維持せよ。
CLAUDE.md
プロジェクト
[1 文：このコードベースが何をするか、使用するテクノロジースタック]
行動ルール
コードを書く前に考える
コードを書く前に仮定を述べる。トレードオフを明らかにする。アーキテクチャやデータに影響を与えるものについては、推測する前に尋ねる。よりシンプルなアプローチが存在する場合は反論する。
シンプルさを最優先
問題を解決する最小限のコードを書く。推測による機能は不要。1 回しか使わないコードのための抽象化は不要。シニアエンジニアが複雑すぎると言うなら、シンプルにせよ。
外科的な変更
タスクに必要なものだけに触れる。依頼の一部ではなかった隣接するコード、フォーマット、コメント、命名を改善してはならない。既存のコードスタイルに完全に合わせる。
目標駆動型の実行
開始する前に成功の定義を明確にする。その定義が満たされ、検証されるまでループする。ステップバイステップの指示を求めない。道を見つけ出せ。
決定論的判断にモデル呼び出しを使用しない
ルーティング、リトライロジック、ステータスベースの分岐、しきい値の判断は、LLM 呼び出しではなくコードに属する。ルールを記述できるなら、記述せよ。
厳格なトークン予算
すべてのセッションには厳格なトークン制限がある：[数値を設定せよ、例：50,000 トークン]。制限に達しても検証済みの解決策がない場合は、調査結果をファイルに書き込んで停止せよ。予算を超えて続行してはならない。
1 エージェント、1 ディレクトリ
並行して実行されるエージェントは、別々の git worktree で作業する。2 つのエージェントがディレクトリを共有してはならない。2 つ目のエージェントが必要な場合は、以下を実行せよ：git worktree add ../agent-2 [ブランチ名]
マルチステップ作業のチェックポイント
3 ステップより長いタスクの場合は、作業ディレクトリに PROGRESS.md を作成せよ。各ステップの後に書き込む：何をしたか、何を見つけたか、次に何をするか、何がブロックされているか。セッションが完了前に終了した場合、次のセッションは最初に PROGRESS.md を読む。
大きく失敗する
ステップが失敗した場合、続行する前に停止し、具体的な内容を報告せよ。テストがパスしても実際の動作をカバーしていない場合は、その旨を述べよ。成功とは、報告されたことではなく、検証可能であることである。
一意のスキル説明
各スキルは正確に 1 つの役割をカバーする。その説明は、プロジェクト内の他のどのスキルにも適用できてはならない。2 つのスキルの説明が重複する場合は、デプロイ前に改名せよ。
リサーチと実装は別々のセッション
5 つ以上のファイルを読むか、2 つ以上のソースにクエリを実行する必要があるタスクには、サブエージェントを使用せよ。構造化されたレポートを取得せよ。実装のために、そのレポートのみを入力としてクリーンなセッションを開始せよ。
スコープ付きフックのみ
すべてのフックには明示的な条件がある：ファイル拡張子、ディレクトリパス、またはセッションイベント。どのフックも、すべてのツール呼び出しで無条件に実行されてはならない。可能な場合は、ログをセッション終了時にバッチ処理せよ。
触れてはならないもの
[claude が決して変更すべきではないディレクトリまたはファイルをリストアップせよ：例：/secrets、/migrations/archive、/prod-config]
成功基準のデフォルト
タスクが完了したかどうか疑問がある場合：テストはパスするか、ビルドは成功するか、出力は claude 自身の判断以外のもので検証可能か？これらのいずれかに「いいえ」の場合、完了していない。
元のテンプレートが静かに壊れる 4 つの場所
元の 4 つのルールだけでも、テンプレートが誤った動作を生成し、それを伝えない特定の条件が 4 つ存在する。
第一に：コンテキストが蓄積された長時間のセッション。karpathy の目標駆動型実行ルールは、claude に検証されるまでループするよう指示する。長時間のセッションでは、コンテキストが満杯になるにつれて「検証済み」が曖昧になる。claude は、本来すべきことの劣化したモデルに対して検証を開始する。修正はルール 6（トークン予算）による強制停止である。
第二に：マルチエージェント設定。外科的な変更ルールは、各エージェントに必要なものだけに触れるよう指示する。しかし、2 つのエージェントとディレクトリ所有権ルールがない場合、「必要なもの」は重複する。ルール 7（1 エージェント、1 ディレクトリ）が欠けている部分である。
第三に：類似した役割を持つ並行スキル。元のテンプレートにはスキルに関する記述がない。ルール 10（一意のスキル説明）がディスパッチャの曖昧さのギャップを埋める。
第四に：タスク途中で終了するセッション。目標駆動型実行は、セッションが完了まで実行されることを前提としている。セッションが 8 ステップ中のステップ 4 で終了した場合の指示がない。ルール 8（チェックポイントファイル）が次のセッションに開始点を提供する。
これらはいずれも元のルールのバグではない。元のルールがカバーするように書かれていなかったギャップである。
GitHub スターを説明する数字
12 万人の開発者が 65 行のテキストファイルにスターを付けた。コードなし。ライブラリなし。フレームワークなし。4 つのルールが書かれた 1 つのファイル。
それを説明する数字：CLAUDE.md なしの監視なし claude code セッションでのエラー率 41%。元の 4 つのルールで 11%。完全な 12 ルールで 3%。
エラーが 38 ポイント減少することは、わずかな改善ではない。実際の本番作業で claude code を実行しているチームにとって、これは、一晩中信頼して実行できるエージェントと、常に監視しなければならないエージェントの違いである。
この記事の最後にあるファイルは、貼り付けて埋めるのに 5 分もかからない。それを実行した後の最初のセッションは、違ったものに感じられるだろう。モデルが変わったからではない。モデルがついにあなたの世界の仕組みを理解したからだ。
この記事をブックマークして、今夜 12 のルールを CLAUDE.md に貼り付けてください。
役に立ったと思ったら、リポストしてください。
