CLAUDE.md の書き方で AI の働きが変わる

CLAUDE.md とは何か

Claude Code は、プロジェクトルートに置かれた CLAUDE.md を起動時に読み込みます。ここに書かれた内容は「このプロジェクトに関する不変の前提」として、すべての対話の文脈に注入されます。

つまり、CLAUDE.md は AI に対する「コーディング規約」「禁止事項」「ディレクトリ規約」のドキュメントとして機能します。

事故が減った 2 つの規約

私のプロジェクトで実際に書いてある規約を 2 つ紹介します。

金額計算は BCMath 必須

Laravel のサブスク決済を扱うプロジェクトで、初期は float で金額を計算していました。当然のように丸め誤差が出て、テストが落ちる。Claude Code が善意で float で書いてしまうのを止めるために、CLAUDE.md にこう書きました。

## 禁止事項
- 浮動小数点での金額計算は禁止。BCMath / Decimal を使うこと

これを書いてからは、何も指示しなくても bcadd や bcmul を使った実装が返ってくるようになりました。

flutter install の禁止

以前、flutter install を Claude Code に実行させたら、シミュレータ上のアプリデータが全消失したことが 3 回あります。これは本当に痛い経験でした。

## 禁止事項
- flutter install は使用禁止（データが消える）
- 代わりに flutter run --release -d <device_id> を使う

これを書いて以降、データ消失事故はゼロです。

グローバルとプロジェクト個別の使い分け

Claude Code は ~/.claude/CLAUDE.md（グローバル）と <project>/CLAUDE.md（プロジェクト個別）の両方を読みます。私の使い分けはこうです。

• グローバル: 「主要スタック」「禁止事項」「コミットメッセージは日本語」など、すべてのプロジェクトに共通する規約
• プロジェクト個別: 「テーマカラー」「ディレクトリ構成」「主要コマンド」など、そのプロジェクト固有の情報

良い CLAUDE.md の構成例

何度か書き直して、今は以下の構成に落ち着いています。

# プロジェクト概要
何のためのアプリか、何を実現したいか

## 主要コマンド
開発・ビルド・テスト・デプロイのコマンドを列挙

## プロジェクト構成
ディレクトリ階層と各ディレクトリの役割

## 重要な設定
テーマカラー、レスポンシブ閾値、外部 API キーの場所など

## 禁止事項
やってはいけないコマンド、避けるべき実装パターン

## デプロイ時の注意
環境変数、ビルド成果物、注意事項

この順で書くと、Claude Code が「最初に何を読めばいいか」「禁止事項は何か」を素早く把握できる、という体感があります。

書きすぎない

参考までに、改善前と改善後の Bad/Good 比較を載せておきます。Bad は曖昧で文脈依存、Good は具体的・明示的・優先順位がついている、という差です。

# Bad（曖昧で AI が判断に迷う）
## ルール
- なるべくキレイに書く
- セキュリティに気をつける
- テストもなるべく書いてください
- 言語は日本語が望ましいです

# Good（具体的・優先順位明確・禁止事項が明確）
## 禁止事項
- 浮動小数点での金額計算（BCMath / Decimal を使用）
- `flutter install` の実行（データ消失の実績あり）
- マジックナンバーの直書き（PianoConfig に集約）

## 必須事項
- すべての新規ロジックにユニットテストを追加
- 多言語化対象の文字列は arb ファイルに登録
- コミットメッセージは日本語、命令形

注意点として、CLAUDE.md は短いほうが効きます。プロジェクトの細かい仕様を全部書こうとすると、肝心の規約が埋もれます。「これだけは譲れない」をピックアップして、残りはコードや別ドキュメントに任せるのがコツです。

まとめ

• CLAUDE.md は AI に対するコーディング規約として機能する
• 禁止事項を明文化すると事故が減る
• グローバル / プロジェクトで階層化する
• 短く保つほうが効果が高い

AI の働きは、与える文脈で大きく変わります。プロンプトを毎回工夫するより、CLAUDE.md に書いて 1 度で済ませるほうが、はるかに効率がいいです。