CLAUDE.md ベストプラクティス20選

Claude Code を使い込んでいる人が「CLAUDE.md が一番大事」と口を揃えるのは、それが Claude の 永続的な前提知識になるから。プロンプトに毎回書くより、CLAUDE.md に置いて「常に参照される」状態にすることで、出力の一貫性が桁違いに上がります。今回は私たちが運用している CLAUDE.md の構成20項目を、効いた順に解説します。

ベスト10（必須）

ここから10項目は 書いてないと Claude が右往左往する最低ラインです。書かないと初回プロンプトで毎回同じ説明をすることになるので、結局時間を喰います。

1. 1プロジェクトの一行説明：「誰に・何を・なぜ提供するか」を1文で。Claude のすべての判断の起点になる
2. 2主要な技術スタック（バージョン込み）：「Next.js 16 App Router」「Python 3.12 + uv」など。バージョンが違うと API（Application Programming Interface） も違うのでバージョン必須
3. 3ディレクトリ構成と各責務：tree コマンドの出力に1行ずつ「ここは○○用」とコメント。Claude が新規ファイルをどこに置くべきかの判断材料
4. 4命名規約：ファイル（kebab-case / PascalCase）、関数・変数（camelCase / snake_case）、テストファイル（`*.test.ts` / `test_*.py`）。混在するとレビュー疲れ
5. 5よく使うコマンド：`make test`、`npm run dev`、`uv run pytest` 等。Claude がコマンドを推測する前に書く
6. 6触ってはいけないファイル：自動生成ファイル（lockfile, dist/）、レガシーコード、外部からコピーしたコード等。Claude が勝手に lint しないように
7. 7実行禁止コマンド：`git push --force`, `git rebase main`, `rm -rf`, `npm publish` 等。auto モードで暴走する事故を防ぐ
8. 8テスト戦略：単体テストは `tests/unit/`、E2E は `tests/e2e/`。何をどこに書くかを Claude が悩まないように
9. 9デプロイ手順の概要：本番デプロイがどう走るか（Vercel / GHA / 手動）。Claude が「とりあえずデプロイしてみよう」と暴走しない歯止め
10. 10コミット規約・PR 規約：Conventional Commits、PR テンプレ、レビュー必須項目。機械的に守るべきルールを明文化

ベスト11-20（差をつける）

ここから10項目は 書くと Claude のアウトプット品質が一段上がる項目です。「動くもの」と「壊れないもの」の差はここに出ます。

1. 1過去の事故事例：「○月の障害は××が原因だった、再発防止として△△」。同じ失敗を Claude に繰り返させない
2. 2読むべき参考実装ファイル：`@src/lib/auth.ts` のような形で参照。「新機能を作るときはこれをパターンに」という指示が効く
3. 3外部 API のレートリミット：「OpenAI は 10K req/min」「Stripe は idempotency key 必須」等。Claude が知らない外部仕様
4. 4Secret 管理：`.env.local` の場所、Secrets Manager の参照方式、コミットしてはいけないファイル。漏洩事故の防止
5. 5ローカル環境のセットアップ手順：「`make setup` 1コマンド」を整備し、CLAUDE.md に書く。Claude がトラブったとき自己復旧できる
6. 6Git ブランチ運用：main / develop / feature の使い分け、PR 先のターゲット、マージ後の挙動
7. 7レビュー基準：「人間が必ずやること」を明示。マイグレーション SQL（Structured Query Language）、課金関連、認証フローなど
8. 8Claude が自動実行していいタスク：「テスト走らせる」「lint かける」「型チェック」は許可。曖昧にすると毎回確認を取られて遅い
9. 9Claude が確認を取るべきタスク：DB（Database） マイグレーション、外部 API 呼び出し（課金あり）、`git push`、本番デプロイ。逆に明示しないと事故る
10. 10コメント言語ポリシー：日本語コメントを許容するか英語強制か。混在は読みづらい。チームの実態に合わせる

実例：ふくふく社内 CLAUDE.md の冒頭

# [プロジェクト名]
データ基盤＋AI活用の受託プロジェクト。クライアントは {小売／メディア／製造} 業種。
## 技術スタック- Python 3.12 + uv- BigQuery / dbt 1.9 / Airflow 2.10- Next.js 16 (App Router) + Tailwind v4- Vercel (Production), Cloud Composer (DAG)
## ディレクトリ- `src/` … 本体ソース- `dags/` … {{airflow|*}} DAG（** Cloud Composer に直接デプロイされる**ので慎重に）- `tests/unit/` … 単体テスト- `tests/e2e/` … E2E テスト（dev DB 必要）- `infra/` … Terraform（**勝手に apply しない**）
## 触ってはいけない- `migrations/applied/` … 適用済みマイグレーション、絶対編集しない- `legacy/` … 旧コード、参照のみ
## 実行禁止- `git push --force`、`git rebase main`- `terraform apply`（人間が確認後に実行）- `bq query --destination_table` で本番テーブル直書き
## Claude が自動実行 OK- `make test`, `make lint`, `make type`- `uv add <pkg>`, `uv sync`- `git diff`, `git status`, `git log` 系
## Claude が確認を取るべき- 新規 `migrations/` ファイル作成- 外部 API（特に課金あり：OpenAI / Anthropic / Stripe）- `git push`, PR 作成（main 以外なら自動 OK）- 本番デプロイトリガー
## 過去の事故- 2025-12: {{dbt|*}} incremental の unique_key ミスで重複行が {{dwh|*}} に蓄積  → ** unique_key は `composite` で複合キーにする**- 2026-02: Airflow の retry が重複決済を引き起こす  → **idempotency key を必ず付ける**
## レビュー基準- マイグレーション SQL：人間 1 名以上必須- 課金フロー：人間 2 名 + ステージング動作確認- それ以外：Claude のレビューで OK

更新運用：「育てる」CLAUDE.md

CLAUDE.md は書いて終わりではなく、育てるものです。事故が起きるたびに「この事故を再発させないなら CLAUDE.md にどう書く？」を自問し、追記する。半年〜1年運用すると、そのプロジェクトでしか得られない知見の塊になります。これが新人オンボーディング資料としてもそのまま使える状態。

• 月1回の見直し：陳腐化した項目（移行済みの一時ルール等）を削除
• 事故ごとの追記：「ポストモーテム → CLAUDE.md 反映」を運用ルールに
• 新メンバー受け入れ時のチェックリスト化：人間が読んでも理解できるか

ふくふくの進め方

「Claude Code を導入したいが CLAUDE.md の書き方が分からない」というご相談には、1〜2 週間で初期版作成、1 ヶ月で運用ルール定着、3 ヶ月で社内標準化のロードマップでお出ししています。実プロジェクトを題材に伴走しながら書き進めるので、机上論ではない、現場で効く CLAUDE.md ができます。

次回予告

EP.08 は Sub-AIエージェント の応用パターン。3 並列で複雑タスクを進める設計と、competing changes（競合変更）を起こさないための分離戦略を、実プロジェクトでの使い方とともに公開します。