プロジェクト初期セットアップとコンテキスト管理 (CLAUDE.md)
AIエージェントを活用する際に最も注意すべき点は、**コンテキストオーバーフローとハルシネーション(Hallucination)**です。これを防ぐための核心ツールが claude.md ファイルです。
⚠️ 重要：必ずプロジェクトルート(Root)ディレクトリで実行してください
Claude Codeは現在のディレクトリを基準にファイルを探索します。サブフォルダ（例：/apps/api）で実行してしまうと、プロジェクト全体の構造を読み取れず、엉뚱なコードを書いたりファイルを見つけられない問題が発生します。常にトップレベルのルートディレクトリで実行する習慣をつけましょう。
/init コマンドと CLAUDE.md の階層構造
ターミナルで /init を実行すると、プロジェクトの説明書的な役割を果たす claude.md が生成されます。
- グローバル適用：
~/.claude/claude.md（全プロジェクト共通ルール。例：「常に日本語で回答すること」） - プロジェクト適用：
プロジェクトルート/claude.md（該当プロジェクト専用のアーキテクチャおよびコンベンション）
💡 claude.md のトークン最適化と分割戦略（重要）
AIが毎回 claude.md を読み込むため、ファイルが長くなりすぎるとトークンが大幅に無駄になります。
- 300文字以内に維持： ルートにある
claude.mdは核心のみを要約して300文字以内に軽く保ちましょう。（推奨事項） - フォルダ別に分割： DB関連のルールは
/supabase/claude.mdに、API関連のルールは/api/claude.mdに別途作成しましょう。Claudeが該当フォルダを作業する時だけ詳細ルールを読み込むため、はるかに効率的です。
トリガーキーワード (Trigger Keyword) の設定
繰り返されるパイプライン（例：テスト通過時にコミット後プッシュ）を claude.md にトリガーキーワードとして登録しておくことができます。
「デプロイ(Ship)という単語を入力したら 1. テスト実行 2. 失敗時に中断 3. 通過時に git add & commit 4. push の順で進めてください」 これでClaudeコードに「デプロイ」と入力するだけで、上記の一連のプロセスが自動的に実行されます。
🤝 コンパウンドエンジニアリング（チーム単位のコンテキスト同期）
claude.md をGitリポジトリにコミットしてチーム全体で共有しましょう。あるチームメンバーがアーキテクチャルールを更新すると、他のメンバーも同じルールとコンテキストの上でAIを使用できるようになります。
💡 ヒント：直接編集せずAIに任せる 会話中に新しいコーディングコンベンションやルールを決めたら、claude.md ファイルを直接開いてタイピングする必要はありません。
「今決めたパターンをclaude.mdに追加してください」 と指示すれば、Claudeが自動的にファイルを更新してくれます。