CLAUDE.md：コーディングエージェントをシンプルに強化するファイル

優れたCLAUDE.mdはモデルを賢くしません。むしろ、エージェントがリポジトリに入るたびに、曖昧性を減らします。

このシンプルなメカニズムが、2026年で最も目立つエージェントプロジェクトの1つになった理由を説明します。4つの平易なコーディングルールを中心に構築されたリポジトリが、前後の文脈で9万1千以上のGitHubスターを獲得しました。このルールは、エージェントに仮定を明示させ、シンプルな実装を優先させ、変更を限定的にし、検証可能な成功を定義することを促します。これらのルール自体は新しいソフトウェアエンジニアリングではありませんが、全タスクの前に文脈に入れることは確実に有用です。

バイラルニュースでは、1つのファイルが91,000個のGitHubスターを獲得したと言われました。2026年8月2日時点で、このリポジトリはforrestchangからmultica-aiに移動し、プラグインとエディタルールに成長し、GitHubのAPIによると198,529スターに達しました。^[1] この数字は変わり続けるでしょう。持続的な教訓は、シンプルで永続的な指示がエージェント動作をどう変えるかです。

TL;DR

• CLAUDE.mdはクローディクラウドコードが文脈として読み込むMarkdownファイルです。^[2]
• バイラルリポジトリは、エージェント失敗の一般的なパターンを4つのルールに集約しました。コーディング前の思考、シンプルさ優先、限定的な変更、目標指向の実行です。^[3]
• このファイルは、ほぼ全タスクで必要な事実やルールが含まれているときに最も機能します。コマンド、アーキテクチャ、規約、境界線、検証です。
• CLAUDE.mdは文脈であり、強制ではありません。技術的なブロックが必要な場合は、権限やフックを使用してください。^[2]
• タスク固有の手順はスキルに、ファイル固有のガイダンスは.claude/rules/に置きます。全部をグローバルに読み込むと文脈を無駄にします。
• 有用なファイルは、保守可能なくらいに短く、テスト可能なくらいに詳細で、エージェントが誤りを繰り返すたびに改訂されます。

CLAUDE.mdとは？

CLAUDE.mdはClaudeコードのプロジェクト指示ファイルです。通常リポジトリのルートにコミットされた通常のMarkdownであり、エージェントに次のような永続的な文脈を与えます。

• プロジェクトのインストール方法、テスト方法、ビルド方法、フォーマット方法
• ファイル名から明らかでないアーキテクチャの一部
• 命名とコードスタイルの規約
• 手動で編集してはいけない生成ファイル
• タスク完了前にクリアすべきチェック
• リポジトリ固有のセキュリティ境界

Claudeコードはセッション開始時にこのファイルを読み込みます。Anthropicはこれを2つのメモリメカニズムの1つとして説明しています。CLAUDE.md指示は人が書き、Claudeの自動メモリは修正から学んだパターンを保存します。^[2]

これは設定に聞こえるかもしれませんが、Anthropicは重要な区別をしています。これらの指示はモデルの文脈に入ります。強制ではありません。「本番環境にデプロイしてはいけない」を保証する必要があれば、PreToolUseフックまたは権限の境界が適切なレイヤーです。Markdownの文はふるまいをガイドできます。セキュリティ保証は提供できません。

4ルールファイルがバイラルになった理由

multica-ai/andrej-karpathy-skillsと呼ばれるようになったリポジトリは、そのガイドラインがAndrej Karpathyの公開されたコーディングモデル失敗モードの観察に由来すると述べています。^[3] その人気をよく考えると、各ルールは一般的なフラストレーションをエージェントが実行できるふるまいにマップしています。

これらのルールはTypeScript、データベース設計、デバッグを教えません。不確実性とスコープへのアプローチ方法を形作ります。これにより、リポジトリ全体で再利用可能です。

シンプルさはまた社会的です。チームは2分間で4つの原則を読み、1つに異議を唱え、それを編集し、Gitで変更をレビューできます。隠れたプロンプトプラットフォームを管理する必要はありません。

4つの原則をプロジェクト動作に変えたもの

1. コーディング前に思考

