karpathy-guidelines 入門：Andrej Karpathy が勧める大規模言語モデルのプログラミング規約

April 10, 2026

難易度：入門 | 所要時間：約 15 分 | 得られるもの：4 原則の理解 + karpathy-guidelines に沿って AI のプログラミング行動を扱えるようになる

目標読者

  • Claude Code、Cursor、Copilot などの AI コード支援ツールを使っている開発者
  • 開発経験 1〜5 年で、AI が書くコードをより正確にし、無駄を減らし、勝手に改変させないことを望む人
  • AI プログラミングに一定の実践があり、体系的な協業ルールを探している人

コア依存関係と環境

依存バージョン要件用途
Node.js18+Claude Code CLI の実行
Claude Code CLI最新版中核ツール、プラグインをインストール
curl任意のバージョンCLAUDE.md ファイルのダウンロード

TIP

まだ Claude Code をインストールしていない場合は、claude.ai/code にアクセスしてインストール方法を確認してください。

完全なプロジェクト構成ツリー

andrej-karpathy-skills/
├── CLAUDE.md                # 中核ガイドファイル（4 原則を凝縮。プラグイン/ファイルの2方式で共用）
├── README.md                # インストールと使用方法
├── EXAMPLES.md              # 多数の実戦・反実戦例
└── skills/
    └── karpathy-guidelines/  # Claude Code プラグイン形式（推奨のインストール方式）

WARNING

本プロジェクトは Claude Code の行動規約プラグインであり、OpenClaw のスキルパックではありません。混同しないでください。

1. まず問題を理解する：LLM はなぜ「勝手に話を進める」のか

Andrej Karpathy は 2025 年末にツイートを投稿し、現在の大規模言語モデルのプログラミングにおける核心的な問題を指摘しました：

"The models make wrong assumptions on their own behalf and just run along with them without checking. They don't manage their confusion, don't seek clarifications, don't surface inconsistencies, don't present tradeoffs, don't push back when they should."

意訳すると次のようになります。LLM は黙って前提を置きがちで、曖昧な箇所があっても質問せずに書き始めます。コードを書くほど肥大化し、さらに自分が理解していない部分もそのまま手早く書き換えてしまいます。

この問題は、深く AI プログラミングを使っている開発者ならほぼ全員が遭遇しています。たとえば、AI に小さなバグ修正を頼むと半モジュールを作り直されたり、単純な関数追加を頼むと 3 層もの抽象化を導入されたりします。

karpathy-guidelines はこの 4 つの症状に対応して設計されています：

症状対応する原則
確認せずに黙って前提を置いて着手するThink Before Coding
コードがどんどん膨らみ、200 行が 2000 行になるSimplicity First
バグ修正のついでにプロジェクトの半分をリファクタするSurgical Changes
「直してみせる」—検証可能な成功基準がないGoal-Driven Execution

2. karpathy-guidelines のインストール

インストール方法は 2 つあります。推奨は 1 つ目です。

方法1：プラグイン方式（推奨）

# 手順1：プラグインマーケットを追加
/plugin marketplace add forrestchang/andrej-karpathy-skills

# 手順2：プラグインをインストール
/plugin install andrej-karpathy-skills@karpathy-skills

インストールが完了すると、Claude Code はどのプロジェクトでも自動的にこの 4 つの原則を読み込みます。

方法2：CLAUDE.md を直接ダウンロード（任意のプロジェクト向け）

新規プロジェクト：

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

既存プロジェクト（既存の CLAUDE.md に追記）：

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

TIP

方法 1 と方法 2 は併用できます。プラグインはグローバルなデフォルト動作を提供し、CLAUDE.md はプロジェクト単位の上書きを提供します。

3. 4 つの原則を 1 つずつ解説

原則1：Think Before Coding

核心： 前提を置かない。混乱を隠さない。不明点は自発的に提示し、トレードオフも出す。

これは最も AI 本能に反する項目です。AI の学習目的は「答えを出す」ことです。指示が曖昧だと、そこで止まって「結局どれを意味しているの？」と確認するのではなく、「最もそれっぽい解釈」を推測してそのまま実行を続ける傾向があります。

正しい開き方はこうです：

# ユーザーの指示：「検索をもう少し速くして」

# ❌ AI にありがちなやり方：黙ってキャッシュ、インデックス、非同期処理を足し、200 行を一気に書く
@lru_cache(maxsize=1000)
async def search(query: str) -> List[Result]:
    # ... いろいろ最適化コード
    pass

# ✅ karpathy-guidelines が求めるやり方：
"""
「検索をもっと速く」は、いくつかの意味として解釈できます：
1. 応答時間がより速い（< 100ms）：DB インデックス + キャッシュ、見積もり 2 時間
2. 並行スループットがより高い：非同期への改造 + コネクションプール、見積もり 4 時間
3. 体感速度がより速い（UX）：漸進的ロード、見積もり 3 時間

どれを指していますか？
"""

曖昧な指示に遭遇したら立ち止まって確認するほうが、作業を終えてから手戻りするよりはるかに効率的です。

