午前2時のコンテキストの悪夢
時刻は午前2時14分。あなたは赤字で埋め尽くされたターミナル画面を凝視しています。本番環境でバグが発生し、始業時間までに修正するためにAIアシスタントに頼っています。しかし、問題が発生しました。AIは npm run dev を提案し続けますが、あなたのレガシープロジェクトでは独自の make shell コマンドを使用しています。チームはCSS Modulesを厳格に使用しているのに、AIは存在しないTailwind CSSのクラスを生成し続けます。プロンプトを書くたびに、「これはしないで」「代わりにこれを使って」という400語の指示から始めなければなりません。
トークンの無駄遣いと絶え間ない修正は、生産性を著しく低下させます。結局、コードを修正することよりも、AIの思い込みを管理することにエネルギーを費やすことになってしまいます。CLAUDE.md ファイルは、この問題を解決します。これは、プロジェクトのビルド、テスト、スケーリングの方法を正確に定義する、永続的な「信頼できる情報源（Source of Truth）」として機能します。
クイックスタート：5分で作成する最初のCLAUDE.md
即座に効果を得るために、複雑な設定は必要ありません。CLAUDE.md は、プロジェクトのルートディレクトリに配置するシンプルなMarkdownファイルです。Anthropicの Claude Code CLIや Cline 拡張機能などの最新ツールは、このファイルを自動的に読み取り、動作を最適化します。
ファイルを作成し、以下の基本構造を記述してください：
# プロジェクトのコンテキスト：決済ゲートウェイAPI
## ビルドと開発
- ビルド: `make build`
- テスト: `pytest tests/unit`
- リント: `flake8 .`
- ローカル開発: `docker-compose up`
## コーディング規約
- すべての関数シグネチャにPythonの型ヒントを使用すること。
- I/Oバウンドなタスクにはスレッドよりも `async/await` を優先すること。
- エラー：`src/core/exceptions.py` のカスタム例外を使用すること。
- ドキュメント：Googleスタイルのdocstringのみを使用すること。
## アーキテクチャ
- パターン：ヘキサゴナル / ポート＆アダプター
- ドメインロジックは `src/domain` に配置する。
- データベースロジックは `src/infrastructure/db` に配置する。このファイルが存在すれば、AIは推測をやめます。最初のメッセージから、あなたのテストランナー、リントルール、アーキテクチャの境界線を把握できるようになります。
なぜこの戦略が有効なのか
コンテキストウィンドウが20万トークンに達しても、LLMは大規模なコードベースのノイズの中で迷子になることがあります。CLAUDE.md を提供することは、モデルに高密度の地図を渡すようなものです。AIがパターンを推測するために500個のファイルをスキャンする代わりに、まずこの地図を読み取ります。
ビルド＆テストセクション
ここは自律型エージェントにとっての「エンジンルーム」です。AIがテストを実行できなければ、自身の作業を検証することもできません。以下の4つの特定のコマンドタイプを含めることで、存在しないコマンドを捏造する「ハルシネーション」が90%近く減少することがわかっています。
- 依存関係のインストール： （例：
pip installではなくpoetry install） - きめ細かなテスト： 単一のテストファイルを実行する方法と、全スイートを実行する方法。
- データセットアップ： データベースのシード投入やマイグレーション実行のコマンド。
- クリーンアップ： Redisキャッシュやビルド成果物を消去する方法。
暗黙のルールの強制
どのコードベースにも、公式ドキュメントにはないけれど全員が従っている「暗黙の知識」が存在します。例えば、.format() よりも f-strings を好む、あるいはネストを減らすために else ブロックを避けるといったルールです。これらが CLAUDE.md に記載されていない場合、AIは学習データに基づいた一般的なパターンをデフォルトで使用します。これらの好みを明示することで、AIの出力を後で修正するのではなく、AIをあなたのスタイルに適応させることができます。
複雑なフォルダ構成のナビゲート
AIがディレクトリの階層構造を理解していると思い込んではいけません。/dist が自動生成されるなら、そこを無視するようにAIに伝えてください。/scripts に重要なデプロイツールがあるなら、それを指摘してください。このシンプルなステップにより、AIが実はミニファイされたビルド成果物であるファイルを「リファクタリング」しようとするのを防げます。
複雑なプロジェクトのための高度な戦術
リポジトリが成長するにつれ、単純なコマンドリストでは不十分になることがあります。CLAUDE.md を使用して、微妙な技術的負債や特定の環境制約をナビゲートできます。
環境固有の情報
macOSとLinuxでプロジェクトの動作が異なる場合は、それを文書化してください。これにより、最小構成のAlpine Dockerイメージ内で作業しているときに、AIが apt-get コマンドを提案するのを防げます。使用しているパッケージマネージャー（Poetry、Bun、Pnpmなど）を明記し、AIが正しいロックファイルを使用するようにします。
### 開発環境
- ランタイム: Node.js v20.11 (LTS)
- パッケージマネージャー: pnpm
- 注意: 単発のバイナリ実行には常に `pnpm dlx` を使用すること。ライブラリの制約
requests と httpx のように、似た目的のライブラリが2つインストールされていることはよくあります。設定ファイルを使用して、どちらを使うべきか強制してください。例えば、「データバリデーションには pydantic v2を使用し、v1の構文は使用しないこと」とAIに伝えます。これによりコードベースの一貫性が保たれ、古いパターンが紛れ込むのを防げます。
「ステート（状態）」戦略
長期にわたるリファクタリングの場合、私は「現在のステータス」セクションを維持しています。この動的なエリアに進捗を記録します。午後6時に作業を終えて翌朝戻ってきたとき、AIはこのセクションを読み、どのモジュールが完了していて、どこがまだ壊れているかを即座に把握します。
実践的なメンテナンスのヒント
CLAUDE.md ファイルは、正確であってこそ価値があります。テストランナーを Mocha から Vitest に切り替えたのにファイルの更新を忘れると、なぜテストが失敗するのかについてAIと20分間議論する羽目になります。
- Gitにコミットする： このファイルをコアインフラの一部として扱いましょう。プルリクエスト（PR）の際にも変更内容を確認します。
- 簡潔にする： 長い文章は避けてください。AIモデルは、散文よりも箇条書きや見出しをはるかに効率的に処理します。
- アンチパターンを定義する： 開発者が同じ間違いを繰り返しているのを見かけたら、「禁止事項」セクションを追加します。AIに「TypeScriptで
any型を使用しないこと」と伝えます。 - 人間のオンボーディング： このファイルは、新しく入った人間のメンバーのための「スタートガイド」としても役立ちます。チーム全体にとってメリットがあります。
午前2時にデバッグをしているとき、ディレクトリ構造について10回目となる説明をしたくはないはずです. 今日、10分だけ時間を割いて CLAUDE.md を作成しましょう。それは、あなたの環境を隅々まで理解している、より集中力のある専門化されたアシスタントを、未来の自分にプレゼントすることになるのです。
