Karpathy の 65 行の CLAUDE.md：AI コーディングで三つの典型的なミスを減らす

Sun, 19 Apr 2026 18:27:23 +0800

最近、AI コーディングに関する GitHub プロジェクトが注目を集めている。中心にあるのは複雑なコードではなく、およそ 65 行の CLAUDE.md ファイルだ。このプロジェクトが多くの star を集めた理由は、技術実装の複雑さではない。AI にコードを書かせるとき、多くの人が繰り返し遭遇する問題をうまく捉えているからだ。

背景には、Andrej Karpathy による AI コーディングへの観察がある。Karpathy は AI 分野で大きな影響力を持つ教育者でありエンジニアだ。スタンフォード大学の博士で、OpenAI の初期にも関わり、Tesla では Autopilot の視覚システムを担当した。その後も大規模モデル、教育、AI ツールについて発信を続けているため、彼がプログラミング手法の変化について語ると、多くの開発者が注目する。

彼は、Claude Code を数週間使ったあと、自分のプログラミングスタイルが大きく変わったと述べている。以前はおよそ 80% を手書きし、20% を AI に補助させていた。今は 80% を AI に書かせ、自分は 20% を修正する感覚に近いという。自然言語で LLM に何を書くべきか伝えるので、「英語でプログラミングしている」ようなものだと表現している。

一方で、彼は AI コーディングにありがちな問題も指摘している。

01 誤った仮定

一つ目の問題は、モデルがユーザーの代わりに勝手な仮定を置き、その仮定に沿って書き進めてしまうことだ。モデルは必ずしも自分の混乱を管理しないし、要件が曖昧なときに立ち止まって質問するとも限らない。

たとえばユーザーが「ユーザーのエクスポート機能を追加して」とだけ言った場合、モデルは全ユーザーを出力する、JSON 形式にする、ローカルファイルに書き出す、権限や項目は確認不要だ、と勝手に決めるかもしれない。コードが完成してから、ユーザーはモデルの理解が実際のシナリオとずれていたことに気づく。

よりよい進め方は、不確かな点を先に列挙することだ。全ユーザーを出力するのか、フィルタ後の結果なのか。ブラウザでダウンロードするのか、バックグラウンドジョブなのか。必要な項目は何か。データ量はどれくらいか。権限制御はあるのか。こうした点を確認しないまま速く書いても、ずれが大きくなるだけだ。

02 過度な複雑化

二つ目の問題は、モデルが簡単な問題を複雑にしがちなことだ。一つの関数で済む問題に対して、抽象クラス、ストラテジーパターン、ファクトリーパターン、設定レイヤー、将来使うかもしれない拡張ポイントを山ほど追加することがある。

こうしたコードは一見エンジニアリングされているように見えるが、実際には保守コストを増やす。AI は大量の構造を素早く生成するのが得意だが、その構造が本当に必要かを常に判断できるわけではない。その結果、100 行で済むタスクが 1,000 行に膨らむ。

判断基準はシンプルだ。経験あるエンジニアがその変更を見て、過剰設計だと感じるかどうか。答えが yes なら、余分な層を削り、今の問題を解くために必要な最小限のコードに戻すべきだ。

03 付随的な被害

三つ目の問題は、モデルが十分に理解していないコードを変更したり削除したりすることだ。小さな bug を直している途中で、ついでにコメントを変えたり、フォーマットを整えたり、未使用に見える import を消したり、現在のタスクと無関係なロジックにまで手を入れることがある。

こうした「ついでの改善」は危険だ。変更範囲を広げ、レビューを難しくするからだ。ユーザーは空の email でバリデータが落ちる問題だけを直したいのに、モデルが email 検証を強化し、ユーザー名検証を追加し、ドキュメント文字列まで書き換えると、どの行が挙動を変えたのか分かりにくくなる。

より安全な原則は、必要なコードだけを変更し、自分の変更によって生まれた問題だけを片付けることだ。もともと存在していた dead code、フォーマットの問題、歴史的な負債は、明示的に依頼されていない限り触らない。必要なら一言指摘するだけでよい。

04 不満を CLAUDE.md に変える

Karpathy の見解が広く共有されたあと、開発者の Forrest Cheung は賢いことをした。これらの不満を、実行可能な行動指針として整理し、CLAUDE.md ファイルに書き込んだのだ。

このプロジェクトには複雑なコードはない。重要なのは、AI コーディングで問題が起きやすい部分を、明確な作業ルールに変えたことだ。大きく四つの原則にまとめられる。

一つ目は、書く前に考えること。黙って仮定しない。混乱を隠さない。要件に複数の解釈があるなら列挙する。より簡単な案があるなら伝える。確認が必要なら質問し、反論すべきときは反論する。

二つ目は、シンプルさを優先すること。求められていない機能を追加しない。一度しか使わないコードを抽象化しない。余計な設定を増やさない。ほぼ起きないケースのために大量の防御コードを書かない。50 行で済むなら 200 行にしない。

三つ目は、正確に変更すること。すべての変更行は、ユーザーの依頼に直接結びついているべきだ。近くのコードをついでに改善しない。壊れていないものをリファクタリングしない。できるだけ既存プロジェクトのスタイルに合わせる。

四つ目は、目標駆動で進めること。モデルに曖昧な指示だけを渡すのではなく、検証可能な成功基準を与える。たとえば「bug を直す」は「bug を再現するテストを書き、それを通す」にできる。「バリデーションを追加する」は「不正入力のテストを書き、それを通す」にできる。成功基準が明確なほど、モデルは完了に向けて自分でループしやすくなる。

05 なぜ広まったのか

このプロジェクトが広まったのは、内容が難解だからではない。実際の開発に近いからだ。

AI にコードを書かせたことがある人の多くは、似た場面を経験している。モデルが自信満々に要件を誤解する。コードがどんどん複雑になる。触るべきでない場所を変更する。CLAUDE.md の価値は、こうした経験をプロジェクトに置ける協作ルールに変えたことにある。

導入の敷居も低い。複雑な連携は不要で、一つのファイルから始められる。Karpathy 本人の影響力に加え、プロジェクト内に実践的な比較例があるため、Claude Code ユーザーや AI コーディングコミュニティの間で自然に広まった。

さらに重要なのは、この種のルールが Claude Code だけに限られないことだ。どの AI コーディングツールを使っても、本質的な問題は似ている。モデルは、いつ質問すべきか、いつ単純化すべきか、いつ手を止めるべきか、どうやってタスク完了を判断するかを知る必要がある。

06 普通の開発者への示唆

普通の開発者にとっての示唆はシンプルだ。AI コーディングは、一文の要件をモデルに投げて奇跡を待つものではない。本当に有効なのは、モデルに境界を与えることだ。

要件が不明確なときは、まず仮定を表に出させる。実装が複雑になり始めたら、最小の実用解に戻らせる。コードを変更するときは、タスクの目的だけに集中させる。完了時には、テスト、コマンド、明確なチェックポイントで結果を検証する。

AI がコードを書く能力はすでに高い。それでも、よい協作上の制約は必要だ。短い CLAUDE.md がこれほど注目されたことは、開発者が求めているのはより賢いモデルだけではなく、より信頼できる作業方法でもあることを示している。

簡単にまとめると：

書く前に考え、誤った仮定を減らす。
シンプルさを優先し、過度な設計を避ける。
正確に変更し、変更範囲を制御する。
検証可能な成功基準で、目標に向かって進める。

この四つは複雑ではないが、実用的だ。AI コーディングが本当に効率を上げる前提は、モデルにより多く書かせることではない。より正確に、より少なく、より制御された形で書かせることだ。