Claude Code に必須の CLAUDE.md？10 件の実チケットで Karpathy Skills を検証した

先に数字。 Karpathy Skills（コミュニティがまとめた CLAUDE.md 行動準則）が本当に効くか、実チケット 10 件で検証した。Claude Opus 4.8 固定、変えたのはKarpathy 四原則の有無だけ。1 週間で印象に残ったのは次のとおり。

がっかりしたケースもある——定数 1 行のチケットでは準則がほぼ効かず、「前提の確認」だけが 1 ラウンド増えた。成功も失敗も書く。あわせてリポジトリに置いている CLAUDE.md 最終版（Claude Code Rules / Claude Code Prompt で検索する人向け）を載せる。

Claude Code はなぜ関係ないところまで直すのか

モデルが弱いというより、デフォルトの最適化目標がエンジニアとずれている——早く「それっぽく完成した」パッチを出す。抽象を増やし、隣ファイルを触り、曖昧さは聞かずに進む。Andrej Karpathy は X で四つの慢性症状を整理した：聞く前に手を動かす、単純要件の過剰設計、触るべきでないファイルのついで修正、「終わった」宣言で検証可能なゴールを置き換える。

2026 年春、コミュニティはそれを数十行の CLAUDE.md に圧縮した（forrestchang/andrej-karpathy-skills、通称 Karpathy Skills）。新ランタイムはない——四つの行動契約だけ。Claude Code は毎セッション読む。知りたかったのは I tested it — 数字はいくつか。

Karpathy Skills とは

名前は Skills だが、形はプロジェクト指示ファイル。OpenAI GPT の Skills でも OpenHuman の SKILL.md プラグインでもない。Claude Code はセッション開始時にリポジトリ直下の CLAUDE.md（とグローバルプラグインの同等テキスト）を読み、最初の一行を書く前から Agent の思考と diff の切り方を縛る。

四原則は上流 CLAUDE.md と対応する：

• Think Before Coding：仮説を言い、曖昧さを出し、より単純な案があれば先に示す。黙って一解釈で書き始めない。
• Simplicity First：問題を解く最小コードだけ。要求されていない抽象・設定・「将来用」レイヤは拒否。
• Surgical Changes：タスクに必要な行だけ。隣の「整理」やフォーマットはしない。自分が入れたデッドコードは消す。レガシーは指摘だけ。
• Goal-Driven Execution：バグ修正やバリデ追加を検証可能なゴールに（可能なら失敗テストから）。多段タスクは各段の verify を列挙。

入れ方は二択：Claude Code プラグイン /plugin install andrej-karpathy-skills@karpathy-skills、または上流 CLAUDE.md をリポジトリ根にマージ——下の「最終版」はそのままコピー可。

検証のやり方

変数を抑える手順（Mac mini M4 Cloud Mac 上で実施——tmux 長走と xcodebuild 切れ防止のため。数字はローカル Mac でも再現可）：

• 実チケット 10 件：Swift 小機能 4、跨ファイルリネーム 2、テスト追加 2、CI スクリプト 2。
• モデル固定：claude-opus-4-8、Effort high、同週内でマイナーアップなし。
• 唯一の変数：対照は旧 CLAUDE.md（Karpathy なし）。実験は四原則 + 下記チーム規則 2 条。
• 各チケット 2 回（A→B または翌日交互）で「その日調子が良い」偏りを避ける。

レビューで時間を食う 5 指標を記録：

10 チケットの結果

下表は中央値（n=10、公式ベンチではない）。一つだけ覚えるなら 無関係 diff −78%。

無関係 diff の 18% → 4% は、ファイル数自体はまだ多くても「Payment モジュールのついでフォーマット」が diff から消えた感覚——Surgical Changes の曲線。初回 CI 緑 5/10 → 8/10 は主に Goal-Driven Execution：失敗テストを先に足してから実装に入る頻度が上がった。

効きが大きいシーン

• 跨ファイルリネーム / シグネチャ変更：無関係 diff −78% が体感で最大。CR が地雷原にならない。
• 要件がやや曖昧な小機能：Think Before Coding で仮説列挙が先に出て、手戻し 3 回 → 1 回（PAY-1842、AUTH-901）。
• テスト追加 + 実装：一発緑率上昇。CLAUDE.md に「赤→緑」を書くと安定。

コード知識グラフとは直交：グラフは「どこを直すか」、CLAUDE.md は「余計なところを触らない」。

ほぼ効かないシーン（失敗事例つき）

がっかりした 1 件：定数 1 つ。 チケット CFG-77：maxRetryCount を 3→5、パス指定済み。Karpathy 有効でも Agent は「バックオフ戦略とユニットテストのデフォルトも変えるか？」と確認が 1 ラウンド増えた。diff のきれいさは無準則と同じ、合計 +4 分。仕様が極端に明確な一点変更では四原則の慎重さがほぼ 0 効果。

その他ほぼ無効：

• チーム CLAUDE.md が既に長く Karpathy と重複——限界効用逓減。
• テスト / xcodebuild なし——Goal-Driven が閉じず「終わった風」だけ残る。
• チャットだけでリポジトリに書かない——CLAUDE.md は読まれない。