コードの層では、この原則は次を要求します：

  • 自分の仮定を明確に述べる。不確かな点は質問する
  • 複数の妥当な解釈があり得るなら、すべて列挙してユーザーに選ばせる
  • よりシンプルな案が見つかったら、主導して提案する
  • 不明な箇所があれば即座に立ち止まり、質問する

原則2：Simplicity First

核心： 現在の課題を解決するのに必要な最小限のコードだけを書く。予測による設計はしない。

AI には傾向があります。「ベストプラクティス」を一気に押し込んでしまう癖があるのです。今まったく必要ないのに。たとえば、AI に割引計算を書かせると、ストラテジーパターン + ファクトリーパターン + 設定クラスの完全な体系を作ってしまうことがあります。

実際の比較を見てみましょう：

ユーザーの依頼：「割引計算関数を追加して」

# ❌ AI がやりがちなこと：不要な抽象化を導入
from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Protocol, Union

class DiscountStrategy(ABC):
    @abstractmethod
    def calculate(self, amount: float) -> float:
        pass

class PercentageDiscount(DiscountStrategy):
    def __init__(self, percentage: float):
        self.percentage = percentage
    def calculate(self, amount: float) -> float:
        return amount * (self.percentage / 100)

@dataclass
class DiscountConfig:
    strategy: DiscountStrategy
    min_purchase: float = 0.0
    max_discount: float = float('inf')

class DiscountCalculator:
    def __init__(self, config: DiscountConfig):
        self.config = config
    def apply_discount(self, amount: float) -> float:
        # ... いろいろコード

# 利用するだけで 30+ 行の準備コードが必要

# ✅ Simplicity First のやり方：
def calculate_discount(amount: float, percent: float) -> float:
    """割引額を計算します。percent は割合（例：10 は 10%）"""
    return amount * (percent / 100)

# 利用
#
discount = calculate_discount(100.0, 10.0)  # 9 割引

この原則の判断基準：

  • 誰も求めていない機能は追加しない
  • 1 回限りで使うコードは抽象化しない
  • 「柔軟性」が不要なら設定を用意しない
  • エラーが起こり得ないならエラーハンドリングを書かない
  • コードを書き終わったら自問する：「上級エンジニアなら、この過度な設計だと判断しないか？」そうなら書き直す

WARNING

この原則の反対は「雑に書く」ではなく、「抑制」です。複雑さが本当に現れたときにだけ抽象化を導入します。

原則3：Surgical Changes

核心： 必要な箇所だけを直し、作ってしまったゴミは片付ける。ただし、最初から存在していたものには触れない。

AI がバグを直すとき、特に「ついでに最適化」してしまうことが起きやすいです。バグを直した 3 行のついでに、変数名まで変えたり、フォーマットを整えたり、コメントを差し替えたりします。karpathy-guidelines は、外科手術レベルの精密さを求めています。

**典型的な場面：ユーザーが「メールが空のとき検証器がクラッシュする問題を直して」**と言った場合

  def validate_user(user_data):
-     # Check email format
-     if not user_data.get('email'):
+     email = user_data.get('email', '')
+     if not email or not email.strip():
          raise ValueError("Email required")
-     # Basic email validation
-     if '@' not in user_data['email']:
+     if '@' not in email:
          raise ValueError("Invalid email")
-     # Check username
-     if not user_data.get('username'):
+     # Check username  ← 元の書き方をそのまま
+     if not user_data.get('username'):
          raise ValueError("Username required")
      return True

❌ AI がやりがちなこと（ユーザーの依頼範囲を超える）：

# ついでに追加：
# - より厳格なメール形式の検証（正規表現）
# - ユーザー名の長さ検証
# - ユーザー名の文字検証
# - docstring
# - クォートのスタイル変更（'' → ""）

✅ Surgical Changes が求めること（空のメールに関係する 2 行だけ変更）：

-     if not user_data.get('email'):
+     email = user_data.get('email', '')
+     if not email or not email.strip():
          raise ValueError("Email required")
-     if '@' not in user_data['email']:
+     if '@' not in email:
          raise ValueError("Invalid email")

判断基準： 変更された各行のコードが、すべてユーザーの具体的な依頼に紐づけて説明できること。

原則4：Goal-Driven Execution

核心： 「何をするか」を「どうなれば成功なのか」に翻訳する。曖昧な指示を成功基準で置き換える。

これは Andrej Karpathy が最も強調している点です：「LLM は特定の目標に到達するまで、反復実行するのが非常に得意です。何をするかを伝えるより、成功基準を渡して自走させたほうがよい。」

2 種類の指示の例を比べてみましょう：

❌ 曖昧な指示（AI が困惑しやすい）：

ログインシステムの問題を修正して

✅ Goal-Driven な指示（AI が明確に進める）：

ログインシステムの具体的な問題：ユーザーがパスワードを変更した後、古い session が無効にならない。

計画：
1. テストを書く：パスワード変更 → 古い session が拒否されることを検証
   検証：テストが失敗する（バグの再現）

2. 実装：パスワード変更時に該当ユーザーの session を削除する
   検証：テストが通る

3. 境界ケース：複数デバイスでログイン、並行してパスワード変更
   検証：追加したテストがすべて通る

