午前2時の惨劇：AIエージェントが暴走する時
時刻は午前2時14分。ターミナルのスクロールが速すぎて目が追いつきません。私はClaude Codeに「ログインコントローラーのバリデーションロジックを修正して」と頼んだだけなのですが、彼は現在、データベーススキーマ全体をリファクタリングしており、すでに12個の.env.exampleファイルを削除してしまいました。それらを「冗長」と判断し、リポジトリには不要だと決めつけたのです。
Anthropicの新しいCLIツールであるClaude Codeを使い始めた方なら、驚嘆と純粋な恐怖が入り混じったような感覚を味わったことがあるでしょう。このツールは信じられないほど高速です。しかし、手綱を握らなければ、エスプレッソを6杯飲んで初日から会社のレガシーコードベースを書き換えようとする新人開発者のように振る舞います。
その混乱を片付けた後、私は問題がAIにあるのではなく、私が「地図」を渡していなかったことに気づきました。その地図こそが.claude/ディレクトリです。このディレクトリを定義しないということは、チームの標準に関する知識がゼロの状態のエージェントを、本番環境のリポジトリで野放しにしているのと同じなのです。
なぜClaude Codeはプロジェクト構造についてハルシネーションを起こすのか
こう考えてみてください。ターミナルでclaudeを起動したとき、それは実質的に、暗い部屋に入ってきた高速で動くインターン生のようなものです。彼はファイルツリーを初期スキャンし、package.jsonを読んで、あなたがどのように仕事をしているかを推測します。
Claude Codeの失敗のほとんどは、以下の3つのギャップから生じます：
- コンテキストの不足： クラスよりも関数コンポーネントを好むことや、クリーンアーキテクチャのような特定のアーキテクチャパターンを使用していることを、彼は知りません。
- 境界の曖昧さ：
node_modules内のサードパーティライブラリのコードを「最適化」しようとしたり、/dist内のビルド成果物をいじったりします。 - 権限の不明確さ：
rm -rfやdocker-compose downのような破壊的なコマンドを、許可を取らずに実行してよいのか確信が持てません。
構造化された設定がない場合、エージェントは一般的なトレーニングデータに依存します。このデータは、プロジェクト固有の要件とは180度異なることがよくあります。
エージェントを制御する3つの方法
開発者は通常、3つの方法のいずれかでClaude Codeの挙動を制御しようとします。しかし、状況が複雑になると、そのうちの2つは失敗に終わります。
1. 「手動プロンプト」方式
すべてのプロンプトでルールを説明しようとする方法です：「バグを直して。ただしCSSは変更せず、インデントにはタブを使って。」 これは非常に疲れます。1回につき200〜500トークン余計に消費しますし、会話の履歴が長くなるにつれて、エージェントはいずれ指示を忘れてしまいます。
2. グローバル設定
自分のマシンにグローバルなエイリアスや環境変数を設定する方法です。自分一人ならうまくいきますが、チームメイトがリポジトリをクローンした瞬間に整合性が崩れます。オフィス内のラップトップごとに、AIアシスタントの挙動がバラバラになってしまいます。
3. .claude/ ディレクトリ（プロのアプローチ）
プロジェクトのルートに.claude/フォルダを作成することで、永続的な「信頼できる唯一の情報源（Source of Truth）」を確立します。このディレクトリはGitの履歴に残ります。すべての開発者、そしてAI自身が、まったく同じルールに従うことになります。私はこれを本番環境のマイクロサービスに適用しましたが、「ハルシネーションによるリファクタリング」を90%近く削減できました。
理想的な .claude/ の構成
プロジェクトをクリーンに保ち、AIエージェントの正気を保つためには、特定のファイルセットが必要です。本格的なTypeScriptやPythonプロジェクトにお勧めの構成を以下に示します。
my-project/
├── .claude/
│ ├── config.json
│ ├── custom_instructions.md
│ └── project_context.md
├── src/
└── ...1. config.json ファイル
このファイルはCLIの技術的な挙動を規定します。エージェントがどのツールを触れるかを定義します。安全な環境のための基本設定は以下の通りです：
{
"auto_execute_commands": false,
"allowed_tools": ["read_file", "write_file", "list_files", "grep_search"],
"theme": "dark",
"model": "claude-3-7-sonnet-latest"
}auto_execute_commandsをfalseに設定することは、私にとって必須の安全策です。これにより、データベースを消去したり保護されたブランチにプッシュしたりする可能性のあるコマンドを実行する前に、Claudeに必ず許可を求めるよう強制できます。
2. custom_instructions.md（ルールブック）
これは最も重要なファイルです。Claude Codeは自動的にこのファイルから指示を探し、コーディングスタイルを決定します。遠慮は無用です。要件については厳格に記述してください。
# プロジェクトのコーディング基準
- 新規ファイルにはすべてTypeScriptを使用すること。`any`型の使用は禁止。
- スタイリングにはTailwind CSSを使用。 .cssファイルは作成しないこと。
- `npm`の代わりに`pnpm`を使用すること。`npm install`は絶対に実行しない。
- バグ修正の際は、必ず最初にVitestのテストケースを作成すること。
- `/legacy`フォルダ内のファイルは絶対に修正しないこと。3. project_context.md（地図）
AIモデルは大規模なアーキテクチャの把握を苦手とすることがあります。個々のファイルは見えても、「全体像」を見失うのです。このファイルを使って、プロジェクトの各パーツがどのように組み合わさっているかを説明します。これにより、Claudeがアーキテクチャを「探す」必要がなくなるため、数千トークンの節約になります。
# プロジェクトのコンテキスト
これはApp Routerを使用したNext.js 14アプリです。
## 主要ディレクトリ:
- `/src/lib/api`: すべてのバックエンドfetchラッパーが含まれています。
- `/src/store`: グローバル状態管理のためにZustandを使用しています。
## アーキテクチャに関する注意点:
ヘキサゴナルアーキテクチャを採用しています。ビジネスロジックは`/src/core`に、
フレームワーク固有のコードは`/src/infrastructure`に配置してください。.claudeignore による保護の追加
.gitignoreと同じように、Claudeに見せてはいけないものを伝える必要があります。500MBのログファイルや機密性の高い認証情報がある場合は、Claudeにスキャンさせてはいけません。費用の無駄になりますし、セキュリティリスクも生じます。
Claude Codeは標準の.gitignoreを尊重しますが、明示的に指定することをお勧めします。Gitでは無視されていないがAIには読ませたくない/temp_dataフォルダなどがある場合は、custom_instructions.mdに追加するか、CLIのバージョンがサポートしていれば専用の.claudeignoreファイルを作成してください。
ワークフロー：『子守り』から『監督』へ
.claude/ディレクトリを導入すると、日々のワークフローが変わります。初歩的なミスの修正に追われることがなくなり、成果の管理に集中できるようになります。
- 初期化：
claudeを実行します。エージェントはすぐにcustom_instructions.mdを読み込みます。 - タスク指示： 「新しいユーザープロフィールページを追加して」といったハイレベルなコマンドを出します。
- 実行： Claudeは
project_context.mdを確認し、App Routerが使用されていることを把握して、迷うことなく正しいディレクトリを選択します。 - レビュー：
auto_execute_commandsがオフなので、ディスクに変更が加えられる前に計画を確認できます。
おわりに
.claude/ディレクトリの設定には10分ほどしかかかりません。しかし、それによって後々のAIによるハルシネーションのデバッグに費やす何時間もの時間を節約できます。この設定により、「知能」は汎用的なクラウドモデルから、あなたのコードベースを真に理解する特化型アシスタントへと進化します。
今すぐ.claude/ディレクトリをコミットしましょう。エージェントが勝手な解釈をせずルールに従ってくれることで、チームメイト、および将来の午前2時のあなた自身も救われるはずです。
