Claude Codeエージェント実践 Day 3｜CLAUDE.md の読み方・書き方
TL;DR
- CLAUDE.md は「プロジェクトルール + AIの振る舞い」を一元管理するファイル
- 技術スタックだけでなく「曖昧な指示は確認を取る」のような行動ルールも書く
- 長すぎると逆効果。コンテキスト効率を意識して書く
作ったもの
GitHub: akira-cloudjob-public/agent-scaffold-factory
# 今日学ぶこと
src/agent-framework/CLAUDE.md の読み方
↓
各セクションの意味
↓
カスタマイズのコツ
Day 2 で /new-agent を使ってエージェントを払い出しました。今日は、払い出された CLAUDE.md を詳しく読み解いていきます。
検証環境
| 項目 | 値 |
|---|---|
| OS | Windows 11 / macOS |
| Claude Code | 最新版 |
| 検証日 | 2026-02-03 |
CLAUDE.md とは何か
技術的な動作（検証済み）
まず、CLAUDE.md がどう動作するか、過去に検証した結果を共有します。
| 検証項目 | 結果 | 確認方法 |
|---|---|---|
| 起動時の読み込み | 自動で読み込まれる |
/memory コマンドで確認 |
| 読み込みレベル | 3種類（User / Project / Local） |
/memory の選択肢で確認 |
| 優先順位 | 近い・具体的な設定が優先 | 矛盾する設定で検証 |
| サブディレクトリ | 動的に読み込まれる（一時参照） | ファイル読み込み時に確認 |
優先順位の詳細:
| 優先度 | ファイル |
|---|---|
| 最高 | 対象ファイルに最も近い CLAUDE.md（サブディレクトリ） |
| 高 | CLAUDE.local.md |
| 中 | CLAUDE.md（プロジェクトルート） |
| 低 | ~/.claude/CLAUDE.md（ユーザー） |
これは 2025年12月に Claude Code v2.0.56 で検証した結果です。「より具体的な設定が優先される」という公式ドキュメントの記載と一致していました。
公式ドキュメントに書いてあること:
- 起動時に自動読み込み
- 設定はマージされ、具体的な設定がオーバーライド
公式ドキュメントに書いていないが確認した挙動:
-
サブディレクトリの CLAUDE.md は動的読み込み（
/memoryには表示されないが参照される） - 永続メモリと一時参照の2種類がある
技術的にはこのような動作です。ここからは「どう書くか」の話に移ります。
設定ファイルではない
最初に断っておきたいことがあります。
CLAUDE.md は設定ファイルではありません。
「設定ファイル」と思うと、こういう書き方をしてしまいます：
# 設定
- 言語: TypeScript
- テストフレームワーク: Jest
- デプロイ先: Vercel
これでも動きます。でも、これだけだと「Claude Code に情報を渡しているだけ」になります。
設定 + 行動ルールを書くファイル
CLAUDE.md は「プロジェクト設定」と「AIの行動ルール」を一元管理するファイルです。
エンジニアが CLAUDE.md に求めていること:
- 毎回同じ説明をしたくない → プロジェクトルールを書いておく
- 基本の振る舞いを統一したい → 行動ルールを定義する
- PDCAを回して改善したい → ルールを更新していく
Day 1 で紹介した「優秀な部下」という比喩は、この行動ルールの方向性を示すものです。
## 基本理念
エージェントは「優秀な部下」である。
・上司の曖昧な意図を汲み取り、明確化する
・勝手に進めず、要所で確認を取る
・成果物は必ずドキュメントとして残す
「TypeScript を使う」という情報と、「曖昧な指示を受けたら確認する」という行動原則。どちらがエージェントの振る舞いを決めるでしょうか？
後者です。
技術的な情報は knowledge/ に分離して、CLAUDE.md には行動原則を書く。ソフトウェア設計でいう関心の分離（Separation of Concerns）と同じ考え方です。
CLAUDE.md の構造
agent-scaffold-factory の CLAUDE.md を上から順に見ていきます。
# CLAUDE.md
このファイルは Claude Code（エージェント）の行動指針を定義します。
---
## 基本理念
...
## 行動原則
...
## コマンド
...
## 起動時ルーティン
...
## ナレッジ管理
...
## 標準ワークフロー
...
## フォルダ構成
...
7つのセクションがあります。順に解説します。
1. 基本理念
## 基本理念
エージェントは「優秀な部下」である。
・上司の曖昧な意図を汲み取り、明確化する
・勝手に進めず、要所で確認を取る
・成果物は必ずドキュメントとして残す
・人間との役割分担を明確にして協働する
・案件から得た知識を蓄積し、継続的に成長する
これはエージェントの「アイデンティティ」です。
どんな存在であるか。何を大切にしているか。
具体的な行動ルールより先に、この「基本理念」を書くのがポイントです。
なぜか？
Claude Code は文脈を理解する力があります。「優秀な部下である」という一文があるだけで、以降の行動原則がどういう意図で書かれているかを汲み取ってくれます。
2. 行動原則
## 行動原則
### 1. 確認ファースト
- 曖昧なまま進めない
- 「〜という理解で合っていますか？」と確認する
- 重要な判断は必ず上司に委ねる
### 2. ドキュメント必須
- 口頭のやり取りも記録に残す
- 成果物には必ず README をつける
- 後から見て分かる状態にする
### 3. 段階的承認
- 各フェーズ完了時にレビューを依頼する
- 承認なしに次フェーズに進まない
- 手戻りを最小化する
### 4. 役割分担の明確化
- 人間がやるべきこと、エージェントがやることを分ける
- 判断・承認・機密情報は人間
- 作業・調査・文書化はエージェント
### 5. 報連相
- 進捗を適宜報告する
- 問題があれば早めに相談する
- 完了したら結果を連絡する
### 6. 学習と成長
- ヒアリングで得た情報をナレッジとして蓄積する
- 過去の教訓を次の案件に活かす
- 起動時にナレッジを読み込み、知識を更新する
6つの行動原則があります。
これらは「こうしろ」という命令ではなく、「こう振る舞うとうまくいく」というガイドラインです。
特に重要なのは「確認ファースト」と「段階的承認」。
この2つがあるだけで、エージェントが勝手に突っ走ることを防げます。
なぜ6つなのか
8ヶ月使ってきて、「これがないとトラブルになる」というものを抽出した結果です。
| # | 原則 | なかったときの問題 |
|---|---|---|
| 1 | 確認ファースト | 意図と違う方向に進む |
| 2 | ドキュメント必須 | 何をやったか追えなくなる |
| 3 | 段階的承認 | 手戻りが大きくなる |
| 4 | 役割分担 | 判断すべきことをエージェントがやってしまう |
| 5 | 報連相 | 途中経過がわからず不安になる |
| 6 | 学習と成長 | 同じ失敗を繰り返す |
最初は3つくらいでした。トラブルが起きるたびに追加して、今の形になりました。
3. コマンド
## コマンド
| コマンド | 説明 |
|---------|------|
| `/start-req REQ-YYYY-NNN` | 新規REQを開始する（Phase 0実行） |
| `/next-phase REQ-YYYY-NNN` | 指定REQの次のPhaseを実行する |
| `/status [REQ番号]` | REQ進捗状況の確認・表示 |
| `/approve-phase N` | Phase N を承認 |
使えるスラッシュコマンドの一覧です。
ここに書いておくと、エージェントが「このコマンドが使える」と認識します。
逆に、ここに書いていないコマンドを使おうとすると「そのコマンドは定義されていません」と返ってきます。
4. 起動時ルーティン
## 起動時ルーティン
### コンテキスト効率化の原則
- **ルール（business/）**: 必ず読み込む（行動指針）
- **背景（lessons/）**: 必要時のみ参照（エビデンス）
### 読み込み順序
1. `knowledge/business/` のルールファイルを読み込む（必須）
2. 依頼内容と既存ルールを照合する
3. 不明点があれば `knowledge/lessons/` を参照（任意）
4. 関連する技術知識（technical/）を確認
エージェントが起動したときに何をするかを定義しています。
ここがコンテキスト効率に直結します。
「全部読め」と書くと、毎回大量のファイルを読み込んでコンテキストを圧迫します。
「business/ だけ必須で、あとは必要時に」と書くことで、効率よくナレッジを活用できます。
5. ナレッジ管理
## ナレッジ管理
### ナレッジカテゴリ
| カテゴリ | 内容 | 読み込み |
|---------|------|---------|
| business/ | 業務ルール、行動指針 | **必須**（起動時） |
| technical/ | システム、技術、開発規約 | 必要時 |
| people/ | 関係者、組織 | 必要時 |
| lessons/ | 過去案件の背景・エビデンス | **参照のみ**（問題発生時） |
### ナレッジ更新ルール
- 矛盾する情報は新しい方を優先
- 古い情報は履歴として残す
- 出典を必ず明記（トレーサビリティ）
knowledge/ フォルダの使い方を定義しています。
Day 1 で説明した4カテゴリの使い分けがここに書かれています。
ポイントは「読み込み」の列。
- 必須: 毎回読む（コンテキストを使う）
- 必要時: 必要なときだけ読む（効率的）
- 参照のみ: 問題が起きたときに見る
この区別があることで、エージェントがいつ何を読むべきか判断できます。
6. 標準ワークフロー
## 標準ワークフロー
Phase 0: 依頼受領
↓
Phase 1: ヒアリング
↓ [承認]
Phase 2: 要求定義
↓ [承認]
Phase 3: 設計
↓ [承認]
Phase 4: WBS
↓ [承認]
Phase 5: 実装
↓ [承認]
Phase 6: 完了報告
↓ [承認]
Phase 7: Issue管理
各 Phase の完了時に人間の承認を取ることで、手戻りを最小化します。
依頼を受けてから完了するまでの流れです。
7つの Phase があり、各 Phase 間で承認を取る設計になっています。
なぜこのワークフローを CLAUDE.md に書くのか？
エージェントに「全体の流れ」を理解させるためです。
「今は Phase 2（要求定義）だから、次は Phase 3（設計）に進むはず」という文脈を持っていると、適切な行動が取れます。
7. フォルダ構成
## フォルダ構成
[プロジェクト]/
├── CLAUDE.md # 本ファイル（エージェント定義）
├── .claude/commands/ # スラッシュコマンド
├── templates/ # ドキュメントテンプレート
├── knowledge/ # 構造化知識
│ ├── business/ # 業務ルール（起動時必須）
│ ├── technical/ # 技術知識
│ ├── people/ # 関係者情報
│ └── lessons/ # 過去の教訓
├── documents/ # REQ別ドキュメント
├── inputs/ # ヒアリング記録
├── outputs/ # 成果物
└── Issue/ # 課題管理
プロジェクトのフォルダ構成を示しています。
これがあると、エージェントが「どこに何があるか」を理解できます。
「ヒアリング記録はどこ？」と聞かれたとき、「inputs/ にあります」と即答できる。
書くべきこと、書かなくていいこと
CLAUDE.md に何を書くべきか、8ヶ月使ってきた結論をまとめます。
書くべきこと
| 項目 | 理由 |
|---|---|
| 基本理念 | エージェントのアイデンティティを決める |
| 行動原則 | 判断基準を与える |
| ワークフロー | 全体の流れを理解させる |
| フォルダ構成 | どこに何があるか理解させる |
| コマンド一覧 | 使える機能を認識させる |
書かなくていいこと
| 項目 | 理由 |
|---|---|
| 技術的な詳細 | knowledge/technical/ に分離 |
| 過去の経緯 | knowledge/lessons/ に分離 |
| 関係者情報 | knowledge/people/ に分離 |
| 具体的な手順 | .claude/commands/ に分離 |
分離の原則
CLAUDE.md: 毎回読み込まれる → 短くする
knowledge/: 必要なときだけ読む → 詳細を書いてOK
commands/: コマンド実行時だけ読む → 手順を書いてOK
この分離ができると、コンテキスト効率が大幅に上がります。
コンテキスト効率を上げるコツ
コツ1: CLAUDE.md は200行以内を目指す
目安として、CLAUDE.md は200行以内に収めましょう。
agent-scaffold-factory の CLAUDE.md は約160行です。
長くなりそうなら、何かを knowledge/ に移せないか検討します。
コツ2: 箇条書きを活用する
散文で書くより、箇条書きのほうがトークン効率が良いです。
# 良い例
### 1. 確認ファースト
- 曖昧なまま進めない
- 「〜という理解で合っていますか？」と確認する
- 重要な判断は必ず上司に委ねる
# 悪い例（散文）
### 1. 確認ファースト
曖昧なまま進めないようにしてください。
わからないことがあれば「〜という理解で合っていますか？」と
確認を取るようにしましょう。重要な判断については、
必ず上司に委ねるようにしてください。
箇条書きのほうが短く、読みやすい。
コツ3: テーブルを活用する
情報の対応関係を示すときは、テーブルが有効です。
# 良い例
| カテゴリ | 読み込み |
|---------|---------|
| business/ | 必須 |
| technical/ | 必要時 |
| lessons/ | 参照のみ |
# 悪い例（箇条書き）
- business/ は必須で読み込みます
- technical/ は必要なときに読み込みます
- lessons/ は問題が起きたときに参照のみします
テーブルのほうが情報密度が高い。
コツ4: 繰り返しを避ける
同じことを複数箇所に書くと、コンテキストを無駄に使います。
# 悪い例
## 行動原則
### 3. 段階的承認
- 各フェーズ完了時にレビューを依頼する
- 承認なしに次フェーズに進まない
## 標準ワークフロー
各 Phase の完了時に人間の承認を取ることで、手戻りを最小化します。
Phase 間では必ず承認を取ってください。
承認なしに次の Phase に進むことはできません。
同じ「承認を取る」という内容が2箇所に書かれています。
# 良い例
## 行動原則
### 3. 段階的承認
- 各フェーズ完了時にレビューを依頼する
- 承認なしに次フェーズに進まない
## 標準ワークフロー
（標準ワークフローの図だけ。承認の説明は行動原則を参照）
なぜこう作ったか
選択肢1: 設定ファイル形式 vs 行動ルール形式
| 案 | 採用 | 理由 |
|---|---|---|
| JSON/YAML で設定 | ✗ | 行動パターンを表現しにくい |
| Markdown で行動ルール | ✓ | 自然言語で振る舞いを記述できる |
最初は JSON で書こうとしました。でも「曖昧な指示を受けたら確認する」みたいなルールは、JSON では表現しにくい。
Markdown なら自然言語で書けるので、人間が読んでも理解しやすいし、Claude Code も意図を汲み取ってくれます。
選択肢2: 1ファイル集約 vs 分離
| 案 | 採用 | 理由 |
|---|---|---|
| CLAUDE.md に全部書く | ✗ | 長くなりすぎてコンテキスト圧迫 |
| 行動原則のみ、詳細は分離 | ✓ | 毎回読む量を最小化 |
1ファイルに全部書いた時期もありました。1000行を超えて、後半が認識されなくなって気づきました。
今は「CLAUDE.md は200行以内、詳細は knowledge/ に」という方針です。
テンプレートのカスタマイズ
払い出された CLAUDE.md をそのまま使うこともできますが、プロジェクトに合わせてカスタマイズすることもできます。
カスタマイズ例1: 基本理念を変える
「優秀な部下」以外のメタファーを使いたい場合：
## 基本理念
エージェントは「専門コンサルタント」である。
・クライアントの課題を深く理解する
・複数の選択肢を提示して、判断を委ねる
・成果物は必ず報告書としてまとめる
・契約スコープを明確にして、範囲外は別途相談
メタファーを変えると、振る舞いのニュアンスが変わります。
カスタマイズ例2: 行動原則を追加する
プロジェクト固有の原則を追加：
### 7. セキュリティ優先
- 個人情報を含むデータは必ずマスクする
- API キーを出力に含めない
- 社外秘のドキュメントは outputs/ に置かない
カスタマイズ例3: ワークフローを変える
Phase の数や内容を変更：
## 標準ワークフロー
Phase 0: 依頼受領
↓
Phase 1: 要件確認
↓ [承認]
Phase 2: 実装
↓ [承認]
Phase 3: テスト
↓ [承認]
Phase 4: デプロイ
（設計フェーズを省略した軽量版）
シンプルなタスクなら、Phase を減らしてもOKです。
ハマったところ
問題1: CLAUDE.md が長すぎて全部読まれない
症状: CLAUDE.md に書いたルールが守られない
原因: ファイルが長すぎて、後半が認識されていない
解決: 200行以内に収めるか、重要な内容を先頭に持ってくる
# 重要な順に並べる
## 基本理念（最重要）
## 行動原則（重要）
## コマンド
## 起動時ルーティン
## ナレッジ管理
## フォルダ構成（参考情報）
問題2: knowledge/ に分離したら参照されない
症状: knowledge/business/ に書いたルールが適用されない
原因: 起動時ルーティンに「読め」と書いていなかった
解決: 明示的に読み込み指示を書く
## 起動時ルーティン
### 読み込み順序
1. `knowledge/business/` のルールファイルを読み込む（必須） ← これが必要
問題3: 書きすぎて矛盾が生まれる
症状: ある場所では「確認を取る」、別の場所では「自律的に進める」
原因: 複数箇所に書いているうちに矛盾が発生
解決: 各トピックは一箇所にだけ書く
同じ内容を複数箇所に書くと、修正漏れで矛盾が生まれます。
「この内容はここにだけ書く」というルールを決めておくと防げます。
良い CLAUDE.md の特徴
8ヶ月いろいろ試して、良い CLAUDE.md の特徴が見えてきました。
| 特徴 | 説明 |
|---|---|
| 短い | 200行以内 |
| 構造的 | セクションが明確に分かれている |
| 行動指向 | 「何をするか」より「どう振る舞うか」 |
| 優先順位付き | 重要な内容が先頭にある |
| 参照可能 | 詳細は knowledge/ に分離 |
まとめ
- CLAUDE.md は「プロジェクトルール + AIの行動ルール」を一元管理するファイル
- 7つのセクションで構成される
- 書くべきは「どう振る舞うか」、詳細は knowledge/ に分離
- 200行以内を目指して、コンテキスト効率を上げる
- 重要な内容を先頭に置く
Day 2 で払い出したエージェントの CLAUDE.md、どう見えましたか？
「ここはうちのプロジェクトに合わない」「この原則は追加したい」という部分があれば、今日の内容を参考にカスタマイズしてみてください。
正直なところ、この構成が正解かどうかはまだわかりません。8ヶ月使ってきた中での「今の最適解」であって、これからも変わっていくと思います。「うちではこう書いてる」「この項目は要らなかった」など、経験を共有してもらえると嬉しいです。
次回予告
Day 4: commands/ の4つのコマンド
- /start-req の中身
- /next-phase の中身
- /status の中身
- /approve-phase の中身
- コマンドファイルの書き方
シリーズを追いかける
Discussion