はじめに
Claude Codeを使い始めた直後は感動します。自然言語でコードが書ける、テストも回してくれる、リファクタリングまでやってくれる。ところが1ヶ月ほど経つと、壁にぶつかります。
- 「前にも同じ指示を出したのに、また違うスタイルで書いてくる」
- 「プロジェクトのルールを毎回説明するのが面倒」
- 「サブエージェントを使いたいけど、どう設計すればいいかわからない」
この壁を越えるカギが CLAUDE.md の設計です。
筆者は本業・副業・個人開発を並行して進めており、Claude Codeを日常業務のパートナーとして使っています。最初は雑にCLAUDE.mdを書いていましたが、構造を設計し直してから、指示のやり直しが激減しました。この記事では、実際に運用しているCLAUDE.mdの設計と、それを軸にしたワークフローを公開します。
この記事はClaude Code 2026年3月時点の機能に基づいています。サブエージェント、Agent Teams、Memory、Hooks等の機能を前提としています。
関連記事として、Claude Codeの基本的な使い方は「Claude Codeベストプラクティス -- 成果を安定させる7つの鉄則」、コンテキスト管理の具体的なコマンド操作は「Claude Codeのコンテキストを綺麗に保つ方法まとめ」で解説しています。本記事はそれらを踏まえた上での実践的な設計・運用ノウハウです。
CLAUDE.mdの階層構造
Claude Codeは複数のCLAUDE.mdを階層的に読み込みます。どこに何を書くかを設計することが重要です。
~/.claude/CLAUDE.md ← グローバル設定（全プロジェクト共通）
<project>/.claude/rules/*.md ← プロジェクトルール（条件付きで適用）
<project>/CLAUDE.md ← プロジェクト固有設定
公式のmemory hierarchyは「Enterprise policy → Project memory (./CLAUDE.md or ./.claude/CLAUDE.md) → User memory (~/.claude/CLAUDE.md)」です。.claude/rules/*.md は公式仕様ではなく、筆者が独自に運用しているルール分離の仕組みです。
グローバル設定（~/.claude/CLAUDE.md）
全プロジェクトに適用する「自分の仕事の進め方」を書きます。筆者の設定の構成は以下のとおりです。
# グローバル設定
## 基本情報
- 名前 / GitHub ID
- 結論ファースト。挨拶・前置き・段階報告は不要
- 敬語（です/ます体）で統一
## 役割
1. 経営パートナー — 戦略立案・意思決定支援
2. 秘書・アシスタント — スケジュール管理・タスク整理
3. テックリード — 技術的な意思決定・コードレビュー
## ツール
| ツール | 用途 |
|--------|------|
| gog CLI | Gmail・Calendar・Drive操作 |
| gh CLI | Issue管理・コード管理 |
| Smart Edit | LSPベースのコード編集支援 |
| Codex CLI | セカンドオピニオン・レビュアー |
## 行動原則
### コア
- シンプル第一。影響するコードを最小限にする
- 手を抜かない。一時的な修正は避ける
- 影響を最小化する
### 進め方
- 3ステップ以上のタスクは必ずPlanモードで開始する
- リサーチ・調査はサブエージェントに任せる
- サブエージェント1つにつき1タスク
### 検証
- 動作を証明できるまで完了としない
- テストを実行し、ログを確認する
ポイントは「AIに何をさせたいか」ではなく「自分がどう仕事を進めたいか」を書くことです。Claude Codeはこの設定を読んで、あなたの仕事の流儀に合わせた振る舞いをします。
グローバル設定にプロジェクト固有の情報（ディレクトリ構造やビルドコマンド等）を書かないでください。全プロジェクトに影響します。
プロジェクト設定（<project>/CLAUDE.md）
プロジェクトごとの固有情報を書きます。筆者が業務管理リポジトリで使っている設定の構成です。
# プロジェクト設定
## ディレクトリ構造
| ディレクトリ | 役割 |
|-------------|------|
| 00_context/ | プロフィール・経歴・AIメモリ |
| 01_strategy/ | 事業戦略・方針 |
| output/ | AI出力ファイル |
## ワークフロー
### スキル発火条件
| トリガーワード | 発動スキル | 動作 |
|--------------|-----------|------|
| 「おはよう」 | /daily-schedule | 今日の工程表を作成 |
| 「調べて」 | /deep-research | リサーチチーム起動 |
| 「記事を書いて」 | /write-article | 記事執筆チーム起動 |
## AIメモリ（00_context/memories/）
| ファイル | 内容 | 参照タイミング |
|---------|------|--------------|
| preferences.md | 文体の好み、常用ツール | 記事執筆時 |
| decisions.md | 意思決定の記録 | 類似の判断時 |
| context-log.md | 進行中プロジェクト | セッション開始時 |
「スキル発火条件」のテーブルは、筆者が実際に運用している仕組みです。特定のキーワードを発話すると、対応するSkillが自動的に起動します。CLAUDE.mdにこのマッピングを書いておくと、Claude Codeが自然言語のトリガーを認識してくれます。
プロジェクトルール（.claude/rules/*.md）
特定の条件でのみ適用するルールを分離します。これは筆者の独自運用であり、Claude Codeの公式機能ではありません。
.claude/rules/
├── codex-guidelines.md # Codex CLIの活用ルール
└── plan-template.md # Plan mode の計画テンプレート
たとえば plan-template.md には、計画を作成する際の固定フォーマットを定義しています。
## 必須セクション
| # | セクション | 形式 |
|---|-----------|------|
| 1 | なぜやるか | 散文（3行以内） |
| 2 | 何を変えるか | テーブル |
| 3 | どう実装するか | 番号付きリスト |
| 4 | 検証方法 | チェックリスト |
| 5 | リスク・注意点 | 箇条書き |
このテンプレートがあることで、Planモードの出力が毎回同じ構造になります。レビューしやすく、抜け漏れに気づきやすくなります。
ワークフローの全体像
筆者が日常的に回しているワークフローの全体像です。
サブエージェント設計
サブエージェントは .claude/agents/*.md にMarkdownファイルとして定義します。YAML frontmatterで設定を記述し、本文がシステムプロンプトになります。
リサーチチームの例
/deep-research スキルで起動するリサーチチームは6エージェント構成です。
設計のポイントは3つあります。
- Phase 1を並列実行する — 3つのリサーチエージェントを同時に起動します。直列だとコンテキストが偏りますが、並列にすることで多角的な視点が得られます
- レビュアーが差し戻せる — 構成案と最終レポートの2段階でレビューが入ります。品質が基準を満たさなければ差し戻します
- 各エージェントに1タスク — 「調べる人」「統合する人」「書く人」を分離します。1エージェントに複数の役割を持たせると、どちらも中途半端になりがちです
記事執筆チームの例
記事執筆にも同様のチーム構成を使っています。
# write-article スキル定義（抜粋）
## Phase 1: 並列リサーチ（3エージェント同時実行）
1. リサーチャーA（テーゼ分析）
2. リサーチャーB（事実調査）
3. リサーチャーC（批判的思考）
## Phase 2: 構成設計
構成エージェントが3本のリサーチを統合
## Phase 3〜5: レビュー → 執筆 → 最終レビュー
編集長が品質をチェックし、基準未達なら差し戻し
このチーム構成のおかげで、「リサーチ不足のまま書き始める」「構成が甘いまま執筆に入る」といった問題が起きにくくなりました。
AIメモリの設計
Claude Codeのメモリ機能（~/.claude/CLAUDE.md のユーザーメモリ）とは別に、プロジェクト内に独自のメモリシステムを構築しています。
00_context/memories/
├── preferences.md # 文体の好み、ツールの使い方
├── decisions.md # 意思決定の記録（背景・決定・根拠）
├── context-log.md # 進行中プロジェクトの状況
└── case-judgment-framework.md # 判断パターン・基準
「覚えておいて」と伝えると /agent-memory スキルが起動し、内容を自動分類して適切なファイルに保存します。
分類の基準は以下のとおりです。
保存時には重複チェックも行います。同じ内容が既に記録されていればスキップし、既存の記録と矛盾する場合は確認を求めます。
サブエージェント単位のpersistent memoryも利用できます。memory: user を設定すると ~/.claude/agent-memory/<agent名>/ にサブエージェント専用のメモリが保存され、セッションをまたいで知識が蓄積されます。
コンテキスト管理の工夫
Claude Codeを長時間使っていると、コンテキストウィンドウの圧迫が課題になります。筆者はCLAUDE.mdに「焦ったら止まれ」というセクションを設けています。
### コンテキスト圧迫時の行動規範（焦ったら止まれ）
- コードを読まずに書かない
- 検証を省略しない
- Planモードを飛ばさない
- サブエージェントを使う（コンテキスト節約）
- 中途半端に終わらせるなら止まる
- 焦りを自覚したら宣言する
これを書いた背景があります。コンテキストが残り少なくなると、Claude Codeはショートカットを取りがちです。ファイルを読まずにコードを書いたり、テストを省略したりします。そこで「品質を落とすくらいなら、正直に中断を宣言してくれ」と明示しました。
この規範を入れてから、「コンテキストが残り少ないため、ここで区切ります」と宣言してくれるようになりました。中途半端な出力を受け取るよりも、はるかに助かります。
セカンドオピニオンの仕組み
筆者はOpenAI Codex CLIをセカンドオピニオンとして組み込んでいます。.claude/rules/codex-guidelines.md にルールを定義しています。
## いつ使うか
### 必須（自動実行）
- 資料・成果物を作成した後 → Codexにレビューを依頼
- 重要な意思決定の前 → Codexの見解を聞く
### 推奨
- アプローチが2回以上失敗したとき
- 複数の選択肢で迷ったとき
- 専門外の領域で自信がないとき
Claude自身の出力をClaude以外のモデルにレビューさせることで、盲点を減らしています。Claude自身の判断とCodexの見解が異なる場合は、両方の根拠を提示してもらい、最終判断は自分で行います。
日常の使い方
朝のルーティン
「おはよう」と打つだけで、以下が自動実行されます。
- Google Calendarから今日の予定を取得
- GitHub Issueから進行中タスクを取得
- プロジェクト管理APIからマイルストーンを確認
- タスクを「緊急度 × 重要度 × 認知負荷」で分類
- 15分刻みの工程表を生成
午前中に認知負荷の高いタスク（開発・設計）、午後にミーティングやルーティン作業を配置します。各タスク間に5分のバッファを入れるのがコツです。
リサーチ
「○○について調べて」で6エージェントのリサーチチームが起動します。所要時間は10〜15分ほどです。最終的にレポートが output/research/ に保存されます。
複数の視点（Web最新情報・技術的背景・批判的分析）を並列で集め、シンセサイザーが統合するため、自分で検索して回るよりも網羅性が高くなります。
記事執筆
この記事自体も、筆者のClaude Code環境で書いています。記事執筆チームが起動し、リサーチ → 構成 → レビュー → 執筆 → 最終レビューのパイプラインを回します。
失敗から学んだこと
失敗1: CLAUDE.mdに全部書きすぎた
最初のCLAUDE.mdは200行を超えていました。ディレクトリ構造、コーディング規約、コミットメッセージのルール、全てを1ファイルに詰め込んでいました。
結果、Claude Codeは重要な指示を見落とすことが増えました。コンテキストの優先度が平坦になり、何が重要かわからなくなっていたのです。
対策として、CLAUDE.mdは「意思決定に関わる情報」に絞り、機械的に検証できるルール（コーディング規約等）はLinterに任せるようにしました。.claude/rules/ への分離も効果的でした。
失敗2: サブエージェントに複数の役割を持たせた
初期は「リサーチも分析も1エージェントでやれば速いだろう」と考えていました。結果、出力が散漫になりました。調査しながら分析すると、どちらも浅くなります。
「1エージェント = 1タスク」の原則を徹底してから、各エージェントの出力品質が上がりました。
失敗3: レビュー工程を省略した
記事執筆パイプラインを最初に作ったとき、「リサーチ → 構成 → 執筆」の3ステップで回していました。レビュー工程がないため、構成が甘いまま執筆に入り、手戻りが多発しました。
編集長エージェントを追加し、構成案と最終原稿の2段階でレビューを入れたことで、差し戻し前提の品質管理ができるようになりました。
設計のポイントまとめ
筆者が試行錯誤の中で見つけた設計原則を整理します。
| 原則 | 説明 |
|---|---|
| 階層を分ける | グローバル・プロジェクト・ルールの3層に情報を配置する |
| CLAUDE.mdは意思決定情報に絞る | 機械的に検証できるルールはLinter等に委譲する |
| スキル発火条件を明示する | トリガーワードと対応スキルをテーブルで定義する |
| 1エージェント1タスク | 複数の役割を持たせると出力が散漫になる |
| レビュー工程を必ず入れる | 差し戻し可能なゲートを設ける |
| コンテキスト管理を明文化する | 残量が少ないときの行動規範を書く |
| メモリを構造化する | 分類基準を決め、自動振り分けする |
まとめ
CLAUDE.mdは「プロジェクトの説明書」ではなく「AIとの仕事の進め方の設計書」です。
- 階層構造で情報を整理し、グローバル・プロジェクト・ルールを分離する
- サブエージェントを1タスク1エージェントで設計し、レビュー工程を組み込む
- AIメモリを構造化し、セッションをまたいで知識を蓄積する
- コンテキスト管理のルールを明文化し、品質低下を防ぐ
CLAUDE.mdを雑に書いている段階から、意図を持って設計する段階に移ると、Claude Codeの振る舞いが目に見えて安定します。この記事の設定をベースに、自分のワークフローに合わせてカスタマイズしてみてください。