Andrej Karpathy発「CLAUDE.md」4原則 — AIコーディングエージェントの品質を劇的に変えるルールファイル

「AIに書かせたコードが動くけど読めない」「頼んでいない箇所まで書き換えられた」「テストも実行もせずに"完了しました"と返ってくる」——コーディングエージェントを日常的に使うエンジニアであれば、これらの経験に身に覚えがあるはずです。生成AIへの期待が高まる一方で、こうした「やらかし」に悩む声は開発コミュニティで絶えません。

そんな課題に対し、Andrej Karpathyの観察をもとに作られたCLAUDE.mdファイルが、GitHubで急速な注目を集めています。「考えてからコードを書く」「最小限のコード」「必要な箇所だけ編集」「テストファースト」という4原則を1枚のMarkdownファイルに落とし込む、シンプルながら効果的なアプローチです。

本記事では、この4原則がなぜLLMコーディングの品質を改善するのかを具体例とともに解説し、あなたのプロジェクトへ今日から適用できる実践的な手順をお伝えします。

そもそも何が起きているのか — Karpathyの観察とCLAUDE.mdの流行

Andrej Karpathyが指摘した「LLMコーディングの違和感」

OpenAIの共同創業者であり、Tesla AI部門の元責任者でもあるAndrej Karpathyは、LLMをコーディングに活用する「vibe coding」という概念を広めた人物として知られています。ただし、Karpathy自身はエージェントに丸投げすることの限界についても鋭い観察を続けており、「生成量」よりも「どう介入を設計するか」が品質を決めるという視点を持っています。

その観察が蒸留されたのが、GitHubで公開されているmultica-ai/andrej-karpathy-skillsです。個人の気づきとして生まれたこのCLAUDE.mdが、再利用可能な形で公開されると、「自分もこれで悩んでいた」という共感からコミュニティで急速に拡散しました。

この記事で持ち帰れるもの

• LLMエージェントが犯す典型的な失敗パターンの整理
• CLAUDE.mdが内部でどう機能するかの仕組み
• 4原則それぞれの意味と具体的なCLAUDE.md記述例
• 自分のリポジトリへの段階的な導入手順

LLMコーディングエージェントが必ずやらかす5つの失敗パターン

CLAUDE.mdの価値を理解するには、まず「何を防ごうとしているのか」を把握する必要があります。実際の開発現場で繰り返し観察される失敗パターンを整理しましょう。

パターン1: 考える前に書き始める（Premature Coding）

LLMは「要件の曖昧さを質問せず、勝手な前提で実装を走らせる」傾向があります。「ユーザー認証機能を追加してください」という依頼に対して、JWTを使うかセッションを使うか、どのライブラリを使うかを確認せずにコードを書き始めてしまう——その結果、手戻りコストが自分で書いた場合を超えることになります。

パターン2: 過剰実装（Over-engineering）

「関数を1つ追加してください」という依頼に対して、インターフェース・抽象クラス・設定ファイル・エラーハンドリングレイヤーまで自動的に追加してくるケースがあります。LLMは「丁寧に書こう」とすると過剰実装に振れやすい性質を持っています。こうして生まれる「AI Slop」（AIが量産する使い捨てコード）は、レビューコストと保守コストを直撃します。

パターン3: 無断リファクタリング（Scope Creep）

「この関数のバグを直してください」と頼んだら、ファイル全体が整形・変数名変更・コメント追加された状態で返ってきた——という経験はないでしょうか。diffが数百行に膨れ上がり、本来の修正箇所がどこか探すのに時間がかかります。

パターン4: 動作未検証の「完了」宣言

LLMは実行環境を持たないため、「コードを書いた」ことと「動作を確認した」ことが等価に扱われがちです。存在しないAPIや関数を呼び出すハルシネーションも、実行してみるまで表面化しません。

パターン5: 既存の作法を無視した独自流儀

プロジェクトがPyTestを使っているのにunittestで書く、既存のユーティリティ関数があるのに別途実装する、命名規則から外れた変数名を導入する——LLMはプロジェクト固有の文脈を知らない状態でコードを書くため、こうした不整合が頻発します。

