この記事でわかること
– CLAUDE.mdの仕組みと3つの配置場所
– グローバル・プロジェクト・サブディレクトリの使い分け
– 書くべき内容とアンチパターン
– チームリポジトリでの運用ルール
Claude Codeを使い込んでいくと、毎回同じことを伝えるのが面倒になってくる。「このプロジェクトはPython 3.13」「テスト後はlintも走らせて」「コミットメッセージは英語で」——これを毎回言うのは非効率だ。
CLAUDE.md はこの問題を解決する。プロジェクトの情報・規約・注意点を一度書いておけば、以降のすべての会話でClaude Codeが自動で参照する。
CLAUDE.mdの仕組み
Claude Codeは起動時に以下の場所を自動で読み込む。
~/.claude/CLAUDE.md ← グローバル（全プロジェクト共通）
{project_root}/CLAUDE.md ← プロジェクト固有
{subdirectory}/CLAUDE.md ← サブディレクトリ固有（そのディレクトリ配下の作業時のみ）
3つが同時に読み込まれ、コンテキストとしてマージされる。Claude Codeは会話を始める前にこれらを全て「読んでいる」状態になる。
3つの配置場所の使い分け
グローバル: ~/.claude/CLAUDE.md
全プロジェクトに共通する自分の好みや環境情報を書く。
# グローバル Claude Code 設定
## 環境情報
-OS: Windows 11 / Python 3.13 / Node.js 20
-サブPC: user@192.168.0.10
## 開発スタイル
-コミットメッセージ: 英語
-変更は最小限に。過剰なリファクタ禁止
-テスト後は必ずlint確認
## セキュリティ
-npm installは `npm info <pkg>` で確認してから
-.envファイルをgitに含めない
グローバルファイルはgitで管理されない個人設定ファイルなので、PC固有の情報（パス・接続先・APIキー以外の環境情報）を書いても問題ない。
プロジェクト: {project_root}/CLAUDE.md
そのプロジェクト固有の技術情報・アーキテクチャ・コマンド体系を書く。チームで使う場合はgitにコミットする。
# プロジェクト名
## 技術スタック
-Python 3.13 / FastAPI / Redis / PostgreSQL
-フロントエンド: Next.js 15 (App Router)
## ディレクトリ構成
| ディレクトリ | 役割 |
|------------|------|
| src/api/ | FastAPIルーター |
| src/db/ | DB操作層 |
| tests/ | pytest テスト |
## よく使うコマンド
```bash
# 開発サーバー起動
uvicorn src.main:app --reload
# テスト実行
pytest tests/ -v
# DBマイグレーション
alembic upgrade head
コーディング規約
- 関数は単一責任。50行を超えたら分割を検討
- 型アノテーション必須
- DBアクセスはsrc/db/以外で直接書かない
注意点
- src/legacy/は触らない（削除予定）
- Redis接続はconfig.pyのCONFIG.redis_urlから取得すること
---
### サブディレクトリ: `{subdir}/CLAUDE.md`
**特定のモジュールやマイクロサービスに固有の情報**を書く。モノレポ構成や複数サービスが同一リポジトリに入っている場合に特に有効。
my-monorepo/
CLAUDE.md ← リポジトリ全体の概要
services/
api/
CLAUDE.md ← APIサービス固有（FastAPI固有の規約など）
worker/
CLAUDE.md ← Workerサービス固有（Celery固有の設定など）
frontend/
CLAUDE.md ← フロントエンド固有（Next.js/Tailwind規約など）
`services/api/` で作業するとき、Claude Codeはリポジトリルートと `services/api/` の両方のCLAUDE.mdを読む。関係ないサービスの情報は入ってこない。
---
## CLAUDE.mdに書くべき内容
### 必ず書くべき
**プロジェクト固有の技術情報**
```markdown
## 技術スタック
- Python 3.13 / Django 5.2 / PostgreSQL 16
- テスト: pytest + factory-boy
- CI: GitHub Actions
よく使うコマンド（毎回聞かれることがなくなる）
## コマンド
-起動: `make dev`
-テスト: `pytest`
-lint: `ruff check . && mypy src/`
「触ってはいけない」エリア（特に重要）
## 注意事項
-src/vendor/は外部ライブラリのコピー。修正禁止
-migrations/は手動で編集しない。`makemigrations`を使う
-settings_local.py はgit管理外。テンプレートは settings_local.example.py
デプロイ・リリース手順
## デプロイ
1. mainブランチへのPRは必ずCIが通ってからマージ
2. `git tag v{semver}` してpush → GitHub Actionsが自動デプロイ
外部サービスの接続情報（場所のみ。値は書かない）
## 設定ファイル
-DB接続: .env の DATABASE_URL
-Redis接続: .env の REDIS_URL
-.envのテンプレート: .env.example を参照
書かなくていい内容
Claudeのデフォルト動作と変わらないもの
# 不要な例
-「コードは正確に書いてください」
-「コメントを書いてください」
-「エラーハンドリングを考慮してください」
これらはClaude Codeがデフォルトで行う。わざわざ書くと指示が冗長になり、本当に重要な情報が埋もれる。
変わりやすい情報
– 「現在のバージョンはv1.2.3」→ バージョンは頻繁に変わるのですぐ陳腐化する
– 「XXさんが担当」→ 担当者は変わる
CLAUDE.mdは記事で言えば常設コンテンツ。頻繁に更新が必要な情報は別の場所（README.md、wiki、Notion等）に書く。
チーム運用のルール設計
gitにコミットするか否かの判断
| CLAUDE.mdの場所 | gitコミット |
|---|---|
~/.claude/CLAUDE.md | しない（個人設定） |
{project}/CLAUDE.md | する（チーム共有） |
{subdir}/CLAUDE.md | する（チーム共有） |
.gitignore で個人設定を逃がす
プロジェクトのCLAUDE.mdはチーム共有だが、個人的な追記をしたい場合は .gitignore で管理外ファイルを作る。
# .gitignore
CLAUDE.local.md
CLAUDE.local.md に個人のメモを書いておく（Claude Codeは CLAUDE.md しか読まないのでこれはあくまで個人メモ）。
メンテナンス担当を明記する
## このCLAUDE.mdについて
-最終更新: 2026-03-09
-更新担当: @username
-変更があれば必ずCLAUDE.mdを更新してください
CLAUDE.mdは生きたドキュメントとして扱う。コード変更に伴う更新を忘れると、古い情報がClaudeに渡されてバグを引き起こす原因になる。
アンチパターン
機密情報を書く
# 絶対ダメ
DATABASE_URL=postgresql://admin:PASSWORD@db.example.com/prod
AWS_SECRET_ACCESS_KEY=xxxxx
プロジェクトのCLAUDE.mdはgitにコミットされる。チーム全員・場合によっては外部に漏れる。
長すぎる
200行を超えるCLAUDE.mdは読み込みコンテキストを圧迫する。重要度の低い情報を詰め込みすぎると、本当に必要な情報が薄まる。
目安：プロジェクトルートCLAUDE.mdは100行以内。それ以上になるなら、情報をサブディレクトリのCLAUDE.mdに分散させる。
矛盾する指示
グローバルCLAUDE.mdで「コミットメッセージは英語」と書き、プロジェクトCLAUDE.mdで「コミットメッセージは日本語」と書くと、Claude Codeが混乱する可能性がある。より具体的な指示（プロジェクト側）が優先されるが、意図しない動作の元になるので一貫性を保つ。
テンプレート
# {プロジェクト名}
## 概要
（1-2行でプロジェクトの目的）
## 技術スタック
-バックエンド:
-フロントエンド:
-DB:
-インフラ:
## ディレクトリ構成
| パス | 役割 |
|-----|------|
| | |
## よく使うコマンド
```bash
# 開発起動
# テスト
# lint/型チェック
# デプロイ
コーディング規約
-（プロジェクト固有のルールのみ）
触ってはいけないエリア
-（理由とともに明記）
設定ファイルの場所
- 認証情報: .env（テンプレート: .env.example）
“`
まとめ
CLAUDE.mdはClaude Codeへの「永続的な指示書」だ。
- グローバル: 自分の開発スタイル・環境情報
- プロジェクト: 技術スタック・コマンド・禁止エリア
- サブディレクトリ: モジュール固有の詳細情報
書くべきはClaudeが毎回聞いてくる情報と触ってはいけない地雷の場所。書かないのは機密情報とClaudeのデフォルト動作と変わらない内容。
一度きちんと書いておくと、新しいセッションを始めるたびに「このプロジェクトは…」と説明する手間がゼロになる。チームで使う場合は、コード変更と一緒にCLAUDE.mdも更新するルールを作るのが鍵だ。
わさびの見解
わさびです。Claude Codeを2025年12月から使い始めて3ヶ月で10以上のプロジェクトを回すようになり、CLAUDE.mdなしでは無理でした。最初、akahara-vlabの自動化パイプラインで毎回「Python 3.13、WP-CLI経由でREST API叩け」と繰り返していましたが、グローバル~/.claude/CLAUDE.mdに環境情報とlintルールを書いて一発解決。以降の会話でClaudeが自動参照するので、思考の無駄がゼロに。
プロジェクトルートにはcocoaAIみたいにFastAPI+Redisのスタックとuvicornコマンドをまとめ、サブディレクトリごと（例: src/api/）にルーター規約を置いて運用。ZariaSystemの暗号資産売買部分ではセキュリティ注意点をCLAUDE.mdで固定し、ミスを防ぎました。チーム運用ルールもこれでgit共有可能で、グローバルチームのベストプラクティスそのもの。
CLAUDE.mdはClaude Codeを「記憶あるパートナー」に変える鍵。AIをただ使う人と、こうした仕組みでシステム化するエンジニアの差がここで開きます。複数プロジェクト管理してる人は、今日からグローバルファイル作って体感してみてほしい。
あわせて読みたい
- Claude Code hooksシステム完全ガイド — hooksでClaude Codeの動作をカスタマイズ
- Claude Code v2.1.70リリースノート — 直近のClaude Codeアップデートまとめ
- Claude Codeのサードパーティスキルは安全か？ — スキル・フック・MCPの安全な使い方
見てもらえるだけで応援になります
このブログはアフィリエイトリンクで運営されています。以下のリンクから気になるサービスをチェックしてもらえると、僕たちの活動の支えになります。
この記事を書いたのは わさび（ニホンイシガメ / 3歳 / VTuberあかはら。の家族）です。
あかはらVラボ — Claude特化の情報を発信中。
この記事が参考になったら｜以下のリンクから見てもらえるだけで、ブログ運営の応援になります。
- 天秤AI Biz byGMO
Claude・ChatGPT・Geminiなど6つの生成AIを同時に使い比べ。業務活用に。 - 45万円のAI講座［E資格］を月額3,000円で始められる【ラビットチャレンジ】
45万円相当のAI講座（E資格対応）を月額3,000円で受講できます。
コメント