karpathy-coder

Karpathy Coder — 積極的なコーディング規律

LLM によるコーディングの落とし穴についての Andrej Karpathy の見解に基づいています。単なるガイドラインではありません — 違反を検出する Python ツール、レビューエージェント、スラッシュコマンド、プリコミットフックを備えています。

「モデルはあなたに代わって誤った仮定をし、それを確認せずにそのまま進めてしまいます。混乱をうまく扱わず、確認を求めず、矛盾を明らかにせず、トレードオフを提示せず、必要なときにも異議を唱えません。」

「コードや API を過度に複雑にし、抽象化を肥大化させ、不要なコードを整理しない傾向があります……100 行で済むところに、1000 行を超える肥大化した構造を実装します。」

「LLM は、具体的な目標を達成するまで繰り返すことが非常に得意です……何をするかを指示するのではなく、成功基準を示して、その実現を見届けましょう。」

— Andrej Karpathy

4 つの原則

1. コーディングの前に考える

決めつけない。混乱を隠さない。トレードオフを明らかにする。

• 仮定を明確に述べます。不確かな場合は質問します。
• 解釈が複数ある場合は、それらを提示します — 何も言わずに一つを選ぶことはしません。
• よりシンプルな方法がある場合は、その旨を伝えます。必要に応じて異議を唱えます。
• 不明な点があれば、いったん止まります。何が不明なのかを明らかにして、質問します。

2. シンプルさを優先する

問題を解決するために必要最小限のコードだけを書く。憶測に基づく実装はしない。

• 要求されていない機能は追加しません。
• 一度しか使わないコードを抽象化しません。
• 要求されていない「柔軟性」や「設定可能性」は追加しません。
• 起こり得ない状況に対するエラー処理は追加しません。
• 200 行書いたものが 50 行で済むなら、書き直します。

テスト： シニアエンジニアが見て、複雑にしすぎだと言うでしょうか？ そうなら、シンプルにします。

3. 変更を必要最小限にする

必要な箇所だけを変更する。自分が作った問題だけを片付ける。

• 近接するコード、コメント、書式を「改善」しません。
• 壊れていないものをリファクタリングしません。
• 自分なら違う書き方をするとしても、既存のスタイルに合わせます。
• 無関係な不要コードに気づいた場合は、その旨を伝えます — 削除はしません。
• 自分の変更によって未使用になったインポート、変数、関数は削除します。
• 依頼されていない限り、既存の不要コードは削除しません。

テスト： 変更したすべての行が、ユーザーの依頼に直接結び付いている必要があります。

4. 目標に基づいて実行する

成功基準を定め、検証できるまで繰り返す。

代わりに…	次のように置き換える…
「検証を追加する」	「無効な入力のテストを書き、それを通す」
「バグを修正する」	「バグを再現するテストを書き、それを通す」
「X をリファクタリングする」	「変更の前後でテストが通ることを確認する」

複数の手順があるタスクでは、簡潔な計画を示します。

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

スラッシュコマンド

/karpathy-check — ステージ済みの変更に対して、4 つの原則すべてに基づくレビューを実行します。

Python ツール（scripts/）

すべて標準ライブラリのみを使用します。--help を付けて実行してください。

スクリプト	検出する内容
complexity_checker.py	過剰なエンジニアリング：クラスの多さ、深いネスト、高い循環的複雑度、未使用パラメーター、時期尚早な抽象化
diff_surgeon.py	差分のノイズ：明示された目標に結び付かない行 — コメントの変更、スタイルの逸脱、ついでのリファクタリング
assumption_linter.py	計画に潜む仮定：依頼されていない機能、確認事項の不足、明示されていない解釈の選択
goal_verifier.py	弱い成功基準：検証可能なチェックがない曖昧な計画、テストアサーションの不足

サブエージェント

karpathy-reviewer — 差分に対して 4 つの原則すべてに基づくレビューを実行します。/karpathy-check から、またはコミット前に手動で起動します。

プリコミットフック

hooks/karpathy-gate.sh — ステージ済みファイルに対して complexity_checker.py と diff_surgeon.py を実行します。違反が見つかった場合は警告します（処理はブロックしません）。.claude/settings.json または Husky を使って接続します。

参考資料

• references/karpathy-principles.md — 引用元、詳しい背景、各原則を緩和するタイミング
• references/anti-patterns.md — Python、TypeScript、シェルにわたる 10 件以上の変更前／変更後の例
• references/enforcement-patterns.md — フックの接続方法、CI への統合、チームでの導入方法

緩和する場合

これらの原則は、速度よりも慎重さを重視します。些細なタスク（誤字の修正、明らかな1行変更など）では、状況に応じて判断してください。これらの原則が特に重要となるのは、次のような場合です。

• 些細ではない実装（20行を超える変更）
• 十分に理解していないコード
• 要件が不明確な複数ステップのタスク
• 人間によるレビューを受けるもの

ツール間の互換性

Claude Code ではプラグイン経由でインストールされます。他のツールでは、原則をスキーマファイルにコピーしてください。

ツール	スキーマファイル
Claude Code	CLAUDE.md（プラグインによって自動読み込み）
Codex CLI	AGENTS.md
Cursor	AGENTS.md または .cursorrules
Antigravity / OpenCode / Gemini CLI	AGENTS.md

関連スキル（context: fork を介して連携）

• self-eval — 作業完了後の誠実な品質評価
• code-reviewer — より広範なコードレビュー。karpathy-coder は LLM 固有の4つの落とし穴に焦点を当てます
• llm-wiki — 知識の複利的な蓄積。karpathy-coder は、その構築時に過度に複雑化しないようにします