こんな経験、ありませんか？
- Claude CodeやCursorに「ログイン機能を追加して」と頼んだら、聞かずに勝手にJWT認証を実装されていた。
- 「このバグを直して」と頼んだら、バグ修正だけでなく周囲のコードまでリファクタリングされ、差分が爆発してレビューできなくなった。
- 「もっと良くして」と頼んだら、頼んでもいない抽象クラスや拡張ポイントが追加され、シンプルだったコードが過剰設計の塊になった。
AIコーディングエージェントを日常的に使っているエンジニアなら、おそらく全員が一度は経験しているはずです。
先週からGitHubで、ある1つのリポジトリが爆発的にスターを集めています。名前は Andrej Karpathy Skills。たった 65行のMarkdownファイル1枚 で構成されたリポジトリですが、本記事執筆時点で 9万を超えるスター がついています。
このたった1枚のテキストファイルだけで、AIコーディングの性能がドラマチックに改善されると、開発者の間で大きな話題になっているのです。しかも構造があまりにもシンプルなので、Claude Code・Cursor・Codex など、どのAIコーディングエージェントにもそのまま流用できる ことが大きな特徴です。
この記事では、Karpathyの65行Markdownがどう構成されていて、どんな原理でAIコーディングの品質を変えるのか を、エンジニア視点で分解していきます。
1. なぜこのリポジトリが生まれたのか
このリポジトリは、OpenAI共同創業者で元TeslaのAIディレクターでもあるAndrej Karpathy本人が、自分でAIコーディングエージェントを使い込んだ上で感じた「不満」から生まれています。
Karpathyは自身のXで、Claude CodeのようなAIコーディングエージェントの限界を以下のように整理しています。
- 詰まっても質問しない：分からないこと・選択肢があるときに、ユーザーに尋ねず勝手にコードを書き始める。
- 誤った仮定で突き進む：その仮定の上にどんどんコードを積み上げ、後から修正が困難になる。
- 必要以上に複雑なコードを書く：単純な関数で済むものを抽象クラスや拡張機構で覆い隠す。
- 関係ないコードまで“ついでに”修正する：バグ修正と称してフォーマッタ・スタイル・コメントまで書き換えてしまう。
そして、ユーザー側にも問題があると指摘しています。
- 目標を伝えず「いい感じにして」と頼んでしまう
つまり「AIの暴走」と「ユーザーの曖昧な指示」が掛け算され、結果としてレビュー不能なPRが量産されていく ― これが現状のAIコーディングの実態だ、というのが彼の問題意識です。
そこでKarpathyは、これらの問題を一貫して抑え込むための 4つの原則 を作り、1枚のMarkdown文書として配布しました。それが今回紹介する Karpathy Skills です。
2. 4つの原則 ― AIを「自由に走らせない」設計
ここがこの記事の本題です。65行のMarkdownの中身を、原則ごとに見ていきます。
2-1. Think Before Coding — まずコードを書く前に考えさせる
核心：AIに「とりあえずコードを書くな、まず考えろ」と指示する。
LLMはユーザーの要求が曖昧でも、聞き返さず自己流に解釈して突っ走ります。
たとえば「ログイン機能を追加して」と言ったとき、実装の選択肢は複数あります。
| 選択肢 | 特徴 |
|---|---|
| JWT認証 | ステートレス、トークンベース |
| OAuth | 外部IDプロバイダ連携 |
| セッション認証 | サーバ側でセッション管理 |
放っておくと、AIはこの中から 勝手に1つを選んで実装してしまいます。後から「いやそうじゃなくて……」となるのは日常茶飯事です。
この原則では、AIに対して次のように振る舞うことを要求します。
- 不明点や選択肢がある場合は、勝手に推測しない。
- 利用可能なオプションを ユーザーに提示する。
- ユーザーの決定を待ってから実装に進む。
要するに、「分からない時に黙って進める」というAIの悪癖を、最初に潰す ための原則です。
2-2. Simplicity First — 必要な分だけ書かせる
核心：AIは“賢く見えるコード”を書きたがる。それを禁止する。
AIコーディングエージェントは、放っておくと過剰設計をします。
- 単純な関数で済むものを抽象クラスにする。
- 拡張可能性のためにインターフェイスを切る。
- 「将来必要になるかもしれない」機能を勝手に足す。
一見すると“良いコード”に見えますが、実際には次のような問題が発生します。
- ユーザーが頼んでいない機能の 保守コストだけが増える。
- 不要な抽象化により、人間にとってむしろ読みづらいコード になる。
- 設計判断のレビューが必要になり、 PRが重くなる。
ユーザーの依頼：「設定値を読み込む関数を1つ追加して」
NG な AI の挙動：
- ConfigLoader インターフェイスを切る
- JsonConfigLoader / YamlConfigLoader を実装する
- DIコンテナに登録する仕組みを足す
- 将来用に CacheableConfigLoader を用意する
OK な AI の挙動：
- 設定値を読む関数を 1 つ書いて終わる
この原則は、「スマートに見えるコード」ではなく「必要十分なコード」を書け と AI に命令することで、過剰設計・コードの肥大化・不要な抽象化を抑えます。
2-3. Surgical Changes — 必要な箇所だけ、外科手術のように変更する
核心：AIに「ついでに直しておきました」をやめさせる。
「このバグを直して」と頼んだとき、AIはしばしば次のような挙動を取ります。
- バグ箇所の隣にあるコードまでリファクタリング。
- コメントやフォーマットも勝手に変更。
- 既存のコードスタイルを“自分好み”に書き換える。
レビュアーの立場で見ると、これは悪夢です。
- 出力されるコードの量が そもそも多すぎる。
- やっと差分を理解したと思ったら、次のPRでまた大量の変更。
- 「どの変更がバグ修正で」「どの変更がAIの趣味なのか」 境界が見えなくなる。
差分の見え方：
+ バグ修正の本質的な 5 行
+ ついでにリファクタした 80 行
+ フォーマット変更による 200 行
+ コメント書き換え 30 行
実際にレビューしたいのは最初の 5 行だけ
こうなるとレビュー速度は落ち、いつしか コーディングの主導権をAIに渡してしまう ことになります。「動いてはいるが、自分では説明できないコード」が増えていく状態です。
この原則は、人間がレビュー可能な速度と範囲にAIを合わせさせる ためのものです。AIに対して「外科医のように、必要な部分だけを修正せよ」と命じます。
2-4. Goal-Oriented Execution — 目標を立て、目標で検証させる
核心：曖昧な指示を、AI自身が「検証可能な目標」に変換させる。
Karpathyが指摘しているもう一方の問題、つまり ユーザー側の曖昧な指示 に対応する原則です。
ユーザーは AI に対してこう言いがちです。
- 「直して」
- 「良くして」
- 「いい感じにして」
AIはこの曖昧な指示を受け取った瞬間、「止まって確認する」ではなく「適当に解釈して走り出す」 という挙動を取ります。
そこで本原則では、AIに以下のフローを強制します。
- ユーザーの曖昧な指示を、検証可能な形に書き直す。
- その目標に対するテストやチェックを 先に書く / 計画する。
- 実装する。
- 立てた目標を 満たしているかを自分で検証する。
たとえば「このバグを直して」という指示は、次のように展開されます。
| ステップ | 内容 |
|---|---|
| 1 | バグを再現するテストを書く |
| 2 | テストを実行し、失敗することを確認する |
| 3 | バグを修正する |
| 4 | 同じテストが通ることを確認する |
| 5 | 関連箇所の挙動を検証する |
これにより AI は「コードをいじっただけで終わり」ではなく、バグが存在していたことの証明 → 修正 → 修正されたことの証明 をワンセットで行うようになります。
これが Goal-Oriented Execution、つまり「成功条件を明確に定義してから実装させる」というアプローチです。
3. なぜこの65行が効くのか ― ハーネス・エンジニアリングという視点
ここまで4つの原則を見てきましたが、内容自体は新しいものではありません。むしろ、エンジニアが普段やっている当たり前のことを言語化しただけです。
ではなぜこれが9万スターを集めるのか。
それは、このMarkdownが「AIに能力を足すもの」ではなく、「AIから自由を奪うもの」だからです。
従来のプロンプト：
「いい感じにコードを書いてくれ」
→ AI が高い自由度で暴走
→ 過剰設計・暴走リファクタ・曖昧な完成判定
Karpathy Skills 適用後：
「考える → 質問する → 最小限書く → 必要な箇所だけ触る → 目標で検証する」
→ AI の振る舞いがハーネス（馬具）で拘束される
→ レビュー可能な速度と範囲に揃う
AI は コードが書けないのではなく、書きすぎる・速すぎる・自信を持ちすぎる 存在です。だから本当に必要なのは、AIに「もっとできる」ようにすることではなく、「正しい方向に走らせる」ためのレーン を引いてやることです。
これを ハーネス・エンジニアリング（Harness Engineering） と呼びます。やっていることは次のような作業です。
- 走るべきレーンを定義する（原則1, 2）
- 範囲を絞り込むハーネスを付ける（原則3）
- ゴール地点とチェックポイントを設置する（原則4）
- 最終的にテストで合格を確認する
Karpathyの65行は、これらをコードでもライブラリでもなく、たった1枚のMarkdownで実現 しているところに本質があります。
4. 実際にどう使うか
Claude Code・Cursor・Codex などのAIコーディングエージェントには、共通して プロジェクトルートに置く設定用Markdown を読み込む仕組みがあります。
| ツール | 読み込まれるファイル例 |
|---|---|
| Claude Code | CLAUDE.md |
| Cursor |
.cursorrules / cursor.md
|
| Codex 系エージェント | エージェントの設定ファイルに参照を追加 |
Karpathy Skills の Markdown は、この設定ファイルにそのまま貼り付けるか、@import 的に参照させるだけ で機能します。プロジェクト固有の事情があれば、4原則の下にプロジェクト固有の制約を追記する形が使いやすいです。
CLAUDE.md（例）
─────────────────────────────────
# General Principles
（Karpathy Skills の 4 原則をここに貼る）
# Project-Specific Rules
- ライブラリは XXX を優先して使うこと
- ディレクトリ構成は src/ 配下を維持すること
- テストは Vitest を使うこと
─────────────────────────────────
ポイントは、「ツールごとに別の設定を書かない」 ことです。原則部分はツール非依存にしておき、プロジェクト固有のルールだけツール側で差し替えると、運用コストが最小化されます。
5. 開発者の役割はこの先どう変わるか
このリポジトリが象徴しているのは、AIコーディング時代における開発者の役割の変化です。
これまでの開発者の仕事は、コードを1行ずつ書くことでした。これからは、
- AIが安全に走れる環境を設計すること
- 明確な成功基準を定義すること
- 検証ループ（テスト・lint・型・CI）をAIの動線に組み込むこと
- AIの暴走を止めるハーネスを設計すること
が中心になっていきます。
つまり、必要なのは「プロンプトを上手に書ける人」でも、「ボタンを1回押して終わらせる人」でもなく、実運用に耐える開発環境を設計できる人 ということです。
6. Andrej Karpathy Skillsの日本語バージョン
下記の内容を、必要に応じて自分のハーネスで使ってください。
LLMによる一般的なコーディングミスを減らすための行動指針だ。プロジェクト固有の指針がある場合は、本ガイドラインとマージして使う。
トレードオフ：本指針はスピードよりも慎重さを優先する。些細な作業については、状況に応じて判断する。
### 1. 実装前に考える (Think Before Coding)
思い込みで進めない。曖昧さを隠さない。トレードオフを明確に示す。
実装に着手する前に、以下を守ること：
- 自分の前提を明示的に書き出す。不確かな場合は質問する。
- 解釈の余地が複数ある場合は、勝手に選択せず、代替案を提示する。
- よりシンプルなアプローチがあれば提案する。正当な理由があれば、ユーザーの要望に対して反対意見を述べる。
- 不明瞭な点があれば、作業を中断する。どこが分かりにくいのかを具体的に挙げて質問する。
### 2. シンプルさを最優先 (Simplicity First)
- 問題を解決するための最小限のコードだけを書く。憶測に基づくコードは排除する。
- 頼まれていない機能を追加しない。
- 使い捨てコードのために抽象化レイヤーを作らない。
- 頼まれていない柔軟性や設定の自由度を考慮しない。
- 起こり得ないシナリオに対する例外処理を書かない。
- 200行のコードを50行に減らせるなら、書き直す。
- 「シニアエンジニアから見て、このコードは過剰に複雑じゃないか？」と自問する。そうなら、シンプルにする。
### 3. 外科的な修正 (Surgical Changes)
必要な箇所だけを修正する。自分が触れた部分の後始末だけを行う。
既存コードを編集するときは、以下を守ること：
- 隣接するコード、コメント、フォーマットを勝手に改善しない。
- 壊れていない部分をリファクタリングしない。
- 自分のスタイルと違っていても、既存のスタイルに従う。
- 作業と無関係なデッドコードを見つけた場合は報告するに留め、自分の判断で消さない。
修正によって不要になった要素が出た場合：
- 自分の変更によって不要になったインポート、変数、関数は削除する。
- 元から存在していたデッドコードは、依頼がない限り残しておく。
- 判断基準：変更したすべての行は、ユーザーの依頼内容と直接結びついていなければならない。
### 4. ゴール駆動の実行 (Goal-Driven Execution)
成功基準を定義する。検証できるまで繰り返す。
作業を検証可能なゴールに置き換える：
- 「バリデーションを追加」→「不正な入力に対するテストを書き、パスすることを確認」
- 「バグを修正」→「バグを再現するテストを書き、パスすることを確認」
- 「Xをリファクタリング」→「リファクタリング前後でテストがパスすることを確認」
複数ステップの作業については、簡潔な計画を立てる：
1. [ステップ] → 検証：[確認事項]
2. [ステップ] → 検証：[確認事項]
3. [ステップ] → 検証：[確認事項]
成功基準が明確なら、自律的に作業を進められる。「とりあえず動くようにする」みたいな曖昧な基準は、不要な聞き返しを招くだけだ。
指針が効いているサイン：差分に含まれる不要な変更が減る、複雑さによる書き直しが減る、実装前の質問で意思決定がクリアになる。
まとめ
- Karpathy Skills の正体は、AIに新能力を足すものではなく、AIから自由を奪う設計指針 である。
- 4つの原則 ―
- Think Before Coding（推測せず質問させる）
- Simplicity First（必要な分だけ書かせる）
- Surgical Changes（必要な箇所だけ修正させる）
- Goal-Oriented Execution（検証可能な目標で動かす）
- AIはコードが書けないのではなく、書きすぎる・速すぎる・自信を持ちすぎる。だから「正しい方向に走らせるレーン」が必要になる。
- Claude Code / Cursor / Codex すべてに使い回せる構造で、設定ファイルに貼るだけで効果が出る。
- これからの開発者の仕事は 「コードを書く」ことから「AIが安全に走れる開発環境を設計する」ことへ シフトしていく ― いわゆる ハーネス・エンジニアリング の時代になっていく。