元のガイドラインは、エージェントに仮定を述べ、必要に応じて複数の解釈を提示し、不要な複雑さに異議を唱え、本当に困ったら止まることを求めます。^[3]

プロジェクト固有の文言がそれを強化します。

APIコントラクトを変更する前に、リポジトリ内のすべての利用者を特定し、
変更が後方互換性があるかどうかを述べてください。プロダクト動作が曖昧な場合は、
静かに動作を選択せず、止まって質問してください。

汎用原則はスタイルを設定します。具体的な追加は、エージェントが誤った仮定が高くつく場所を告げます。

2. シンプルさ優先

「過度に設計しないでください」は方向性として有用ですが、検証が難しいです。リポジトリのシンプルのローカル定義を追加してください。

既存ユーティリティを新しい抽象化より優先してください。1つのコール場所に
サービス、ファクトリ、または設定フラグを導入しないでください。
要求されたふるまいだけを実装してください。オプションのフォローアップをリストしてください。

これは予測可能なモデルの傾向を減らします。現在のものではなく、仮説的な将来の問題ファミリーを解決します。

3. 限定的な変更

エージェントは広くを読んだ後、近くのクリーンアップ機会を見るため、そのタスクが全クリーンアップを許可することを意味しません。

変更されたすべてのラインはリクエストをトレースする必要があります。
周囲のフォーマットと命名を保存してください。編集で不使用になったインポートを削除し、
関連しないデッドコードの代わりにレポートしてください。

小さいdiffはレビュー、テスト、リバート、割り当てがより簡単です。また、エージェントがその目的を理解していないものを破る可能性を減らします。

4. 目標指向の実行

「とにかく動かす」のような指示は終了状態を定義しません。エージェントが確認できる結果にタスクを変換してください。

バグ修正の場合、本番コードを変更する前にテストで失敗を再現してください。
反復中に最も狭いチェックを実行し、完了前に必要なプロジェクトチェックを実行してください。
コマンドと結果をレポートしてください。

ここが自律性が有用になるところです。成功が観察可能なら、エージェントは最初の妥当な編集後に止まるのではなく、失敗で反復できます。

CLAUDE.mdに何を入れるか

Anthropicは、Claudeがすべてのセッションで保つべき事実をCLAUDE.mdに置き、より多くのステップまたは狭い手順をより対象のメカニズムに移すことを勧めています。^[2] 有用なテストは「ほぼすべてのタスクのオンボーディングでこれを繰り返しますか」です。

これらをルートファイルに入れてください

• 1段落のプロジェクトとアーキテクチャの説明
• パッケージマネージャーと標準的なインストール、開発、テスト、タイプチェック、ビルドコマンド
• ディレクトリ所有権と生成ファイル境界
• 言語またはパッケージ全体に適用されるルール
• 完了の定義
• 高頻度の誤りとその修正
• より深い指示を見つける場所

これらを別の場所に入れてください

シンプルなCLAUDE.mdテンプレート

これを開始点としてコピーし、ブラケット内をすべて置き換えてください。プロジェクトを制限しないセクションを削除してください。

# プロジェクト指示

## プロジェクト

[1段落：このリポジトリが提供するもの、主なランタイム、
最も重要なアーキテクチャ境界。]

## コマンド

- インストール: `[コマンド]`
- 開発: `[コマンド]`
- 限定されたテスト: `[ファイルまたはパターン付きコマンド]`
- 完全テスト: `[コマンド]`
- タイプチェック: `[コマンド]`
- ビルド: `[コマンド]`

## 編集前に

- 提案された変更の前に最も近い既存実装とテストを読んでください。
- 公開動作、データ、セキュリティ、または互換性に影響する仮定を述べてください。
- リクエストが複数の実質的に異なる解釈を持つ場合は、質問してください。

## スコープ

- 要求されたふるまいだけを実装してください。
- 新しい抽象化より既存パターンとユーティリティを優先してください。
- 必要でない限りdiffを限定的に保ってください。隣接するコードをリファクタしないでください。
- 変更で作成されたデッドコードだけを削除してください。

## プロジェクト境界

- `[パス]`は生成されます。代わりに`[ソースパスまたはコマンド]`を変更してください。
- `[パッケージ]`は`[責任]`を所有します。`[他のパッケージ]`で重複しないでください。
- ログまたはフィクスチャに`[シークレットまたはプライベートデータカテゴリ]`を公開しないでください。

