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の実践的な使い方を発信中。