CLAUDE.mdの仕組み——毎回の会話で自動読み込み
Anthropicの公式ドキュメントによると、CLAUDE.mdはClaude Codeが「あらゆる会話の開始時に読み込む特別なファイル」だ。プロジェクトのルートディレクトリ（フォルダの一番上）にこのファイルを置くだけで、Claudeはそのルールを毎回の作業前に確認する。「毎回同じ指示をコピペする」という手間が一切なくなる。

なぜClaude Codeは「暴走」するのか
Claude Codeを既存のコードベースで長時間使うと、勝手にリファクタリングする・関係ないファイルまで変更する・巨大なdiffを作る・過剰に抽象化する・曖昧な要件を勝手に解釈して実装するという問題が起きやすい。これは「AIの能力が低い」のではなく、AIエージェントに明確な行動制約を与えていないことが原因だ。

CLAUDE.mdに何を書くか——Anthropicの推奨
Anthropicは「使用するBashコマンド・コードスタイル・ワークフロールールを含めることで、Claudeがコードから推測できない永続的なコンテキストを提供できる」と述べている。形式は決まっておらず、短く人間が読みやすい形が推奨される。毎回のセッションで読み込まれるため、広く適用できることだけを書くのがポイントだ。

Andrej Karpathyとは何者か
Andrej Karpathyは元TeslaのAIディレクター（自動運転を担当）、元OpenAI創業メンバーのひとりで、現在は個人研究者として活動している。AI研究の世界では「わかりやすい解説をする人」として知られ、彼のチュートリアル動画や論文は世界中のエンジニアに読まれている。2024年末に「もうほとんど自分でコードを書かない、80%がAIエージェント経由になった」と発言し話題になった。

「AIで最も変わった20年間」という発言と失敗の観察
Karpathyは2024年12月にコーディングの80%をマニュアルからエージェント駆動に切り替え、「20年間で最大のコーディングワークフローの変化だ」と述べた一方で、繰り返し起きる失敗パターンを名指しした。モデルが前提を黙って走らせてしまう・モデルが混乱を隠す・モデルが要求されていない変更を加える・モデルが「どうやるか」を明示されないと適切にループできない——という4つの問題だ。

Forrest Changがファイルに変換した
2026年1月27日、開発者のForrest Chang（Jiayuan Zhang）がKarpathyの観察をCLAUDE.mdというファイルに落とし込んでGitHubに公開した（forrestchang/andrej-karpathy-skills）。MITライセンスで公開されたこの65行のファイルは、2026年5月時点でGitHub史上最も多くスターがついたリポジトリのひとつになった。Karpathyが問題を特定し、Changが解決策をコード化したという役割分担だ。

なぜ「アイデアファイル」として広まったのか
このリポジトリはKarpathyが「アイデアファイル」と呼ぶパターンを体現している。実装でも、インポートするライブラリでも、アプリでもない。誰でも自分のプロジェクトに合わせて応用できる「原則の集合」だ。これはオープンソースの新しい形——コードではなくアイデアをオープンにするという発想だ。

【原則1】Think Before Coding——「前提を明示し、混乱を隠すな」

この原則が防ぐのは「沈黙の思い込み問題」だ。AIは曖昧な指示をもらっても止まらず、自分の判断で解釈して作業を進める。その解釈が間違っていたとき、完成後に全部やり直しになる。「まず確認する」というルールを入れることで、この無駄を防ぐ。

【原則2】Simplicity First——「頼まれたことだけをシンプルにやれ」

AIは「より良くしようと」して過剰なコードを生成しがちだ。「ボタンを赤くして」と頼んだのに、なぜかコンポーネント全体をリファクタリングする——という体験をしたことがある人は多いだろう。Simplicity Firstはこの「善意の過剰」を防ぐ。

【原則3】Surgical Changes——「要求された部分だけを変えろ」

「外科的な変更」というのは、手術で必要な部位だけにメスを入れるイメージだ。AIは「ついでに」関係ないコードも修正しようとする。それが意図しないバグを生む。Surgical Changesはそのリスクを根本から防ぐ。

【原則4】Goal-Driven Execution——「成功条件を与えてAIに自律的にループさせろ」

Goal-Driven Executionの考え方は「成功条件を定義してAIが自律的にループできるようにする」ことだ。「バリデーションを追加して」という手順指示より「無効な入力のテストを書いて、それが通るようにして」という目標指示の方が、AIは自律的に作業を完結させやすい。