## スタイル

- [フォーマッタのデフォルトと異なるか見逃しやすい2〜5つのルール。]
- 明示的なルールがない場合、周囲のファイルに合わせてください。

## 検証

- バグ修正の場合、修正前に失敗するテストを追加または更新してください。
- 反復中に最も狭いチェックを実行してください。
- 完了前に実行してください：`[必要なコマンド]`。
- 変更されたファイル、実行されたコマンド、結果、検証されていないリスクをレポートしてください。

## より深い指示

- APIの仕事：`.claude/rules/api.md`
- データベース変更：`[スキルまたはドキュメンテーションパス]`
- リリース：`[スキルまたはドキュメンテーションパス]`

テンプレートは意図的にシンプルです。CLAUDE.mdは動機付けのマニフェストのように読むべきではありません。エージェントが別の推測をしなければならなくなるはずの推測を減らすべきです。

Claude Codeが複数の指示ファイルをどのように読み込むか

Claude Codeは現在のワーキングディレクトリから上へディレクトリツリーを移動し、見つけたCLAUDE.mdとCLAUDE.local.mdファイルを読み込みます。起動ディレクトリに近い指示は、文脈で遅く現れます。ワーキングディレクトリの下のネストされたファイルは、Claudeがそれらのサブディレクトリ内のファイルを読むときに読み込まれます。^[2]

モノレポについて、それは有用な階層を許可します。

repo/
├── CLAUDE.md                 # 組織全体のプロジェクト事実
├── .claude/
│   └── rules/
│       ├── testing.md        # スコープされていない共有ルール
│       └── api.md            # paths: packages/api/**
├── packages/
│   ├── web/
│   │   └── CLAUDE.md         # Web固有のアーキテクチャとチェック
│   └── worker/
│       └── CLAUDE.md         # Worker ランタイム制約
└── CLAUDE.local.md           # 開発者のみのローカルノート

ファイルは厳密な設定オーバーライドのように動作するのではなく、文脈として連結されます。矛盾するルールは矛盾した動作を生じる可能性があります。定期的に階層をレビューし、古い指示を削除してください。

実際の失敗からファイルを改善する方法

1日目のあらゆる可能な誤りを予測しようとしないでください。小さく始め、繰り返されるフリクションをバックログとして使用してください。

1. 失敗を記録してください。 エージェントが何をしましたか、何を予想しましたか？
2. 正しいレイヤーを探してください。 これは普遍的な指示、パススコープルール、タスク手順、またはハードセキュリティコントロールですか？
3. 観察可能なルールを書いてください。 「注意して」を行動と条件に置き換えてください。
4. 類似したタスクでテストしてください。 ふるまいは改善しますが、些細な仕事をブロックしませんか？
5. 古いルールを削除してください。 文脈にはコストがあります。古い指示は指示がないより悪い可能性があります。

Anthropicの実用的なトリガーは記憶に値します。Claudeが同じ誤りを2回したときか、コードレビューが、エージェントが持つべき知識を見つけたときか、セッション全体で同じ修正を繰り返したときに、何かを追加してください。^[2]

避けるべき5つのCLAUDE.mdの誤り

指示の代わりに願いを書く

「優れた堅牢なコードを書く」は新しい情報を与えません。「packages/apiの下の変更後にpnpm test --filter apiを実行する」は追いかけでき、確認できます。

巨大な汎用ルールブックをコピーする

公開テンプレートはアイデアを提供できますが、無条件のラインはすべて文脈を消費し、プロジェクトと競合する可能性があります。役に立つ場合は4つの広いふるまい原則を保ちますが、一般的な技術的な助言を、ローカル事実に置き換えてください。

エージェントが安く発見できる事実を符号化する

各ディレクトリをリストにする必要はめったにありません。ファイル名が明かさない境界線を説明してください。例えば、どのパッケージが認可を所有しているか、またはどのソースが確認されたクライアントを生成するか。

指示をセキュリティコントロールとして扱う

「シークレットを読まない」または「デプロイしない」を唯一の保護として依存しないでください。ハード境界については、スコープ付き認可情報、権限、サンドボックス、フックを使用してください。

