andrej-karpathy-skills

Karpathy-Inspired Coding Agent Guidelines — CLAUDE.md、Claude Code Skill、Cursor project rule で配布される行動規範

1 — 概要

何のためか

このリポジトリは、Andrej Karpathy が指摘した LLM コーディングの癖に対し、4 つの原則でブレーキと方針を与えるための素材をまとめたもの。中核は CLAUDE.md、Claude Code プラグインとしての Skill（karpathy-guidelines）、Cursor 用の project rule、そして失敗例と修正例を集めた EXAMPLES.md である。

Think前提を明示

Simple最小のコード

Surgical触る範囲を限定

Goals検証可能なゴール

キーインサイト（README より）: 「LLM は具体的なゴールがあれば、それを満たすまでループするのが得意」— だから手順命令より成功条件と検証を渡す設計に寄せる。

Claude Code

Marketplace plugin と Skill で、複数プロジェクトに再利用しやすい形で配布。

Cursor

.cursor/rules/karpathy-guidelines.mdc が alwaysApply: true で同梱される。

Root Instructions

ツールが project rule や plugin を読まない場合は CLAUDE.md を取り込む。

2 — 問題意識（出典の要約）

Karpathy が挙げたパターン

「モデルはユーザーに代わって誤った前提を置き、確認せずに走り続ける。混乱の管理・質問・矛盾の表面化・トレードオフ提示・本来押し返すべきときの押し返しが弱い。」

「コードや API を過剰に複雑にし、抽象を膨らませ、デッドコードを片付けない… 100 行で足りるところを 1000 行の構築物にしてしまう。」

「タスクと直交するコメントやコードまで、十分に理解しないまま副作用として変えてしまうことがある。」

3 — 4 原則

原則と狙い

原則	主に抑える失敗
Think Before Coding	暗黙の前提、隠れた混乱、トレードオフ未提示
Simplicity First	過剰設計、肥大した抽象、不要機能の先回り
Surgical Changes	直交するコードへの「ついで修正」、スタイルの押し付け
Goal-Driven Execution	曖昧な「なんとかして」、検証なき完了宣言

1. Think Before Coding

実装前に仮説を言語化し、曖昧さは質問で潰す。複数解釈があるときは勝手に一つに決めず並べる。単純な代替があれば指摘する。

2. Simplicity First

依頼範囲を超えた機能・一度きりなのに一般化した抽象・不要なエラーハンドリングを避ける。「シニアが過剰と言うなら削る」というテストを README でも提示。

3. Surgical Changes

隣の未壊コードはリファクタしない。既存スタイルに合わせる。自分の変更で不要になった import 等だけ掃除し、元から死んでいたコードの削除は依頼があるまでしない。

4. Goal-Driven Execution

「バグを直す」→「再現テストを書き、通るまで」など、検証可能な形に言い換える。複数ステップなら ステップ → verify: チェック の短い計画を先に出す。

4 — 関係図

失敗パターン → 原則 → 期待される挙動

flowchart TB
  subgraph issues[典型的な失敗]
    A[暗黙の前提で実装]
    B[抽象と行数の膨張]
    C[無関係な差分・コメント改変]
    D[曖昧な完了条件]
  end
  subgraph p[4 原則]
    P1[Think Before Coding]
    P2[Simplicity First]
    P3[Surgical Changes]
    P4[Goal-Driven Execution]
  end
  subgraph out[期待される結果]
    O1[質問とトレードオフが先]
    O2[最小差分のパッチ]
    O3[テストやコマンドで検証]
  end
  A --> P1
  B --> P2
  C --> P3
  D --> P4
  P1 --> O1
  P2 --> O2
  P3 --> O1
  P4 --> O3

5 — 具体例

EXAMPLES.md の読みどころ

EXAMPLES.md は、4 原則を抽象論で終わらせず、LLM がやりがちな「それっぽいが危ない」実装と、望ましい応答を対比する実例集になっている。