①「作業前に計画を立てろ」——無駄な作業の防止

②「禁止リスト」——絶対にやってはいけないことを明示

③「レスポンス形式の統一」——出力の品質を標準化

④「コードベースの地図」——どのフォルダに何があるかを教える

⑤「確認のタイミング」——勝手に進まず適切なタイミングで止まる

⑥「コンテキスト管理」——長い会話でAIが迷子になるのを防ぐ

ギャップ①：セッション予算の未定義
Karpathyの原則はセッション長について沈黙している。予算の境界がないと、デバッグループが90分走り続け、すでに試みて拒否した変更を再提案し始めることがある。タスクあたり約4,000トークン・セッションあたり約30,000トークンという上限と、上限に近づいたら要約して新しいセッションを始めるというルールがこれを防ぐ。

ギャップ②：ステップ間のチェックポイント未設置
Goal-Driven Executionは「成功条件を定義してループせよ」と言うが、「途中で止まって報告せよ」とは言っていない。6ステップのリファクタリングでステップ4が失敗した場合、チェックポイントなしだとステップ5・6を壊れた状態の上に実行してしまう。修正より全部やり直す方が早い事態になりかねない。

ギャップ③：コンテキスト劣化への対策なし
最も成功しているClaude Codeユーザーは、CLAUDE.mdファイル・積極的な/clear使用・ドキュメントシステムを通じてコンテキストを徹底管理している。コンテキストの劣化がClaude Codeの主要な失敗モードだ。長い会話でAIは過去の決定を忘れ、同じ提案を繰り返す。定期的にコンテキストをリセットするルールを明示する必要がある。

ギャップ④：エラー処理の手順未定義
「Surgical Changes」はどこを変えるかを制限するが、エラーが起きたときにどう対処するかは定義していない。エラーが出たら「即座に報告し、修正案を提示した上で指示を待つ」というルールを明示することで、AIが壊れた状態で突き進むのを防ぐ。

Skillsとは何か——「CLAUDE.mdとの違い」
Skillsの基本構造は、SKILL.mdという単一ファイルで構成されるディレクトリだ。ファイルの上部にYAML形式で名前と説明を書き、その下にClaudeが実行する指示を書く。それだけだ。スラッシュコマンド（例：/run-tests）で明示的に呼び出せるほか、Claude Codeが関連するタスクを認識したときに自動でトリガーすることもできる。

海外エンジニアに人気のSkills例
Skills化で最も人気なのは「テスト実行・PR作成・依存関係の更新・バグ修正」などの繰り返しタスクだ。Skillsなしの場合、バグを修正するよう頼むとdocstringを追加・クォートを整形・型ヒントを追加・隣接するロジックを書き直すなど余分な変更をしがちだ。Skillsがあれば、変更は3行だけになる。

「SKILL.mdはどこでも使える」——Claude Codeだけの話ではない
注目すべき点は、Agent Skillsの仕様はオープンスタンダードであり、Claude Code・OpenAI Codex CLI・Gemini CLI・Cursor・GitHub Copilotなど主要なAIコーディングアシスタントをまたいで同じSkillが使える。一度書けばどこでも使える。これは「AIツールが変わっても資産が引き継げる」という大きなメリットだ。

Routines——Skillsをスケジュール実行する仕組み
Skillsをさらに進化させたのが「Routines」という仕組みだ。Skillをスケジュール・API・GitHubイベントに応じて自動実行できる。毎晩の依存関係更新・マージ時のchangelogの自動生成・新しいissueの自動トリアージなどが自動化できる。Skillsが「繰り返し作業のレシピ」なら、Routinesはそのレシピを「スケジュールで自動調理する」仕組みだ。

65行のテキストファイルがGitHub史上最もスターを集めたリポジトリのひとつになったという事実は、世界中のエンジニアが同じ問題——「AIは優秀だが、制約なしには暴走する」——に直面していることを示している。

計画してから実装すること・シンプルさが複雑さを打ち負かすこと・コンテキスト管理が最重要であること——これらはClaude Codeに限らず、すべての高品質なソフトウェア開発に共通する原則だ。

AIツールの進化は「何ができるか」から「どう使うか」の段階に入った。CLAUDE.mdはその変化を象徴する。エンジニアにとっては「AIの行動ルールを設計するスキル」が、非エンジニアにとっては「AIに適切な制約を与える発想」が、2026年以降のAI活用の中核能力になっていく。