コードが1行も書かれていないプレーンな Markdown ファイルが、GitHub のトレンドデイリーランキングで3日連続の1位を獲得し、今週は 44,465 スターを新たに積み上げました。その名は CLAUDE.md。プロジェクトルートに置く設定ファイルで、AI コーディングが犯しがちな失敗を律する4つのルールが書かれています。

CLAUDE.md とは

CLAUDE.md は Markdown 形式の設定ファイルで、プロジェクトルートに置いておくと、AI コーディング Agent（Claude Code、Cursor など）が自動的に読み込み、そのルールに従って動作します。核心の発想は、ベテランエンジニアの暗黙知を、Agent がそのまま理解して実行できる指示としてパッケージすることです。

プロジェクトURL：https://github.com/forrestchang/andrej-karpathy-skills

4つの核心原則の詳細

このファイルの源流は、Karpathy が今年1月に X に投稿した長文スレッドで、AI コーディング Agent のさまざまな問題を詳しく指摘したものでした。中国系開発者の Jiayuan Zhang がこれを、実行可能な4つのルールへと凝縮しました。

原則1：コードを書く前に考える

問題：「バリデーション機能を追加して」と頼むと、何をどの程度厳密に検証するのかを聞かずに、いきなり最も複雑な方案を推測して、不要なコードを大量に書き上げます。

ルール：

• 不確かなときは推測せず、必ず立ち止まって質問する
• 複数の解釈があり得る場合は選択肢を挙げて選ばせ、代わりに決めない
• よりシンプルな方案が見つかったら、自分から申し出る

原則2：シンプルさを最優先する

問題：シンプルな機能を頼んだだけなのに、AI はログイン認証、セキュリティ検証、トラフィック制御まで付いた企業級アーキテクチャ一式を書いてきます。「シンプルにして」と言うと、今度は大半を即座に削り「もちろんできます」と返してきます。

ルール：

• 要求されていない機能は書かない
• 1度しか使わないコードに抽象レイヤーを作らない
• 誰も求めていない「柔軟性」や「設定可能」を付け加えない
• 起こり得ない例外シナリオにはエラー処理を書かない

検証基準：ベテランエンジニアが見て「複雑すぎる」と言うかどうか。言うなら、思い切って削ります。

原則3：正確な編集

問題：バグ修正を頼むと、AI はバグを直したついでに周辺のコードまでリファクタリングし、変数名を変え、コメントを消します。30箇所も変更したうち、25箇所はあなたの要求と無関係、という具合です。

ルール：

• 指示された部分以外は触らない
• プロジェクトの既存コードスタイルに合わせる
• 無関係な問題を見つけたら一言添えるだけで、手を出さない
• 自分の変更によって使われなくなったコードは片付けるが、以前から存在した問題には手を付けない

原則4：ゴール駆動

問題：AI は「ループして目標に達するまでやり続ける」のが得意ですが、具体的な手順まで指示すると、かえってその力を制限してしまいます。

ルール：

• 手順ではなく、受け入れ基準を渡す
• 機能追加なら：まずテストケースを書き、すべてのテストを通させる
• バグ修正なら：バグを再現するテストを先に書き、それを通させる
• 複雑なタスクなら：まず段階的な計画を列挙させ、各ステップに検証方法を持たせる

これは AI コーディングにおいてレバレッジが最も大きい原則です。受け入れ基準が明確であるほど、AI が自律的に実行できる時間が長くなり、あなたが介入する頻度は下がります。

使い方

1. CLAUDE.md ファイルをプロジェクトルートに置く
2. AI コーディング Agent が自動的に読み込み、そのルールに従って動作する
3. 自分のニーズに合わせてルールを修正・追加してもよい

# 例：CLAUDE.md にプロジェクト固有のルールを追加する

## プロジェクトの取り決め
- TypeScript strict モードを使う
- コンポーネントのファイル名は PascalCase
- API インターフェースは src/api/ ディレクトリにまとめる
- 新機能を書く前にテストを書く

なぜこんなに人気なのか

開発者の Kraggich の言葉をそのまま引用します。「Markdown ファイル1つがトレンド1位に登ったということは、今のボトルネックはモデルではなく、モデルを取り囲む足場にあるということ。この『接着剤』こそがプロダクトの本体なんです」。

別の開発者はある計算を紹介しました。モデルが間違ったブランチを選び、40分走らせた末に壁にぶつかって失敗。事前にひとこと確認しておけば30秒で済んだ話です。

Karpathy 自身の言葉では、わずか数週間で、彼のプログラミングワークフローは「手書き80%＋AI 補助20%」から「Agent に任せる80%＋自分で修正する20%」へと完全にひっくり返りました。この CLAUDE.md こそ、この逆転を本当に信頼できるものにする鍵となるツールなのです。