Claudeコードエージェントの構造化：CLAUDE.mdと.claude/ディレクトリパターン

エージェントディレクトリ構造

このセットアップでは、~/Documents/の下に各エージェント用の個別ディレクトリを作成します。例では5つのエージェントが示されています：planner（実行機能、ルーティング、責任管理）、content（コンテンツパイプライン）、youtube（YouTube制作）、life（個人領域）、control-center（ダッシュボード、データベース、API）。

各エージェントは次のテンプレート構造に従います：

agent-name/
├── CLAUDE.md # アイデンティティ + ミッション + 能力
├── .claude/
│   ├── rules/ # 自動読み込みコンテキスト（常時保持）
│   └── skills/ # オンデマンドワークフロー
├── inbox/ # 他のエージェントからの入力
├── outputs/ # 生成された出力
└── archive/ # アーカイブせずに削除しない

ルールとスキルの区別

.claude/rules/ファイルは、すべてのセッション開始時に自動的に読み込まれます。Claudeはこれらをコンテキストウィンドウの一部として読み取ります。ここには、エージェントが常に知っておく必要があるもの — その範囲、ビジネスコンテキスト、どのように振る舞うべきか — を配置します。

.claude/skills/ファイルはオンデマンドです。/skill-nameで呼び出したときにのみ読み込まれます。ここには、マルチステッププロセス、テンプレート、構造化されたルーティンなどの特定のワークフローを配置します。

ルールファイルはセッション開始時にコンテキストウィンドウに読み込まれ、そこに留まります。Claude Codeはプロンプトキャッシングを使用するため、繰り返しコンテンツは毎回全額課金されませんが、大きなルールファイルは依然としてコンテキスト圧力を高め、応答品質の低下を引き起こす可能性があります。スキルでは、デフォルトでは名前と説明のみがコンテキストに保持され、完全なワークフローはオンデマンドで読み込まれます。これは、あなたが呼び出したとき、またはClaudeが関連性があると判断したときに読み込まれます。

経験則

• ルール（常時保持）： 範囲の境界、ビジネスコンテキスト、ルーティングロジック、命名規則 — すべての決定に影響を与えるもの
• スキル（オンデマンド）： ステップバイステップのワークフロー、テンプレート、バッチ操作。時折行うもの（注：スキルの説明は常にコンテキスト内にあり、Claudeは何が利用可能かを知っています。完全な内容のみがオンデマンドです）

CLAUDE.mdの内容

CLAUDE.mdファイルは120行以下に保ち、以下をカバーします：

• アイデンティティ（2-3行）：このエージェントが誰で、何をするか
• 現在のフェーズ（2-3行）：現在取り組んでいること
• コア能力（10-15行）：利用可能なスキル、何ができるか
• 主要な場所（10-15行）：参照が必要なファイルパス
• 構築されたもの（10-20行）：完了した作業の履歴
• 次のステップ（5-10行）：直近の優先事項
• 原則（5-10行）：行動のガードレール

ルール構造の例

プランニングエージェントの場合、.claude/rules/ディレクトリには読み込み順序を制御する番号付きファイルが含まれます：

.claude/rules/
├── 01-business-context.md # 収益モデル、ポジショニング、ターゲット顧客
├── 02-agent-ecosystem.md # すべてのエージェント、そのミッション、接続方法
├── 03-roadmap.md # 現在のフェーズ、マイルストーン、終了基準
├── 04-content-architecture.md # コンテンツチャネル、柱、ワークフロー
├── 05-daily-routine.md # スケジュール、アイデアフィルタリング、注意散漫防止ルール
├── 07-godin-strategy.md # マーケティング原則、マイルストーントラッキング
├── 08-control-center.md # CLIツールリファレンス、DBスキーマ
├── 98-end-of-session.md # 儀式：ロードマップ更新、知識のキャプチャ
└── 99-content-capture.md # すべてのセッションからコンテンツシグナルを自動抽出

エージェント間通信

エージェントは直接互いを呼び出しません。以下を通じて調整します：

• SQLiteデータベース：タスク、コンテンツパイプライン状態、セッション、メトリクスの信頼できる情報源
• インボックスファイル：あるエージェントが別のエージェントにコンテキストを渡す必要がある場合、ターゲットのinbox/にマークダウンファイルを配置します
• APIエンドポイント：ダッシュボード読み取り