Claudeの「勝手に推測・過剰実装・余計な変更」を直す Karpathy由来のCLAUDE.md 4原則【前編】
TL;DR (3行まとめ)
- AIコーディングエージェントの弱点は構文ミスではなく、「シニアエンジニアなら持っている判断力」の欠如です。
- Andrej Karpathy（元Tesla AIディレクター／OpenAI創業メンバー）の問題提起を、開発者 Forrest Chang が
CLAUDE.mdの4原則に落とし込んだものが、GitHubで16万Star超（執筆時点、2026年05月31日）のバズになりました。 - 4原則は「Think Before Coding / Simplicity First / Surgical Changes / Goal-Driven Execution」。本記事はその中身を整理する前編、実際に組み込んで手を動かす話は後編で扱います。
🚀 はじめに
こんにちは！Claude Code をはじめ、コーディングエージェントやAIと壁打ち時に、使っているとこんな経験はないでしょうか。
「バグ修正を頼んだだけなのに、関係ないインデントやコメントまで“改善”されていた」
「頼んでいない柔軟性や抽象化を勝手に足されて、100行で済む処理が1000行に膨らんだ」
「依頼していないので、勝手に裏の意味を想像して違う方向性に突っ込んでいて、トークンが大量燃やされた」
LLMは構文を書くのは得意でも、「曖昧なら確認する」「余計なことはしない」といった判断が抜け落ちがちです。
元Tesla AIディレクターの Andrej Karpathy がこの不満を X に投稿したところ大きな反響を呼び、それを開発者 Forrest Chang が CLAUDE.md という1ファイルにまとめて公開。GitHub Trending 1位、執筆時点で16万を超える Star を集めています。
本記事（前編）では、その4原則が「何を直すのか」を整理します。実際に自分のClaudeへの指示へ組み込んだ before/after は、後編で扱う予定です。
🛠️ 4原則の本質：AIに「判断力」を持たせる
Karpathy が挙げた不満は、ざっくり3つです（出典：Karpathy の X 投稿）。
- 勝手な仮定を立てて、確認せず突き進む
- コードやAPIを過剰に複雑化し、抽象を膨らませる
- タスクと無関係なコードやコメントまで、理解しないまま書き換える
これに1対1で対応するのが、以下の4原則です（原文リポジトリ）。
| 原則 | 解決する問題 |
|---|---|
| Think Before Coding | 誤った仮定・隠れた混乱・トレードオフの不提示 |
| Simplicity First | 過剰実装・肥大化した抽象 |
| Surgical Changes | 無関係な変更・触るべきでない箇所への手出し |
| Goal-Driven Execution | 「動くようにして」では弱い。検証可能な成功基準でループさせる |
ポイントは、これらが「機能の指示」ではなく「振る舞いの指示」だということです。タスクを伝える前に、AIに対して“どう振る舞ってほしいか”の土台を先に渡しておく、という発想です。
1. Think Before Coding（書く前に考える）
推測しない。混乱を隠さない。トレードオフを出す。
LLMは曖昧な指示でも、勝手に解釈を1つ選んで突き進みがちです。この原則は次を強制します。
- 前提は明示する。不確かなら推測せず質問する
- 解釈が複数あるなら、黙って1つに決めない
- もっと単純な方法があるなら、そう言う（必要なら反論する）
- 混乱したら止まる。何が不明かを名指しして確認する
「とりあえず動くものを作って、後から指摘されて直す」という後戻りを、最初の質問1つで潰すイメージです。
2. Simplicity First（まず単純に）
問題を解く最小限のコードだけ。投機的なものはなし。
- 頼まれていない機能は足さない
- 単発利用のコードに抽象化はいらない
- 要求されていない「柔軟性」「設定可能性」は持ち込まない
- 起こり得ないケースのエラー処理はしない
- 200行が50行で済むなら書き直す
判定基準：シニアエンジニアが見て「複雑すぎる」と言うか？ Yesなら単純化する。
3. Surgical Changes（外科手術的な変更）
触るべき箇所だけ触る。自分が散らかした分だけ片づける。
既存コードを編集するとき:
- 隣接するコード・コメント・整形を勝手に「改善」しない
- 壊れていないものをリファクタしない
- 自分なら違うやり方でも、既存スタイルに合わせる
- 無関係なデッドコードに気づいたら、消さずに「指摘」する
自分の変更が不要物を生んだとき:
- 自分の変更で使われなくなった import / 変数 / 関数は消す
- 元からあったデッドコードは、頼まれない限り消さない
判定基準：変更した全行が、ユーザーの依頼に直接ひもづくか。
4. Goal-Driven Execution（目標駆動の実行）
成功基準を定義し、検証されるまでループする。
命令形のタスクを、検証可能な目標に変換します。
| こう言う代わりに | こう変換する |
|---|---|
| 「バリデーションを追加して」 | 「無効な入力のテストを書いて、それを通す」 |
| 「バグを直して」 | 「バグを再現するテストを書いて、それを通す」 |
| 「Xをリファクタして」 | 「前後でテストが通ることを保証する」 |
複数ステップのタスクでは、先に短い計画を宣言させます。
1. [手順] → 検証: [確認方法]
2. [手順] → 検証: [確認方法]
3. [手順] → 検証: [確認方法]
Karpathy 曰く、LLMは「明確な目標に達するまでループするのが非常に得意」。だからこそ、やり方を細かく指示するより、成功基準を渡して走らせる方が効く、というわけです。逆に「動くようにして」のような弱い基準だと、AIは判断に迷って都度こちらに確認してきます。
🔍 効いているサイン
4原則がちゃんと効いていれば、こういう変化が見えるはずです（リポジトリの "How to Know It's Working" より）。
- diffに余計な変更が出てこない（依頼した変更だけが入る）
- 過剰実装による書き直しが減る（最初から素直なコードになる）
- 実装の「前」に確認質問が来る（ミスした「後」ではなく）
- PRが小さくきれいになる（ついでのリファクタや“改善”が混ざらない）
逆にこれらが見られないなら、原則がうまく伝わっていないサインです。
⚠️ 使うときの注意点
- リポジトリ自身が「速度より慎重さに倒した設計」と明言しています。タイプミス修正のような自明な作業にまでフル適用すると、かえって冗長になります（自明なものは判断で省く、とのこと）。
- 「テンプレとして丸写しせず、メニューとして使え」という指摘もあります。プロジェクトごとに硬直しないよう、自分の文脈に合わせて取捨選択するのが前提です。
✨ まとめ
同じAIでも、タスク指示の前に「判断の基準」を渡すかどうかで、出力の質は変わります。
- Think Before Coding：勝手な推測を禁止し、トレードオフを出させる
- Simplicity First：過剰設計を禁止し、最小限のコードや文章を書かせる
- Surgical Changes：余計なリファクタを禁止し、差分をきれいに保つ
- Goal-Driven Execution：明確な成功基準を定義し、自己検証させる
後編では、これを自分のClaudeへの指示に組み込み、同じ依頼で before/after がどう変わったかを、実際に手を動かしながら共有する予定です。
📂 付録
- 原文リポジトリ（
CLAUDE.md本体）: https://github.com/multica-ai/andrej-karpathy-skills - 元になった Karpathy の問題提起（X）: https://x.com/karpathy/status/2015883857489522876
AI利用について
本記事の構成・ドラフト作成・英日の言い換えには生成AI（Claude）を活用しています。引用元の確認・最終的な記述内容はすべて筆者が確認・校正しています。
最後まで読んでいただき、ありがとうございました！ 🙌