CLAUDE.mdとは
CLAUDE.mdはClaude Codeが会話の開始時に自動で読み込む設定ファイルだ。
ここに書いたことは、Claude Codeの全ての出力に反映される。「TypeScriptで書いてください」と毎回言わなくても、CLAUDE.mdに書いておけば常にTypeScriptで生成される。
逆に言えば、CLAUDE.mdを書かないと：
- 毎回「うちのプロジェクトはTypeScriptを使っています」と説明する
- 既存のコードのスタイルと合わない実装が生成される
- 「あのファイルは触らないで」と何度も言うことになる
配置場所
| 場所 | スコープ |
|---|---|
~/.claude/CLAUDE.md |
全プロジェクト共通 |
プロジェクトルート/CLAUDE.md |
プロジェクト固有 |
サブディレクトリ/CLAUDE.md |
そのディレクトリ以下 |
モノレポでは親ディレクトリに共通設定、各パッケージに個別設定を置くのが有効だ。
最小限のCLAUDE.md
# プロジェクト名
## 技術スタック
- TypeScript 5.x
- Express + Prisma
- PostgreSQL
## テスト実行
npm test
## コードスタイル
- Prettier + ESLint設定済み
- コミット前に `npm run lint` を実行
この3セクション（技術スタック・テスト・スタイル）があるだけで、出力品質が大きく改善する。
高度なCLAUDE.mdの書き方
1. 「絶対禁止事項」を書く
## 変更禁止ルール
- `src/legacy/` 以下は変更しないこと（本番影響大）
- `package.json` の依存関係は追加しないこと（要レビュー）
- `.env` ファイルは読み書きしないこと（セキュリティリスク）
「禁止」「しないこと」という強い言葉を使うと守られやすい。
2. アーキテクチャ制約を書く
## アーキテクチャルール
- レイヤー: Controller → Service → Repository（逆依存禁止）
- Controller に DB操作を書かない
- Service に HTTP依存コードを書かない
- 全エンドポイントに認証ミドルウェアを適用すること
3. セキュリティ要件を書く
## セキュリティ要件
- SQLは必ずパラメータ化クエリを使う（文字列結合禁止）
- 外部入力は全てzodでバリデーション
- ログにPII（個人情報）を出力しない
- エラーメッセージに内部詳細を含めない（ユーザー向けは汎用メッセージ）
4. テスト要件を書く
## テスト要件
- 新機能には単体テストが必須
- カバレッジ目標: 80%以上
- テストファイルは `tests/` 以下、ファイル名は `*.test.ts`
- モックは `jest.mock()` で、実際のDBに繋がないこと
5. よく参照するファイルパスを書く
## よく使うファイル
- DB接続: `src/lib/db.ts`
- 認証ミドルウェア: `src/middleware/auth.ts`
- 共通型: `src/types/index.ts`
- エラークラス: `src/errors/AppError.ts`
- APIルート一覧: `src/routes/index.ts`
これを書いておくと、「既存のDB接続パターンを使って」と言うだけで正しいファイルを参照してくれる。
チーム開発でのCLAUDE.md
誰が書くか
最初のバージョンはリードエンジニアが書く。その後は全員がPRに含める形で更新する。
# 変更履歴
- 2026-03-01: 初版作成（@lead-dev）
- 2026-03-11: セキュリティ要件追加（@security-team）
チーム共通の禁止事項
## チーム規約
- 「あとで直す」コードは書かない（TODOコメントには担当者と期限を書く）
- console.log は本番コードに残さない
- 型アサション（as SomeType）は使わない
- マジックナンバーは定数化すること
CLAUDE.mdのよくある失敗例
失敗1: 曖昧な表現
# NG
- コードはきれいに書く
- セキュリティに注意する
# OK
- 関数は50行以内
- SQLはパラメータ化クエリのみ（文字列結合でのクエリ組み立て禁止）
失敗2: 長すぎる
CLAUDE.mdが長すぎると、重要な内容が読み飛ばされる。最優先事項を上に書き、詳細は別ファイルに分ける。
## 開発規約
主要ルールのみ記載。詳細は `docs/coding-standards.md` を参照。
失敗3: 更新されない
CLAUDE.mdは「一度書いたら終わり」のファイルではない。プロジェクトの変化に合わせて更新する。月1回レビューする習慣を作るといい。
まとめ: CLAUDE.mdのチェックリスト
□ 技術スタック（言語・フレームワーク・DB）
□ テスト実行コマンド
□ コードフォーマット設定
□ 変更禁止ファイル・ディレクトリ
□ アーキテクチャの制約（レイヤー設計等）
□ セキュリティ要件
□ よく使うファイルパス
□ チーム固有の禁止事項
Claude Codeのカスタムスキルを組み合わせると、CLAUDE.mdで定義した規約を自動チェックできます。
Code Review Pack（¥980） では、コードがCLAUDE.mdの規約に従っているかを /code-review が自動チェックします。
みょうが (@myougaTheAxo) — ウーパールーパーのVTuber。Claude Codeの実践的な使い方を発信中。