4. 回帰確認：ログイン関連の既存テストがすべて通る
   検証：pnpm test

現時点のログインモジュールのテストカバレッジ：[データ]
どのログイン問題に具体的に該当しているのか、教えてください。

マルチステップタスクの標準フォーマット：

1. [ステップの説明] → 検証：[検証方法]
2. [ステップの説明] → 検証：[検証方法]
3. [ステップの説明] → 検証：[検証方法]

このやり方の利点は、AI が各ステップ完了ごとにチェックリストを持つため、「これで合ってる？」を何度も確認する必要がないことです。

4. ガイドラインが効いているかを検証する方法

karpathy-guidelines をインストールした後、次の観点から「機能しているか」を判断できます：

差分（diff）の品質を見る：

  • 変更はすべてユーザーの要求に紐づいているか？
  • 不要な「ついでの最適化」は入っていないか？
  • クォートのスタイル、コメント、docstring が勝手に変更されていないか？

質問するタイミングを見る：

  • 曖昧な指示に遭遇したとき、AI は自発的に止まって確認したか？
  • それとも勝手に推測して書き始めただけか？

コードの複雑度を見る：

  • 新しく書かれたコードは「ちょうど必要な分」になっているか？
  • 過度な抽象化や過度な設計になっていないか？

この 3 つの観点がすべて改善していれば、ガイドラインが有効になっています。

5. 既存の CLAUDE.md とマージする

ほとんどのプロジェクトにはすでに独自の CLAUDE.md があるため、そのまま上書きすると既存の設定が失われます。正しい手順は置き換えではなく追記です：

# まず既存の CLAUDE.md の内容を確認
cat CLAUDE.md

# 次にエディタで手動マージするか、以下を実行：
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

マージ後のファイル構成の推奨例：

# プロジェクト説明（元の内容を保持）

---

# karpathy-guidelines（追加内容、PS：Andrej Karpathy 推奨）

[ここに CLAUDE.md の内容を貼り付け]

---

## プロジェクト固有の規約

- TypeScript strict モードを使用する
- すべての API エンドポイントにはテストが必要
- src/utils/errors.ts にあるエラーハンドリングのパターンに従う

TIP

karpathy-guidelines は汎用の行動規約です。プロジェクト固有の規約の優先度がより高くなります。両者が競合するときはプロジェクト規約を優先してください。

よくあるトラブルシューティング

Q1：プラグインを入れたのに効いていない？

# プラグインがロードされているか確認
/plugin list

# もし出ていなければ、Claude Code を再起動
# Claude Code 内で /exit と入力してから、再度入る

Q2：プロジェクトの CLAUDE.md とプラグインが衝突する場合は？

プロジェクトの CLAUDE.md が優先です。プラグインはグローバルなフォールバックの挙動を提供し、プロジェクトファイルがプラグインの設定を上書きします。

Q3：簡単なタスクでも止まって確認を求められるのはなぜ？

これは正常です——karpathy-guidelines はすべてのタスクに対して、曖昧な指示を明確化することを同じ基準で求めます。**明らかに簡単なタスク（例：「変数 a を b に変えるだけ」）なら、指示に「これは単純な置換で、すぐやって」と明確に追記してください。**すると、AI は確認ステップをスキップしやすくなります。

Q4：AI が Surgical Changes に従わず、またフォーマットまで乱す

指示で変更範囲を明確に制限します：

validateEmail 関数の空値チェックだけ変更して。この 1 箇所だけ直す。他のコードやフォーマットは触らないで。

Q5：CLAUDE.md をマージしたら衝突（コンフリクト）が起きた。どう解決する？

CLAUDE.md を手動で編集し、元の内容と新しく追加する原則を保ってください。重複する段落は避けます。もし同じ原則が別の場所で定義されている場合は、プロジェクトに元からある具体的な規約を優先してください。

Q6：既存のプロジェクトにも遡って適用する必要がある？

不要です。karpathy-guidelines が制約するのはこれからの変更行動であり、既存コードを後から作り直させるためのものではありません。新しいプログラミングのやり取りを導くために使ってください。

さらなる読書と発展方向

TIP

EXAMPLES.md には、正反対のコード比較が大量にあり、各原則につき 2〜3 の実際のシナリオ例が載っています。これらの原則を理解するうえで最も効果的な材料です。実践に入る前に、まずは最初から最後まで一通り目を通すことをおすすめします。

発展方向

4 つの原則を身につけたら、次の方向へさらに掘り下げられます：

カスタム拡張： CLAUDE.md にプロジェクト固有のコーディング規約を追加し、AI に karpathy-guidelines の汎用的な制約を持たせつつ、プロジェクト独自のスタイル要求も反映させる。

チーム共有： karpathy-guidelines をチームのコーディング規約ドキュメントに組み込み、新メンバーがプロジェクトをクローンした時点で自動的に AI プログラミング行動のガイドラインを得られるようにする。

効果の定量化： ガイドライン導入前後での AI の手戻り回数、変更範囲、PR 内の無関係な変更数を記録し、データでこの方法論の実際の価値を検証する。

Updated April 10, 2026