08-02. CLAUDE.md でプロジェクトに記憶を持たせる

この回のゴール

• CLAUDE.md の役割と「毎セッション自動で読まれる」性質を理解する
• 何を書くべきで、何を書くべきでないかを判断できるようになる
• 自分のリポジトリで claude /init → 編集 → 動作確認まで一通りできる

1. 動機: 「素の Claude」 vs 「プロジェクトを知っている Claude」

08-01 で起動した Claude は、毎セッション コードベースの構造を一から調査 する。3 回目に同じ質問をしても同じ調査を繰り返す。

「あなたのプロジェクト固有のこと(規約・コマンド・絶対ルール)を 記憶として永続化 したい」 → CLAUDE.md の出番。

2. CLAUDE.md とは何か

• リポジトリ root に置く Markdown ファイル
• Claude Code 起動時に 自動で読み込まれる
• 内容は 「Claude にこのプロジェクトをどう扱ってほしいか」のメッセージ
• フォーマットは自由(セクション構成は読みやすさのため)

スコープ階層

複数あればすべて読まれる(優先度はリポジトリ近い方が強め)。

3. 何を書くべきか

書くと効く 🟢

• アーキテクチャの概要 (1〜2 段落、超要約)
• コマンド一覧 (make test, npm run dev, デプロイ手順)
• 絶対ルール / 落とし穴 (例: 「sites-enabled/ は symlink ではなく独立ファイル」)
• コーディング規約 (linter で表現できないもの。命名・コメント方針)
• 役割分担 (CLAUDE.md / README.md / 個別ドキュメントのどこに何が書いてあるか)

書かない方がいい 🔴

• コードベースから自動取得できる情報 (依存パッケージ一覧、ファイルツリー) — 二重管理になる
• 長文の解説(チュートリアル的な内容) — README.md にすべき
• TODO リスト(時系列で陳腐化) — Issue に置く
• API キーや認証情報 — 即削除、.env 経由で

4. ハンズオン

4.1 自動生成

cd <your-repo>
claude
> /init

→ Claude がプロジェクトを調査して CLAUDE.md のドラフトを生成。そのまま使わずに、編集する。

4.2 編集ポイント

• ノイズ削減: 自動生成された冗長な部分(ファイル一覧など)を削る
• ルール追加: あなたが「これだけは守ってほしい」と思うことを 5〜10 行で
• コマンド集約: あなたが普段使うコマンドを 1 セクションに

4.3 動作確認: ルールが効いているか

編集した CLAUDE.md に「(任意のルール) 例: 「コミットメッセージは必ず動詞で始める」」を追加し、再度 claude 起動。

> ステージにある変更で適切なコミットメッセージを書いて

→ 動詞で始まる提案が出てくる。次に同じことを別ルール(「コミットメッセージは英語のみ」)で試して、確かに反映されることを確認。

5. 実例: 本リポジトリの CLAUDE.md を見る

本リポジトリ (★digitaocean_claudecode — 仮) の CLAUDE.md は以下の構成:

- 役割分担(どこに何が書いてあるか)
- SSH 接続情報
- ワークフロー (5 ステップ)
- Critical Rules
  - Nginx 設定の罠
  - 情報漏洩防止ポリシー
  - バックアップルール
  - セキュリティ
  - リソース制約
  - ドキュメント鮮度

特徴: - Critical Rules が見出しレベルで分類されている → Claude も人間も探しやすい - 過去の罠(「sites-available を編集しても効かない」)が言語化 → 同じ罠を踏まない

6. アンチパターン

7. 今回の限界 (notes に書く内容)

• CLAUDE.md は 常時読まれる = いつ何を頼んでも参照される
• でも「特定のタスクの時だけ 参照したい」ルール(例: コミットメッセージの規約は commit する時だけ)は分離したい
• → 次回 (08-03) で Skills を導入し、場面別にスペシャリストを呼び出す 仕組みを学ぶ

参考

• 公式: CLAUDE.md ガイド
• 姉妹サイト: claude-academy-japanese ch5-l3: 基本的な使い方とCLAUDE.md
• 本アプリ自身の CLAUDE.md(配布物に含める)