私の CLAUDE.md 最終版（コピー用）

CLAUDE.md、Claude Code Rules、Claude Code Prompt で検索する人が欲しいのはリポジトリに貼れる完成品。Karpathy 四原則 + iOS チーム規則 2 条をマージした版（本文は英語のまま。日本語説明は周辺テキスト）：

# CLAUDE.md — Karpathy rules + Vuncloud iOS team

## Think Before Coding
Don't assume. Don't hide confusion. Surface tradeoffs.
Before implementing: state assumptions; if unclear, ask; if a simpler approach exists, say so.

## Simplicity First
Minimum code that solves the problem. Nothing speculative.
No extra abstractions, config, or error handling for impossible cases.

## Surgical Changes
Touch only what you must. Don't "improve" adjacent code or formatting.
Match existing style. Mention unrelated dead code; don't delete unless asked.

## Goal-Driven Execution
Transform tasks into verifiable goals (tests first when applicable).
Multi-step: list plan with verify check per step.

## Vuncloud: Build Verification (custom)
After code changes to Swift/ObjC targets, run before claiming done:
  xcodebuild test -scheme YourApp -destination 'platform=iOS Simulator,name=iPhone 16'
Report exit code. If tests fail, fix or stop — do not claim success.

## Vuncloud: Path Allowlist (custom)
Unless the user explicitly expands scope, only edit paths they named
or standard paired test paths (e.g. Sources/Foo/ ↔ Tests/Foo/).

上流の入れ方：

/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

# または per-project：
curl -fsSL -o /tmp/karpathy-claude.md \
  https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
# 既存 CLAUDE.md は上書きせず段落をマージ

Cursor 利用者は .cursor/rules/karpathy-guidelines.mdc を同期し、Claude Code と同じ意味に揃える。Karpathy 測定時は claude-opus-4-8 を固定し、モデルアップと混ぜない——Opus 4.8 長走ガイド参照。

Cloud Mac 長時間運用（Claude Code → tmux → Mac mini）

OpenHuman より Cloud Mac が自然なのは、鎖が閉じるから：Claude Code 長セッション → tmux 切断耐性 → 同機 xcodebuild → 専用 Mac mini。対照実験・夜間 Agent・越境 CR はノートのスリープが怖い。試行は Cloud Mac で環境安定だけ取り、数字はローカルでも再現可。

• tmux + Claude Code：SSH 切断でもセッション維持（Opus 4.8 記事に例あり）。
• 永続ボリュームの CLAUDE.md：準則と monorepo を同梱、設定消失なし。
• Goal-Driven 硬検収：Build Verification を CLAUDE.md に書き、Scheme 実行まで完了報告させる。
• Mac クラウド CI と同機で改修即検証。

対照実験用スクリプト断片

TASK_ID="PAY-1842"
git diff --stat main...HEAD > "/tmp/${TASK_ID}-stat.txt"
git diff --name-only main...HEAD | wc -l | awk '{print "files_changed=" $1}'
# 無関係パス：人手または allowlist 比較
xcodebuild test -scheme YourApp -destination 'platform=iOS Simulator,name=iPhone 16' \
  | tee "/tmp/${TASK_ID}-xcodebuild.log"
echo "exit=$?" >> "/tmp/${TASK_ID}-xcodebuild.log"

Claude Code への依頼はゴール文で四原則目を刺す：

ゴール：CheckoutViewModel.validateAmount に非正数チェックを追加。
検証：1) 0・負数・NaN をカバーする単体テストを追加；2) xcodebuild test -scheme YourApp が通る；
範囲：Sources/Checkout/ と対応 Tests/ のみ。UI テーマや他モジュールは触らない。

よくある質問 (FAQ)

Karpathy 本人が書いた？ 準則は X 上の観察が起源。CLAUDE.md はコミュニティ整理（Forrest Chang 等）。Karpathy は関連リポを RT したことがある——README を正とする。

Claude Code の memory / プロジェクト説明と衝突？ マージが正解。四原則を前段、チームの命名・ブランチ・テストコマンドを後段。

Code Review の代替？ いいえ。ノイズ diff は減るが、マージゲート・人手 CR・セキュリティスキャンは必須。

Cursor ユーザーは？ .cursor/rules/ にコピー。同一 git なら Claude Code と意味を揃える。

パーセントは引用できる？ 自チームの対照実験を引用してほしい。本文表は Vuncloud 試行（n=10、厳密な二重盲検ではない）。

まとめ

Karpathy Skills を測った。泛泛の「効く/効かない」ではない。 10 チケット・Opus 4.8 固定：無関係 diff 約 78% 減、初回 CI 緑 +30pp；定数変更はほぼ助けにならない。価値があるのはリポジトリに書いた CLAUDE.md——Karpathy 四原則 + 自前のビルド・パス規則。Claude Code を 7×24 で回すなら Mac mini Cloud Mac + tmux が OpenHuman より素直：Agent・ターミナル・Xcode は同じ macOS にいるべきだ。