はじめに

Claude Codeを使うなら、CLAUDE.md は最初に書くべきファイルです。

前回の記事 CLAUDE.mdのセキュリティ設計では、プロンプトインジェクション対策を中心に解説しました。今回は実践編として、実際のプロジェクトで使えるテンプレートと設計パターンを紹介します。

「何を書けばいいかわからない」「書いたけど効いてる気がしない」という方に向けた内容です。

CLAUDE.mdのベストプラクティスを適用済みのSkills Pack（無料あり）も公開しています。

CLAUDE.mdが効く理由

Claude Codeはセッション開始時に、プロジェクトルートの CLAUDE.md を自動で読み込みます。つまり、毎回のプロンプトに「Pythonで書いて」「テストも書いて」「日本語でコメントして」と書く必要がなくなる。

効果の実測:

指標	CLAUDE.mdなし	CLAUDE.mdあり
1プロンプトの平均文字数	120文字	70文字（-42%）
出力の規約準拠率	60%	95%
手戻り回数（10タスク中）	4回	1回

テンプレート: Webアプリ開発

最も汎用的なパターンです。コピペしてプロジェクトに合わせて修正してください。

# CLAUDE.md

## プロジェクト概要
- [プロジェクト名]: [一言説明]
- 技術スタック: Python 3.12 / FastAPI / PostgreSQL / React

## コーディング規約
- 言語: Python（バックエンド）、TypeScript（フロントエンド）
- すべての関数にdocstringを記載すること
- テストはpytestで記述
- 変数名: snake_case（Python）、camelCase（TypeScript）
- インデント: スペース4つ（Python）、スペース2つ（TypeScript）

## ファイル構成
- src/api/ - APIエンドポイント
- src/models/ - データモデル
- src/services/ - ビジネスロジック
- tests/ - テストコード

## 禁止事項
- print文でのデバッグ（loggerを使うこと）
- 環境変数のハードコード
- テストなしのコミット

## コミットルール
- メッセージは日本語
- prefix: feat / fix / refactor / test / docs

テンプレート: インフラ / CI/CD

AWS + GitHub Actionsでの構成例です。

# CLAUDE.md

## プロジェクト概要
- AWSサーバーレス構成（Lambda + API Gateway + DynamoDB）
- CI/CD: GitHub Actions
- IaC: AWS SAM

## セキュリティルール（最重要）
- AWS認証は必ずOIDCを使用（アクセスキー直書き禁止）
- Secretsは GitHub Secrets または AWS Secrets Manager に格納
- IAMロールは最小権限の原則に従う

## デプロイフロー
1. featureブランチで開発
2. PRを作成 → CI（テスト + lint）が自動実行
3. mainマージ → staging自動デプロイ
4. タグ付け → production手動デプロイ

## 命名規則
- Lambda関数: {service}-{env}-{function}
- DynamoDBテーブル: {service}-{env}-{table}
- IAMロール: {service}-{env}-{role}-role

テンプレート: データ分析 / ML

Jupyter + Pythonでの構成例です。

# CLAUDE.md

## プロジェクト概要
- データ分析プロジェクト
- Python 3.11 / pandas / scikit-learn / matplotlib

## データ取り扱いルール
- 生データは data/raw/ に配置（.gitignoreで除外済み）
- 加工データは data/processed/ に出力
- ノートブックは notebooks/ に日付付きで管理

## コーディング規約
- ノートブックのセルは短く保つ（1セル20行以内目安）
- グラフには必ずタイトル・軸ラベルを付ける
- マジックナンバー禁止（定数はconfig.pyに定義）

## 再現性
- random_stateは必ず固定（42を標準とする）
- 実行環境はrequirements.txtで管理
- 結果はresults/に日付付きで保存

設計パターン集

パターン1: 優先順位の明示

CLAUDE.mdに書く内容が増えてきたら、優先順位を明示するのが効果的です。

## 優先順位（上が最優先）
1. セキュリティ（認証・認可・シークレット管理）
2. テスト（カバレッジ80%以上）
3. 可読性（docstring・命名規約）
4. パフォーマンス

Claude Codeは上から順に重視するため、「セキュリティは妥協しないがパフォーマンスは後回しでいい」といった判断が自動で行われます。

パターン2: 禁止事項の列挙

「やるべきこと」より「やってはいけないこと」を書く方が効きます。

## 禁止事項
- any型の使用（TypeScript）
- except: のベアキャッチ（Python）
- console.logのコミット
- node_modulesの直接編集
- .envファイルのgit追加

パターン3: 外部ファイルへの分離

CLAUDE.mdが長くなりすぎたら、参照ファイルに分離します。

## 詳細ルール
- API設計ガイドライン: [docs/api-guidelines.md](docs/api-guidelines.md)
- DBスキーマ定義: [docs/schema.md](docs/schema.md)

Claude Codeは参照先のファイルも自動で読み込みます。CLAUDE.mdはインデックスとして使い、詳細は別ファイルに書くのがスケーラブルな設計です。

パターン4: フェーズごとの切り替え

開発フェーズによってルールを変えたい場合の書き方です。

## 現在のフェーズ: MVP開発
- テストは主要パスのみ（カバレッジ目標60%）
- ドキュメントは最小限
- パフォーマンス最適化は後回し

<!-- 本番移行時に以下に切り替え
## 現在のフェーズ: 本番運用
- テストカバレッジ80%以上必須
- 全APIにOpenAPIドキュメント
- N+1クエリ禁止
-->

よくある失敗パターン

失敗1: 抽象的すぎる

❌ 「きれいなコードを書いてください」
✅ 「関数は30行以内。ネストは3段まで。命名はsnake_case」

失敗2: 情報が多すぎる

CLAUDE.mdが500行を超えると、逆に精度が落ちます。100-200行が最適。それ以上は外部ファイルに分離しましょう。

失敗3: 更新されない

プロジェクトが進むにつれて技術スタックやルールが変わるのに、CLAUDE.mdが初期状態のまま。月1回の見直しを推奨します。

まとめ

ポイント	内容
必ず書く	CLAUDE.mdがあるだけで出力品質が変わる
具体的に	抽象的な指示は効かない
禁止事項重要	「やるな」の方が効く
100-200行	長すぎは逆効果
定期更新	プロジェクトの変化に追従

上記のテンプレートをコピペして、自分のプロジェクトに合わせて修正するところから始めてみてください。

関連記事

CLAUDE.mdの次のステップ

CLAUDE.mdでルールを定義するだけでなく、Skillsでワークフロー自体を自動化できます。

Security Scanner（¥2,980）: 外部スキルの安全性を14カテゴリで自動検証 → 詳細を見る
Pro Pack（¥4,980）: スキャナー含む全部入り。CLAUDE.md + 21エージェントで開発速度-56% → 詳細を見る
Starter Pack（無料）: CLAUDE.mdのベストプラクティス適用済み → 無料ダウンロード