CLAUDE.mdはどうやってエージェントの動作を制御するのか

CLAUDE.mdの正体 — 「毎回読まれるシステムプロンプト」

CLAUDE.mdはClaude Codeがセッション開始時に自動でコンテキストへ注入するMarkdownファイルです。技術的には「永続化されたシステムプロンプト」であり、毎回プロンプトに書かなくても一定の指示を保持し続けられます。

都度プロンプトに「必ず実装前に設計を確認してください」と書くことも効果はありますが、忘れた瞬間にエージェントは元の動作に戻ります。CLAUDE.mdに記載することで、その指示がデフォルト動作として定着します。

置き場所とスコープ

CLAUDE.mdには3つの配置場所があり、それぞれスコープが異なります。

• ~/.claude/CLAUDE.md：全プロジェクト共通の個人的な作法。「常にテストを書く」「変更前に必ず理解する」など、自分のコーディング方針を定義します。
• リポジトリ直下のCLAUDE.md：チームで共有する規約。技術スタック・命名規則・禁止ライブラリなど、プロジェクト固有のルールを記載します。gitにコミットしてチーム全員が同じエージェント動作を得られます。
• サブディレクトリのCLAUDE.md：モジュール単位の上書き。フロントエンドとバックエンドで異なるルールを定義する場合などに活用します。

効く指示・効かない指示の境界線

CLAUDE.mdに何を書いても同じ効果があるわけではありません。

効果が高い記述：

• 具体的な禁止事項（「未使用のヘルパー関数を追加しない」）
• 手順の明示（「実装前に変更対象ファイルを列挙すること」）
• 判断基準（「既存ライブラリで実現できる場合は自前実装しない」）

効果が低い記述：

• 「良いコードを書いてください」のような抽象的な精神論
• 矛盾する複数のルール
• 長大すぎて中間が読まれにくくなるCLAUDE.md（コンテキスト希釈）

ベストプラクティスとして、CLAUDE.mdは最初は20〜30行の最小構成から始め、必要に応じて育てていくことを推奨します。

原則1: Think Before Coding — 考えてからコードを書く

何を指示するのか

この原則は、エージェントに「理解 → 設計 → 確認」のステップを明示的に踏ませることを目的としています。要件に不明点があれば仮定で埋めさせず、必ず質問させます。

Before / Afterの具体例

Before（指示なし）： 「ユーザーにメール通知を送る機能を追加して」と依頼 → SMTPサーバーの設定、テンプレートエンジンの導入、queue処理の実装まで含む300行のコードが返ってくる。メールプロバイダーは何を使うかすら確認されない。

After（Think Before Codingあり）： 「既存のSendGridクライアントがあること、テンプレートはtemplates/email/以下にあること、notification_service.pyに追加することを確認しました。変更対象は1ファイル、追加は約40行の予定です。進めてよいですか？」という確認が先に来る。

CLAUDE.mdへの記述サンプル

## Think Before Coding

- 実装を始める前に、変更対象ファイルと実装方針を3行以内で述べること
- 要件に曖昧さがある場合は、推測で補わず質問すること
- 既存のコードを読んでからコードを書くこと。既存のパターン・スタイル・ライブラリを踏襲すること
- 新しい依存関係を追加する場合は、追加理由を明示すること

原則2: Simplicity First — 最小限のコードで解く

「動くコード」と「最小のコード」は違う

コードの行数はレビューコストと保守コストに直結します。LLMは「丁寧に、堅牢に、将来の変更に対応できるように」書こうとする傾向があり、これが過剰実装につながります。

実際の開発現場では、コードは書いた量より削った量で品質が決まります。「コードを足す」よりも「コードを足さない」という判断が、長期的にはチームの生産性を守ります。

過剰実装を止める具体的な禁止事項

• 求められていない抽象化レイヤー・インターフェース・設定項目を作らない
• 使われていないヘルパー関数・防御的コードを足さない
• 既存のライブラリで実現できることを自前実装しない
• 「将来的に必要になるかもしれない」機能を先取り実装しない

