Claude Code の CLAUDE.md を書く手順と実用的な設定例

Claude Codeを使っていると、毎回「このプロジェクトはTypeScriptで、DBはPrismaで…」とプロジェクトの背景を説明し直す手間が出てくる。CLAUDE.mdを書いておくと、Claude Codeがセッション開始時に自動で読み込み、最初から文脈を把握した状態で作業を始めてくれる。この記事では、ファイルの配置場所・読み込み順・実際の書き方・つまずきやすい点を手順どおりに解説する。

CLAUDE.mdとは何か・どこに置くか

CLAUDE.mdは、Claude Codeが起動時に自動で読み込むMarkdownファイルだ。「このプロジェクトでClaudeに最初から知っておいてほしいこと」を書いておく場所と考えるとわかりやすい。touch CLAUDE.md で作ってテキストエディタで書くだけでよい。

公式ドキュメントによると、CLAUDE.mdはプロジェクトの概要・よく使うコマンド・コーディング規約・アーキテクチャの決定事項などを記述するために設計されている。特別な構文はなく、普通のMarkdownで書ける。

ファイルは1プロジェクトに1ファイルという縛りはなく、複数の場所に置いたものがすべてコンテキストに積まれる。

公式ドキュメントによると、これらはセッション起動時にすべて読み込まれる。プロジェクト側がグローバル設定を上書きするのではなく、両方が有効になる点に注意する。

プロジェクト用CLAUDE.mdの書き方

プロジェクトルートに CLAUDE.md を作り、以下の構成で書くのが実用的と考えられる。

# プロジェクト名

## 概要
何を作っているか・どんなスタックかを2〜3行で記述する。

## よく使うコマンド
- `npm run dev` — 開発サーバー起動
- `npm run build && npm start` — 本番ビルドと起動
- `npx prisma migrate dev` — マイグレーション実行
- `sudo systemctl restart サービス名` — サービス再起動

## コーディング規約
- TypeScriptのstrictモードを有効にしている
- APIルートはすべて `src/app/api/` 以下に置く
- DBアクセスはPrisma Client経由のみ（生SQLは原則禁止）

## 注意事項
- `prisma/dev.db` が本番DB。操作前にバックアップを取ること
- 価格・在庫の一括変更は承認を経てから実行する
- ファイルを削除する前に確認を求めること

書くべき内容のポイントは3つ。

コマンドを具体的に書く — npm run dev か yarn dev かを都度Claudeが推測しなくて済む。間違えると影響が大きいDB操作コマンドなどを特に書いておく。

禁止事項を先に書く — 「やってはいけないこと」を明示しておくと、意図しない操作を防げる。本番DBの直接操作禁止・テストなしのコード変更禁止といった類を書く。

ファイルパスを具体的に書く — 「DBはSQLiteです」より「prisma/dev.db が本番DBです」のほうが誤解が生まれない。

CLAUDE.mdが長くなることを恐れなくてよい。箇条書きで情報量を詰め込むほうが、長文の散文よりClaudeに伝わりやすいと考えられる。

グローバルCLAUDE.mdと@インポートの活用

~/.claude/CLAUDE.md に書いた内容は全プロジェクトで有効になる。複数のプロジェクトで繰り返し伝えることになる個人ルールはここにまとめる。~/.claude/ が存在しない場合は mkdir -p ~/.claude で作成する。

# グローバル設定

## 出力言語
回答は日本語で行う。コードのコメントも日本語。

## 共通の禁止事項
- ファイルを削除する前に確認を求めること
- テストなしでプロダクションコードを変更しないこと

CLAUDE.mdが長くなってきたら、@ファイルパス の記法で別ファイルを取り込める。公式ドキュメントによると、この記法で指定したファイルの内容がCLAUDE.mdに取り込まれる。

## アーキテクチャ詳細
@docs/architecture.md

パスはCLAUDE.mdからの相対パスで書く。ただし取り込むファイルが増えるとコンテキストウィンドウを消費するため、必要な情報だけに絞るのが現実的と考えられる。

つまずきやすい3つのポイント

1. 編集しても即座に反映されない

CLAUDE.mdを編集しても、すでに起動しているセッションには反映されない。セッションを終了して再起動すると、更新後の内容が読み込まれる。「書いたのに効いていない」と感じたら、まずセッションの再起動を試す。

2. カレントディレクトリによって読み込まれるファイルが変わる

プロジェクトのCLAUDE.mdが読み込まれるかどうかは、Claude Codeを起動したディレクトリに依存する。私はPythonのsubprocessから claude -p を呼び出して記事生成をバッチ自動化しているが、この場合はsubprocessの cwd パラメータが読み込みディレクトリを決める。

import subprocess

result = subprocess.run(
    ["claude", "-p", "記事の草稿を生成してください"],
    cwd="/path/to/project",  # ここのCLAUDE.mdが読まれる
    capture_output=True,
    text=True,
    encoding="utf-8"
)
print(result.stdout)

cronジョブから定期実行する場合も同様で、cronのデフォルトのワーキングディレクトリは / やホームディレクトリになることが多い。cronの設定ファイルでディレクトリを指定するか、スクリプト内で cd してから実行するとよい。

3. GitにコミットするかどうかとCLAUDE.local.md

プロジェクトルートの CLAUDE.md はチームで共有する前提で設計されており、Gitにコミットして管理するのが基本的な使い方と考えられる。.gitignore に入れると環境ごとに書き直す手間が発生する。

個人固有のパスや作業メモはグローバルの ~/.claude/CLAUDE.md に書き分けると、プロジェクトの CLAUDE.md はそのままチーム共有できる。公式ドキュメントによると、CLAUDE.local.md を使うとローカル専用の設定（Gitにコミットせず個人環境にだけ適用する設定）を管理できる。

まとめ

まず手元のプロジェクトに CLAUDE.md を1ファイル作り、## よく使うコマンド と ## 注意事項 の2セクションだけを書いてみるところから始めてほしい。それだけでも毎回の説明コストが変わってくる。