KarpathyのCLAUDE.md解説：スキル検索の背景にある1つのファイル

Google トレンドで、世界全体を対象に過去7日間について2026年10月23日に確認したところ、「karpathy skills」は「claude skills」のシードの下で急上昇クエリとして表示されています。この検索を追う人は誰でも同じ場所にたどり着きます。すなわち github.com/multica-ai/andrej-karpathy-skills で、このリポジトリは2026年10月23日時点でGitHub上に222,612個のスターを表示していました。その説明文には「skill」という語がまったく含まれていません。説明文は次のとおりです。「Claude Codeの動作を改善するための単一のCLAUDE.mdファイル。Andrej KarpathyによるLLMコーディングの落とし穴に関する観察に基づく。」

クエリと対象物の間のずれは、些細な技術的差異ではない。スキルと CLAUDE.md ファイルは別の仕組みであり、果たす役割も異なる。このリポジトリについて人々が語る主張はほぼすべて、どちらを指しているかを知っているかに依存しているか、そうでなければ暗黙のうちに誤った方を前提にしている。中のガイダンスは単一のファイルだ。そのファイルを取り巻くリポジトリには、プラグインマニフェストと skills 配下のフォルダも含まれており、おそらく検索バーに入れた語の出どころはそこだろう。パッケージングとペイロードを切り分けることが、ここでの最初の有用な一手だ。

数字はすべてGitHubのもので、2026年10月23日に確認した。スター222,612、フォーク22,321、2026年1月27日作成、最終プッシュ2026年4月20日、MITライセンス。興味深いのは最後の2項目だ。このリポジトリは約6か月間プッシュを受けていないのに、スター数はそれでも増え続けた。

ファイルが実際の処理を担い、パッケージングが検索語を説明する

リポジトリを開くと、ファイル一覧からその不一致がすぐに分かります。ルートには CLAUDE.md があり、その隣に CURSOR.md、EXAMPLES.md、同じガイドラインを Cursor プロジェクトルールとして保持する .cursor/rules フォルダ、.claude-plugin フォルダ、skills/karpathy-guidelines ディレクトリがあります。README の推奨インストール方法はプラグインマーケットプレイスで、その結果を「スキルをすべてのプロジェクトで利用できるようにする」と説明しています。

検索語が間違っているというよりは、不正確なのです。skills フォルダはあります。プラグインもあります。ないのは、それぞれ別の仕事をする独立したスキルの集合です。これが通常「スキルパック」と言われる形で、SKILL.md とその機能に必要なサポートファイル一式を収めたフォルダを、1つのタスクのために呼び出すものを指します。ここではガイダンス全体が常設の指示をまとめた単一のドキュメントであり、プラグインはそのドキュメントをプロジェクトに届けるために存在します。

その区別があなたにとって重要かどうかは、検索に何を求めていたかによって変わります。ツールボックスを探していたなら、これはツールボックスではありません。プロジェクト全体でコーディングエージェントの振る舞いを変える短いルールブックを求めていたなら、それはまさにこれであり、なぜ誰かがそれをスキルではなくファイルとして書くのかを理解する価値があります。

それが反論として書かれた苦情

README に記載されている出典は、Andrej Karpathy による X の投稿であり、README はモデルがコードを書く方法に関する3つの不満についてその投稿を引用しています。それらは全文を読む価値があります。というのも、4つの原則はほぼ1対1でそれらに対応しているからです。

第一に：モデルは「あなたに代わって誤った前提を置き、確認もせずそのままそれに従って突き進む」し、「自分の混乱を管理せず、明確化を求めず、矛盾を表面化させず、トレードオフを示さず、反論すべきときに反論しない」。何が描写されているかに注目してください。これは誤った回答についての不満ではありません。ためらいなく流暢に提示される誤った回答についての不満であり、疑問を引き出すはずだった不確実性が、代わりに自信に満ちたコードを生み出した状況についての不満です。

第二点は、彼らは「コードとAPIを本当に過剰に複雑化し、抽象化を肥大化させ、デッドコードを整理せず……100行で済むところを1000行以上の肥大化した構造物として実装する」ということだ。これは、機能を求めたのにフレームワークを受け取ったことのある人なら誰でも身に覚えのある話だ。

三つ目はより微妙で、差分をレビューする誰にとっても最も高くつくものです。彼らは「十分に理解していないコメントやコードを、たとえタスクと無関係であっても、副作用として今でも時折変更したり削除したりする」のです。一つのコメントへの無関係な編集は、それだけを見れば小さいものです。しかしコードベース全体に掛け合わされると、それはレビューキューが誰も求めていない変更で埋め尽くされていく仕組みであり、ワークアラウンドの存在理由が誰かに知られる前に、そのワークアラウンドを説明するコメントが消えてしまう仕組みでもあるのです。

4つの原則と、それぞれが残す試練

このファイルは4つの原則を定めています。それぞれには短い一連のルールが付いており、そのうち2つは、何もインストールせずに diff に適用できる1行のテストを明示しています。このファイルの性格が表れるのは、ルールの部分です。

コードを書く前に考えよう