CLAUDE.mdへの記述サンプル

## Simplicity First

- 要求された機能だけを実装する。将来の拡張を先取りしない
- 新しい抽象化を導入する場合は、その理由を述べること
- 同じことが実現できるなら、常に行数の少ない方を選ぶ
- 未使用のコード・コメントアウトされたコード・TODO コメントを残さない
- 既存ライブラリで代替できる場合、新しいユーティリティ関数を作らない

原則3: Surgical Changes — 必要な箇所だけを編集する

「ついでのリファクタリング」が最大の敵

「1行のバグ修正」を依頼したのに、ファイル全体が整形されて変数名が変わり、コメントが英語から日本語に統一された状態で返ってくる——これは単なる「過剰な親切」ではなく、開発フローの破壊です。

レビュー不能な巨大diff、意図していない挙動変更のリスク、git履歴の汚染——Surgical Changesはこれらすべてを防ぐための原則です。

CLAUDE.mdへの記述サンプル

## Surgical Changes

- 依頼された箇所のみを変更する。無関係な整形・コメント追加・変数名変更をしない
- コードスタイルやフォーマットの修正は、明示的に依頼された場合のみ行う
- スコープ外の改善案は実行せず、「提案」としてコメントにとどめること
- 変更完了後、変更したファイル名と変更行数を報告すること

運用のコツ：小さいコミット単位で回す

Surgical Changesの原則を守るには、依頼の粒度を小さくすることも重要です。「認証機能を追加して」ではなく「JWTトークンの検証関数をauth/token.pyに追加して」と具体化することで、エージェントのスコープを自然に絞れます。段階的に理解を深めていきましょう——エージェントへの指示設計もまた、スキルです。

原則4: Test-First Verification — 検証してから「完了」と言わせる

LLMの「できました」を信用してはいけない理由

LLMは実行環境を持ちません。「コードを書いた」ことと「動作を確認した」ことを意識的に区別しなければ、エージェントは書いた段階で完了と判断します。

ハルシネーション（存在しない関数やAPIの呼び出し）も、実行するまで表面化しません。Test-First Verificationは、「完了報告」と「動作証明」を明確に区別させるための原則です。

テストファーストをLLMに適用する形

LLMへのテストファースト適用は、人間のTDDとは少し異なるアプローチが現実的です。

1. 期待挙動をテストとして先に書かせる：実装前に「この関数はこう振る舞うはずだ」というテストを定義させます
2. 失敗を確認 → 実装 → パスを1サイクルで回させる：Red-Green-Refactorを1つの依頼単位でこなさせます
3. テストがない領域では実行ログを証拠として要求する：UIや外部APIなど自動テストが難しい領域では、実際の実行結果をログやスクリーンショットで示させます

CLAUDE.mdへの記述サンプル

## Test-First Verification

- 実装前に、期待挙動を検証するテストを書くこと
- テストを実行し、パスしたことを確認してから完了を報告すること
- 既存のテストが壊れていないことを確認すること
- 実行できない場合は「未検証」と明示すること。「動くはず」は完了ではない
- UIや外部APIなど自動テストが難しい場合は、実行ログまたは手順を示すこと

自分のプロジェクトにCLAUDE.mdを導入する手順

ステップ1: 最小構成から始める

いきなり網羅的なルールを書こうとしてはいけません。まず4原則だけを20〜30行で書きます。完璧なCLAUDE.mdより、使えるCLAUDE.mdの方が価値があります。

ステップ2: プロジェクト固有ルールを追加する

4原則の後ろに、そのリポジトリ固有の情報を追記します。

## プロジェクト概要

- 言語: Python 3.11 / TypeScript 5.x
- パッケージマネージャ: uv (Python) / pnpm (Node)
- テストフレームワーク: pytest / Vitest
- 禁止ライブラリ: requests（httpxを使うこと）

## よく使うコマンド

- テスト実行: `pytest tests/ -v`
- Lint: `ruff check . && mypy src/`
- ビルド: `pnpm build`