原則	やりがちな失敗	望ましい振る舞い
Think Before Coding	エクスポート範囲・形式・項目を勝手に決める	スコープ、形式、機密フィールド、件数を先に確認する
Simplicity First	単純な割引計算に Strategy / Config / Calculator を先回りで作る	今日必要な 1 関数で解き、複雑さは要求が出た時点で足す
Surgical Changes	バグ修正ついでにコメント、型注釈、引用符、周辺ロジックまで変える	報告された不具合に直結する行だけを変え、既存スタイルに合わせる
Goal-Driven Execution	「調査して改善します」のまま成功条件なしで走る	再現テスト、実装、回帰確認を各ステップの verify として置く

要点: 悪い例は必ずしも雑なコードではない。問題は必要になる前に複雑さを足すタイミングで、EXAMPLES.md はその境界を見える化している。

6 — 導入

Claude Code プラグイン（推奨）

マーケットプレイス登録後、プラグイン名でインストールする流れ（README 準拠）。プラグイン定義では skills/karpathy-guidelines が公開 Skill として参照される。

/plugin marketplace add forrestchang/andrej-karpathy-skills

/plugin install andrej-karpathy-skills@karpathy-skills

CLAUDE.md をプロジェクトに取り込む

新規プロジェクトでは raw の CLAUDE.md を取得。既存プロジェクトでは追記。

curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

Skill 本体のエントリは skills/karpathy-guidelines/SKILL.md。エージェント向けの説明文と YAML フロントマター（name / description / license）が定義されている。

7 — Cursor での使い方

Project rule と同期対象

最新の README では Cursor 対応が明記された。このリポジトリには .cursor/rules/karpathy-guidelines.mdc がコミットされており、alwaysApply: true の project rule として自動適用される。

利用面	使うファイル	注意点
このリポジトリを Cursor で開く	`.cursor/rules/karpathy-guidelines.mdc`	追加インストールなし。Settings → Rules で確認できる。
別プロジェクトの Cursor に持ち込む	`.cursor/rules/karpathy-guidelines.mdc`	対象プロジェクトの `.cursor/rules/` にコピーし、既存ルールと必要に応じて統合する。
Cursor 以外の root instruction	`CLAUDE.md`	ツールが Cursor rule や plugin を読まない場合に取り込む。
個人用 Agent Skill	`skills/karpathy-guidelines/SKILL.md`	個人のスキルディレクトリにコピーまたは symlink して再利用する。

同期ルール: 4 原則を変えるときは CLAUDE.md、Cursor project rule、Skill 本体を揃える。Claude Code は plugin / CLAUDE.md、Cursor は project rule を主に読む、という役割分担。

8 — 効き目の目安

うまくいっているサイン

diff に依頼と無関係な変更が減る
最初から過剰な抽象で書き直す回数が減る
実装より先に確認質問が増える（失敗後ではなく）
PR が小さく、ドライブバイリファクタが載りにくい

9 — トレードオフ

速度とのバランス

注意: ガイドラインは慎重さを速度より優先するバイアスを持つ。タイポ修正のような自明な作業では、フル手順までは不要でよい（README の Tradeoff Note と同旨）。

プロジェクト固有ルールは ## Project-Specific Guidelines などで追記し、この 4 原則と合成して使う想定。

10 — 参考リンク

公式・出典

GitHub: forrestchang/andrej-karpathy-skills — 本体リポジトリ（README・プラグイン・CLAUDE.md）
CLAUDE.md（raw） — プロジェクト直下に置く行動規範テキスト
CURSOR.md — Cursor project rule の使い方と Claude Code との違い
EXAMPLES.md — 4 原則ごとの失敗例と修正例
skills/karpathy-guidelines/SKILL.md — Claude Code 用 Skill 定義
Andrej Karpathy（X）— LLM コーディングの癖に関する投稿 — 本ガイドラインの着想・出典