見出しの指示は「仮定するな。混乱を隠すな。トレードオフを表面化せよ」だ。その下では、仮定を明示し、推測するのではなく質問する。要求が曖昧な場合は複数の解釈を示す。より単純な方法がある場合は反論する。混乱したら止まり、何が不明確かを名指しし、明確化を求める。これはまさに最初の不満に狙いを定めている。仕組みは「もっと注意深くなる」ことではない——沈黙のうちになされる選択を可視の選択に変えることで、コードが存在する後ではなく前に、レビュアーが異議を唱えられるようにすることだ。

シンプルさを第一に

ルールは、問題を解決する最小限のコードであり、投機的なものは一切含めないことだ。求められた以上の機能は作らず、単一用途のコードのための抽象化も行わず、誰も求めていない柔軟性や設定可能性も持たせず、起こり得ないシナリオのためのエラーハンドリングも行わない。そして「200行を50行にできるなら、書き直せ」。判断基準はただ一つの問いだ――シニアエンジニアならこれは過剰に複雑だと言うだろうか？――それは判断に委ねられる事柄であり、しかもそうであることを隠していない。

外科的な変更

このファイルは指示を2つに分けており、それがこのファイルの中で最も有用な点です。既存のコードを編集するときは、隣接するコード、コメント、書式を改善しないこと。壊れていないものをリファクタリングしないこと。自分なら違うやり方をするとしても、既存のスタイルに合わせること。無関係なデッドコードは削除するのではなく言及すること。自分の変更が孤立した要素を生む場合は、変更によって未使用になったインポート、変数、関数を削除すること。ただし、既存のデッドコードは依頼されない限りそのままにしておくこと。判断基準は、変更されたすべての行が要求に直接つながっていることです。

目標駆動型実行

成功基準を定義し、検証されるまでループする。README はその変換をペアとして示している。「バリデーションを追加する」の代わりに、無効な入力に対するテストを書き、それを通すようにする。「バグを修正する」の代わりに、そのバグを再現するテストを書き、それを通すようにする。「X をリファクタリングする」の代わりに、前後でテストが通ることを確認する。複数ステップの作業では、各ステップがそれぞれの検証方法を明記した短い計画を求めている。README はここで再び Karpathy を引用している。「LLM は特定の目標を達成するまでループし続けるのが極めて得意だ……何をすべきか指示するのではなく、成功基準を与えて、動くのを見守ればよい。」

ファイル、スキル、プラグインはそれぞれ異なる3つのものです。

仕組みについては正確に述べておく価値がある。実際の動作が異なるからだ。CLAUDE.md はプロジェクト指示ファイルである。これは Claude Code がリポジトリの常設コンテキストとして読むテキストで、そのターンに誰が要求したかに関係なく存在する。スキルは SKILL.md を含むフォルダであり、SKILL.md はその機能をいつ使うべきかを記述し、タスクがそれを必要としたときに読み込まれ、それより前に読み込まれることはない。プラグインは配布パッケージで、マーケットプレイスを通じてインストールされ、スキル、コマンド、その他のコンポーネントを含めることができる。この区別は、指示がいつコンテキストに入るか、誰が決めるかに関するものであり、品質に関するものではない。

その意味で、CLAUDE.md は3つの中で最も大雑把な仕組みだ。そのプロジェクトでは常に有効で、あらゆるタスクに適用され、作業が1行のタイポ修正でも移行作業でも、毎ターンコンテキストを占有する。このファイル自体の README は「Tradeoff Note」というセクションでそのコストを認めている。ガイドラインは速度より慎重さに偏っており、些細なタスク——単純なタイポ修正や明らかなワンライナー——では判断力を働かせるべきだという。目標は非自明な作業での高くつくミスを減らすことであり、単純な作業を遅くすることではない、と述べている。

それは、常設の指示ファイルに何ができるかについての公正な説明だ。モデルが持っていない能力を追加することはできない。モデルの既存の振る舞いを、より起こりやすくしたり、より起こりにくくしたりできるだけだ。だからこそ、そのファイルは、もっと良くなれと励ますのではなく、制約として――これはするな、それはする前に確認しろ――書かれているのだ。

222,612個の星が測るもの

彼らは注目度を測っている。それは軽視ではなく、何でもないことでもない。2026年1月に作成され、最後にプッシュされたのが4月だったリポジトリが、2026年10月23日までにGitHubで222,612個のスターと22,321件のフォークを獲得した。その日に読まれたということは、広く共有され、自分用のコピーを欲しがる人々によってフォークされたことを意味する。スター数は、何人がブックマークする価値があると感じたかを測る妥当な代理指標である。

それは効果の代理指標ではなく、リポジトリもそうでないふりはしていない。そこにはどこにも公開されていないものがある。ファイルがある場合とない場合の結果を比較するベンチマーク、それが機能するかどうかを測る方法論、対照群との比較のいずれも。実在のコードベースでのビフォーアフターも、レビュアーによる研究も、インシデント率もない。このようなファイルは、モデルの振る舞いに関する仮説を優雅に述べたものであり、誰もその試行を実施していない。

