Claude Codeの暴走を止める1つのファイル——Karpathy発、7万スターのCLAUDE.mdを読み解く

Claude Codeに長めの実装を任せると、誰しも一度は経験する。「頼んだのは50行の修正なのに、500行の抽象化が返ってきた」。不要なヘルパークラスが増殖し、触っていないはずのファイルにコメントが書き換えられ、意図しない依存パッケージがpackage.jsonに追加されている。

Andrej Karpathy——元Tesla AI Director、元OpenAI研究者——が2026年1月にXへ投稿した一連の観察が、この問題を端的に言い当てた。「LLMは自分の混乱を管理しない。曖昧さを黙って飲み込み、仮定の上に仮定を重ねて突っ走る」。

この投稿に触発された開発者Forrest Changが、Karpathyの指摘を1つのCLAUDE.mdファイルに凝縮した。リポジトリ名はandrej-karpathy-skills。公開から1週間で44,000スターを獲得してGitHub週間ランキング2位に入り、4月25日時点で累計7万スターを超えている。Markdownファイル1つにこれだけの支持が集まるのは異例だ。

Karpathyが指摘した3つの失敗パターン

CLAUDE.mdの中身を読む前に、元になったKarpathyの観察を整理しておく。彼はコーディングの8割をAIエージェントに移行した結果、LLMに共通する3つの失敗パターンを見つけた。

1. 沈黙の誤仮定

前提が曖昧なまま「たぶんこうだろう」と実装を進める。矛盾があっても指摘せず、トレードオフも提示しない。ユーザーが気づいたときには、間違った前提の上に数百行のコードが積み上がっている。

2. 過剰な複雑化

100行で済む処理に1,000行の抽象化を被せる。使われないインターフェースを先回りして作り、デッドコードを残し、依存パッケージを勝手に追加する。

3. 巻き添え変更

タスクと無関係なファイルのコメントを書き換えたり、既存コードを「改善」として整理したりする。diff を見て初めて気づく類の変更が紛れ込む。

正直、Claude Codeに限った話ではない。Cursor、Copilot、Codexでも程度の差はあれ同じことが起きる。LLMの「親切にしよう」という傾向が、コーディングでは裏目に出る場面だ。

CLAUDE.mdの4原則

Forrest Changはこれらの問題に対して、4つの原則をCLAUDE.mdに定義した。

原則1: Think Before Coding（考えてから書け）

仮定を明示的に述べること。曖昧さがあれば推測ではなく質問すること。複数の解釈がありうるなら選択肢を提示すること。より単純なアプローチがあるなら提案すること。

これだけで「沈黙の誤仮定」がかなり減る。LLMは指示がなければ「最も可能性が高い解釈」で突き進むが、「不確かなら聞け」と書くだけで挙動が変わる。

原則2: Simplicity First（最小限のコードで解決しろ）

問題を解決する最小のコードを書く。投機的な実装をしない。触る必要があるファイルだけ触る。自分が散らかしたものだけ片付ける。

原則3: Surgical Changes（外科的な変更に留めろ）

変更した行すべてがユーザーのリクエストに直接紐づくこと。無関係な「改善」を混ぜない。

原則4: Goal-Driven Execution（成功基準を定義してからループしろ）

成功基準を定義し、検証するまでループする。「たぶん動くだろう」で終わらせない。

個々の原則は目新しくない。だが「1つのファイルにまとめてClaude Codeに読ませる」という形式が効いた。毎回プロンプトで指示するのではなく、プロジェクトルートにCLAUDE.mdを置くだけで全セッションに適用される。

導入は30秒で終わる

Claude Codeのプラグイン機能を使えば、導入は簡単だ。Claude Code内で/pluginを開き、リポジトリURLを指定してインストールする。あるいはもっと手軽に、リポジトリのCLAUDE.mdの内容をコピーして、自分のプロジェクトのCLAUDE.mdに貼り付けるだけでもいい。

導入後にClaude Codeを起動すると、セッション開始時にCLAUDE.mdが読み込まれる。以降、4原則に沿った挙動がデフォルトになる。

実際に何が変わるのか

筆者が数日間使った感触では、もっとも効果があったのは「質問が増えた」こと。以前なら勝手に解釈して実装を始めていた場面で、「この部分は2通りの解釈があります。どちらですか？」と聞いてくるようになった。

一方で、毎回確認を求められると作業のテンポが落ちる場面もある。単純な修正まで「前提を明示しますね」と前置きが入ると、やや冗長に感じる。原則をそのまま適用するよりも、自分のプロジェクトに合わせて「この領域は自律的に判断してよい」と例外を追記するのがよさそうだ。

7万スターが意味すること

このリポジトリの人気は、コードではなく「AIの行動を制御する設計書」に需要があることを示している。プロンプトエンジニアリングが1回のやりとりを最適化する技術だとすれば、CLAUDE.mdは「AIの性格を定義する」技術だ。

Claude Codeに限らず、CursorにはCursor Rules、GitHub Copilotにはカスタムインストラクション、Codexにはルールファイルがある。いずれもAIの振る舞いをプロジェクトレベルで標準化する仕組みだ。Karpathyのスキルファイルが示したのは、こうした設定ファイルの重要性が臨界点に達したということだろう。

チームでClaude Codeを使っている場合、CLAUDE.mdをリポジトリにコミットすれば全員のAIの挙動が揃う。コーディング規約と同じように「AI規約」を管理する時代が、もう始まっている。