ステップ3: 失敗するたびに1行足す

CLAUDE.mdは「育てるドキュメント」です。エージェントがやらかすたびに、そのパターンを防ぐルールを1行追加します。逆に、すでに守られているルールは削除します。肥大化したCLAUDE.mdはコンテキストを希釈し、かえって効果を下げます。

ステップ4: チームで共有する

リポジトリにコミットしてコードレビューの対象にすることで、チーム全員が同じエージェント動作を得られます。個人の好みはグローバル設定(~/.claude/CLAUDE.md)に、チームの規約はリポジトリのCLAUDE.mdに分けるのがベストプラクティスです。

コピペで使えるCLAUDE.mdテンプレート

# CLAUDE.md

このファイルはClaude Codeのエージェント動作を制御するルール定義です。

## Think Before Coding

- 実装を始める前に、変更対象ファイルと実装方針を3行以内で述べること
- 要件に曖昧さがある場合は、推測で補わず質問すること
- 既存のコードを読んでからコードを書くこと。既存のパターン・スタイル・ライブラリを踏襲すること

## Simplicity First

- 要求された機能だけを実装する。将来の拡張を先取りしない
- 同じことが実現できるなら、常に行数の少ない方を選ぶ
- 未使用のコード・コメントアウトされたコードを残さない

## Surgical Changes

- 依頼された箇所のみを変更する。無関係な整形・改名・コメント追加をしない
- スコープ外の改善案は実行せず、コメントとして提示するにとどめること

## Test-First Verification

- 実装前に、期待挙動を検証するテストを書くこと
- テストを実行し、パスしたことを確認してから完了を報告すること
- 実行できない場合は「未検証」と明示すること

## プロジェクト固有ルール

<!-- ここにプロジェクトの技術スタック・コマンド・禁止事項を追記 -->

よくある疑問（FAQ）

CLAUDE.mdは長いほど良いのか？

いいえ、むしろ逆です。長すぎるCLAUDE.mdはコンテキストウィンドウを消費し、中間のルールが参照されにくくなります。まず最小限のルールで始め、実際に問題が発生したときだけ追加する「育て方」を推奨します。

Claude Code以外でも使えるのか？

CLAUDE.mdはClaude Code固有の仕組みですが、同様のコンセプトは他のエージェントにも適用できます。CursorやWindsurf、GitHub Copilot Workspaceでは.cursorrulesやAGENTS.mdなどの類似ファイルが使われます。原則そのものはツールを問わず有効です。

ルールを書いても守られないときは？

まず「ルールが具体的か」を見直してください。「丁寧なコードを書いて」は守られませんが、「新しい関数を追加する場合は理由をコメントで述べること」は守られます。それでも守られない場合、そのルールは指示ではなく願望である可能性が高いです。

既存のREADMEやコーディング規約とどう住み分けるのか？

READMEは人間向けのドキュメント、CLAUDE.mdはエージェント向けの行動規範です。重複してもかまいません。ただし、CLAUDE.mdには「エージェントが今すぐ実行できる具体的な手順」だけを書き、背景説明や設計思想はREADMEに任せるのがすっきりします。

まとめ — ルールを書くことは「レビュー基準を先に言語化する」こと

4原則を改めて整理します。

1. Think Before Coding — 実装前に理解・設計・確認を踏む
2. Simplicity First — 要求された機能だけを最小限のコードで実装する
3. Surgical Changes — 依頼された箇所だけを編集し、スコープを広げない
4. Test-First Verification — テストと実行ログで動作を証明してから完了とする

これらは実は、優れたエンジニアがコードレビューで指摘する典型的な観点そのものです。CLAUDE.mdはその基準を先に言語化し、エージェントへの「暗黙の期待」を「明示的な制約」に変えるものです。

エージェントの性能そのものよりも、どう制約を設計するかが成果を決める——この視点が、コーディングエージェントを本当に使いこなすための核心です。

今日やること： リポジトリのルートにCLAUDE.mdを作り、上のテンプレートを貼る。以上です。動かしながら育てていくのが、このファイルの正しい使い方です。