README が代わりに提示しているのは「How to Know It's Working」というセクションで、そこには観察できるかもしれない 4 つの事項が挙げられています。diff における不要な変更の減少、過度な複雑化による書き直しの減少、ミスの後ではなく実装前に届く明確化のための質問、そしてクリーンで最小限のプルリクエストです。これらは妥当なシグナルです。しかし同時に、何も測定していない場合に書くような内容でもあり、そのファイルを適用している本人による自己申告でもあります。これらは、そのファイルがすでに合格した証拠としてではなく、自分のリポジトリでそのファイルに求める基準としてのチェックリストとして読んでください。

実際にインストールするときに入力する内容

READMEには2つの方法が示されています。推奨される方法はClaude Code内で実行します。マーケットプレイスを追加し、次にプラグインをインストールすると、その後、ガイドラインはリポジトリごとではなくプロジェクト横断で利用できるようになります。2つ目はプロジェクト単位です。生のCLAUDE.mdを新しいリポジトリに取得するか、既存のリポジトリに追記します。コミット済みのCursorプロジェクトルールもあるため、フォルダをCursorで開いたときにも同じガイドラインが適用されます。これは、そのファイルが特定ベンダーのローダーに依存せず、プロジェクトレベルの指示ファイルを読み取るツール間で移植可能になるように書かれていることを示す詳細です。

ひとつ引っかかる点があり、README に正確に従うと必ず遭遇するので指摘しておきます。マーケットプレイスのコマンド名は forrestchang/andrej-karpathy-skills を指していますが、ページ上部のリポジトリ URL は multica-ai/andrej-karpathy-skills です。どちらの文字列も同じ README に記載されており、2026年10月23日に読んだものです。不一致は確認できますが、なぜ存在するのかは説明できません。したがって正直なアドバイスは、片方が失敗したらもう一方のパスを試すこと、そして2つの文字列のうち片方は古いものとして扱うことです。

フロントページで他に注目すべき点は、リポジトリが multica-ai によって維持されており、README の冒頭の引用ブロックで Multica が「再利用可能なスキルを備えたコーディングエージェントを実行・管理するためのオープンソースプラットフォーム」として宣伝されていることです。これは正当な開示であり、同時に、パッケージの見え方が今のようになっている理由を示す手がかりでもあります。再利用可能なスキルに関心のあるプロジェクトは、自らのガイダンスをインストール可能なものとして提供する可能性が高く、そのインストール可能なものがこのプラグインなのです。

その前提を引き継ぐことなく、それを使うこと

カスタマイズセクションは、ほとんどの読者が飛ばしてしまう部分です。このファイルは、置き換えるのではなく、プロジェクト固有の指示とマージされるように設計されており、示される例は具体的です。TypeScriptのstrictモードを使用する、すべてのAPIエンドポイントにはテストが必要、特定のファイルにある既存のエラーハンドリングパターンに従う、などです。これは飾りではありません。汎用的なルールブックと、あなたのコードがどこにあるかを知っている指示セットとの違いなのです。

積み重ねるのではなく統合するのには実用的な理由がある。ファイルをそのまま貼り付けたうえで、自分のプロジェクトに独自の規約がある場合、2組の指示が食い違うことがあり、その食い違いをモデルが調整することこそ、第一原則が排除しようとしている混乱そのものである。自分の規約を同じファイルに同じ語り口で書き込めば、指示の表面を監査できるほど小さく保てる。

そして、あなたはそれを監査すべきです。これは、リポジトリ内のすべてのリクエストに適用される、行動指示に関する短い文書です。正しい問いは、222,612人が間違っている可能性があるかどうか——その捉え方では何も決着しない——ではなく、各ルールがあなたが実際に目にした失敗と一致するかどうかです。あなたの差分に、通りすがりのコメント書き換えが一度も含まれたことがないなら、Surgical Changesセクションは無駄にコンテキストを消費するだけです。それを削除してください。このファイルはMITライセンスであり、編集されることを意図しています。

一層下では、このいずれもどのモデルが応答するかを変えません。CLAUDE.mdファイルは、リクエストがモデルに届いた後の処理方法を形作りますが、それを受け取るモデルについては何も示しません。その2つ目の決定は、モデルの手前にあるものに属します。これを実現する方法の1つは、1つのキーで200以上のモデルを扱う単一のOpenAI互換エンドポイントで、プロバイダー間の自動フェイルオーバーと、プロバイダーの定価を0%のマークアップでそのまま適用するものです。当社はモデルをホストしていますが、Claude Codeを作っているわけではなく、お客様のリポジトリ内の何も当社には見えません。

検索はこれからも「skills」と言い続けるでしょう。なぜなら、エージェントの振る舞いを変えるためにインストールするものを指す言葉として、人々がそれを使っているからであり、このリポジトリを囲むパッケージングも同じ言葉を使っているからです。成果物はファイルです。3つの具体的な不満に対処する形で書かれた、常設の指示をまとめた1つの文書であり、4つの原則と、手作業で適用できる一連のテストを備えています。それらの不満が自分のリポジトリに当てはまるように聞こえるかで判断してください。それはスター数より良い問いです。スター数は、あなたが今したのと同じ反応をした人が何人いたかを測っていたにすぎません。