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つあります。

1. Phase 1を並列実行する — 3つのリサーチエージェントを同時に起動します。直列だとコンテキストが偏りますが、並列にすることで多角的な視点が得られます
2. レビュアーが差し戻せる — 構成案と最終レポートの2段階でレビューが入ります。品質が基準を満たさなければ差し戻します
3. 各エージェントに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の見解が異なる場合は、両方の根拠を提示してもらい、最終判断は自分で行います。

日常の使い方

朝のルーティン

「おはよう」と打つだけで、以下が自動実行されます。

1. Google Calendarから今日の予定を取得
2. GitHub Issueから進行中タスクを取得
3. プロジェクト管理APIからマイルストーンを確認
4. タスクを「緊急度 × 重要度 × 認知負荷」で分類
5. 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の振る舞いが目に見えて安定します。この記事の設定をベースに、自分のワークフローに合わせてカスタマイズしてみてください。

参考リンク

• Claude Code 公式ドキュメント — サブエージェント
• Claude Code 公式ドキュメント — Skills

原文出處：https://qiita.com/nogataka/items/1ad4e4ccaf47816c63e0