ファイルをレビューしない

コマンドは変わります、パッケージは移動します、古い例外はデフォルト動作になります。所有権を割り当てコードのようにCLAUDE.mdをレビューしてください。

それが機能しているかどうかを知る方法

1つのデモが印象的かどうかでファイルを判断するのを避けてください。チームがすでにレビューしている仕事を計測してください。

• 完了したタスクあたりの中央値変更行
• 接触された関連しないファイル
• リポジトリ規約違反により引き起こされたレビューコメント
• 1回のパス成功
• 主張した完了後に再度開かれたタスク
• 永続的な文脈になるべき繰り返される明確化

バイラルリポジトリは同じ結果レベルのテストを示唆しています。より少ない不要なdiff変更、より少ない過度な複雑さによる書き直し、誤りの後ではなく実装の前の明確化。^[3]

FAQ

CLAUDE.mdはどこに行くべきですか？

チーム共有プロジェクト指示については、./CLAUDE.mdまたは./.claude/CLAUDE.mdに置きコミットしてください。~/.claude/CLAUDE.mdを個人の指示に使用し、1つのプロジェクトの個人的なノートにCLAUDE.local.mdを使用してください。^[2]

CLAUDE.mdはCursorまたは他のコーディングエージェントで機能しますか？

CLAUDE.mdはClaudeコード規約です。バイラルリポジトリはCursorルールとプラグインも提供し、他のエージェントはAGENTS.mdまたはプロダクト固有のルールディレクトリのようなファイルを使用する可能性があります。標準的なソースを保ち、全ツール同じファイルを読み込むと仮定するのではなく、意図的に適応させてください。

CLAUDE.mdはどれくらい長くするべきですか？

普遍的な行数はありません。ほぼすべてのセッションで価値のある情報を含むべきです。セクションが1つのディレクトリまたは1つのワークフローに適用される場合は、パススコープルールまたはスキルに移してください。

CLAUDE.mdは破壊的なコマンドを止められますか？

それはClaudeに実行しないよう指示できますが、Anthropicはファイルを設定ではなく文脈として明示的に説明します。信頼できる予防には、権限またはフックを使用してください。^[2]

最初のファイルをどのように作成しますか？

Claude Codeで/initを実行してスターターCLAUDE.mdを生成するか、Markdownファイルを手動で作成してください。その後/contextを実行してそれが読み込まれたことを確認し、/memoryを実行してメモリファイルを確認または編集してください。^[4]

ファイルがシンプルなのは問題が繰り返されるからです

コーディングエージェントは、バグを修正する前に500行の憲法を必要としません。推測できない数個のプロジェクト事実、リクエストされた変更の周囲の明確な境界線、完了と信頼を区別するチェックが必要です。

だからこそ、4つの通常のルールは遠くに行きました。開発者がほぼ毎日見る誤りに対処し、全チームが編集できる形式に存在し、エージェントが決定を始める前に読み込まれます。そこから始めてください。プロジェクト知識は実際の失敗を防ぐときだけ追加し、プロンプトの外側の重要な境界を強制してください。

ツール自体が新しい場合は、より広いClaude Codeの使用ガイドから始めてください。インストールが完了し、次の問いはエージェントがリポジトリに入るたびに知るべきことであるときに、この記事を使用してください。

References

1. GitHub REST API. multica-ai/andrej-karpathy-skills repository metadata. Retrieved August 2, 2026. api.github.com
2. Anthropic. How Claude remembers your project. Claude Code Docs. Retrieved August 2026. code.claude.com
3. multica-ai. Karpathy-Inspired Claude Code Guidelines. GitHub. Retrieved August 2026. github.com
4. Anthropic. Claude Code commands. Retrieved August 2026. code.claude.com
5. Sumit Pandey. A Single CLAUDE.md File Went Viral. The Reason Is Embarrassingly Simple. Towards Deep Learning, May 2026. towardsdeeplearning.com

Further reading

• reAPI. How to use Claude Code. reapi.ai/blog/how-to-use-claude-code
• reAPI. How to get a Claude API key. reapi.ai/blog/how-to-get-claude-api-key
• reAPI. Claude model catalog. reapi.ai/models