Claude Codeを使い始めて最初の数週間、「これは革命だ」と感じる人は多いはずだ。自然言語でコードを書いてもらえる、テストも走らせてくれる、リファクタリングまでやってくれる。だが1〜2ヶ月も経つと、こんな不満が出てくる。「前と同じ指示を出したのに、また違うスタイルで書いてくる」「プロジェクトのルールを毎回説明するのが面倒」。この壁を突破するカギが CLAUDE.md の設計 だ。今回は、本業・副業・個人開発を並行させながらClaude Codeを日常業務のパートナーとして使い込んでいるエンジニアが実際に運用する設計と、それを軸にしたワークフローを紹介する。
CLAUDE.mdの階層構造を理解する
Claude Codeは複数の CLAUDE.md を階層的に読み込む。どこに何を書くかの設計が、まず第一歩だ。
~/.claude/CLAUDE.md ← グローバル設定（全プロジェクト共通）
<project>/.claude/rules/*.md ← プロジェクトルール（条件付き適用）
<project>/CLAUDE.md ← プロジェクト固有設定公式の優先順位は Enterprise policy → Project memory → User memory の順。グローバル設定には「自分の仕事の進め方」だけを書き、プロジェクト固有情報（ディレクトリ構造・ビルドコマンド等）を混ぜてはいけない。全プロジェクトに影響してしまうからだ。
グローバル設定の実例（~/.claude/CLAUDE.md）：
# グローバル設定
## 基本情報
- 結論ファースト。挨拶・前置き・段階報告は不要
- 敬語（です/ます体）で統一
## 行動原則
### 進め方
- 3ステップ以上のタスクは必ずPlanモードで開始する
- リサーチ・調査はサブエージェントに任せる
- サブエージェント1つにつき1タスク
### コンテキスト圧迫時の行動規範（焦ったら止まれ）
- コードを読まずに書かない
- 検証を省略しない
- 中途半端に終わらせるなら止まる
- 焦りを自覚したら宣言する「焦ったら止まれ」セクションは特に重要だ。コンテキストが残り少なくなるとClaude Codeはショートカットを取りがちになる。このルールを明文化しておくことで「コンテキストが残り少ないため、ここで区切ります」と正直に宣言してくれるようになる。
プロジェクト設定：スキル発火条件の設計
プロジェクト固有の CLAUDE.md では、ディレクトリ構造だけでなく「トリガーワードと対応スキルのマッピング」を定義するのがポイントだ。
## ワークフロー
### スキル発火条件
| トリガーワード | 発動スキル | 動作 |
|--------------|-----------|------|
| 「おはよう」 | /daily-schedule | 今日の工程表を作成 |
| 「調べて」 | /deep-research | リサーチチーム起動 |
| 「記事を書いて」 | /write-article | 記事執筆チーム起動 |
| 「覚えておいて」 | /agent-memory | メモリに保存 |「おはよう」と打つだけでGoogle Calendar・GitHub Issueを取得し、タスクを「緊急度 × 重要度 × 認知負荷」で分類、15分刻みの工程表を自動生成する。これが実際に動いているとなると、かなり強力だ。
サブエージェント設計：1エージェント1タスクの原則
.claude/agents/*.md にMarkdownファイルとして定義するサブエージェント。最大の失敗パターンは「1エージェントに複数の役割を持たせること」 だ。リサーチと分析を同じエージェントにやらせると、どちらも浅くなる。
リサーチチームの構成例（/deep-research スキル）：
- Phase 1（並列）: Web調査エージェント / 技術深掘りエージェント / 批判的分析エージェント
- Phase 2: シンセサイザー（統合・構造化）
- Phase 3: レビュアー（品質チェック・差し戻し可能）
- Phase 4: レポートライター →
output/research/に保存
並列実行することで多角的な視点が得られ、レビュアーが差し戻せるゲートを設けることで品質が担保される。レビュー工程を省略すると「構成が甘いまま執筆に入る」という手戻りが多発する——これは実際の失敗から学んだ教訓だ。
AIメモリの構造化：セッションをまたいだ知識の蓄積
プロジェクト内に独自メモリシステムを構築するのも効果的だ。
00_context/memories/
├── preferences.md # 文体の好み、ツールの使い方
├── decisions.md # 意思決定の記録（背景・決定・根拠）
├── context-log.md # 進行中プロジェクトの状況
└── case-judgment-framework.md # 判断パターン・基準「覚えておいて」と伝えると /agent-memory スキルが起動し、内容を自動分類して適切なファイルに保存する。重複があればスキップ、矛盾があれば確認を求める仕組みも組み込める。なお、サブエージェントに memory: user を設定すれば ~/.claude/agent-memory/<エージェント名>/ に専用メモリが保存され、セッションをまたいで知識が蓄積される。
設計原則まとめ
試行錯誤から見つかった原則を一覧で整理する。
| 原則 | 説明 |
|---|---|
| 階層を分ける | グローバル・プロジェクト・ルールの3層で情報を配置 |
| CLAUDE.mdは意思決定情報に絞る | コーディング規約などはLinterに委譲 |
| スキル発火条件を明示する | トリガーワードと対応スキルをテーブルで定義 |
| 1エージェント1タスク | 複数の役割を持たせると出力が散漫になる |
| レビュー工程を必ず入れる | 差し戻し可能なゲートを設ける |
| コンテキスト管理を明文化する | 残量が少ないときの行動規範を書く |
CLAUDE.mdは「プロジェクトの説明書」ではなく「AIとの仕事の進め方の設計書」だ。雑に書いている段階から、意図を持って設計する段階に移ると、Claude Codeの振る舞いが目に見えて安定する。元記事には各スキルの実際の定義例やMermaidフローチャートも掲載されており、そのまま参考にできる粒度で公開されている。Claude Codeを本格活用したいエンジニアには必読の内容だ。