株式会社renue
AI導入・DXの悩みをプロに相談してみませんか？
AIやDXに関する悩みがありましたら、お気軽にrenueの無料相談をご利用ください。 renueのAI支援実績、コンサルティングの方針や進め方をご紹介します。
この記事でわかること
- CLAUDE.mdに何を書くべきか・書くべきでないかの判断基準
- デプロイ制約、禁止操作、コードスタイルなど実務で必須の記載パターン
- CLAUDE.md・Skills・.claude/rulesの使い分けとチーム運用のベストプラクティス
はじめに：CLAUDE.mdはAIエージェントへの「プロジェクト憲法」
CLAUDE.mdは、Claude Codeがすべてのセッション開始時に読み込む特別なファイルです。人間の新メンバーに渡す「プロジェクトのオンボーディング資料」に相当しますが、AIエージェントは毎回のセッションで記憶がリセットされるため、CLAUDE.mdの品質がそのままAIの出力品質を決定します。
しかし多くのプロジェクトで、CLAUDE.mdは「とりあえずプロジェクト構成を書いただけ」の状態で放置されています。本記事では、AIエージェントの行動を確実に制御し、チーム全体の開発品質を底上げするCLAUDE.mdの設計方法を、7つの原則で解説します。
原則1：「削除したらAIが間違えるか」テストで取捨選択する
CLAUDE.mdに書くべきかどうかの判断基準はシンプルです。「この行を削除したら、AIが間違った行動を取るか？」をチェックします。
書くべきもの：
- デプロイ先の制約（「本番環境にはデプロイしない」「staging環境のみ使用可」）
- 禁止操作（「rm -rfを実行しない」「.envファイルを読み取らない」）
- プロジェクト固有の罠（「このリポジトリではnpm installではなくpnpm installを使う」）
- 頻繁に使うコマンド（テスト実行、ビルド、デプロイのコマンド）
書くべきでないもの：
- 一般的なプログラミングの知識（AIは既に知っている）
- コードから読み取れるプロジェクト構成（AIはコードを読める）
- Lintやformatterで強制できるスタイルルール（機械的に強制する方が確実）
- ドメイン知識やときどきだけ関連するワークフロー（Skillsに分離する）
原則2：断言形で書く。「なるべく」「できれば」は禁止
AIに対して曖昧な指示は機能しません。以下のように、断言形で具体的に書きます。
NG：「なるべくテストを書いてください」
OK：「新しい関数を追加する場合、必ず対応するテストファイルを作成する。テストファイル名は{関数名}_test.goとする」
NG：「デプロイには注意してください」
OK：「本番環境（prod）へのデプロイは絶対に実行しない。デプロイ先はstaging環境のみ。誤ってprodを指定するコマンドが生成された場合は即座に中止する」
この原則は、社内ガイドラインの「確認はYes/Noだけで回答可能な形にする」という考え方と同じです。AIへの指示もYes/Noで判定可能な明確さが必要です。
原則3：「If X, then Y」のトリガー形式で書く
CLAUDE.mdの指示は「条件→行動」のトリガー形式が最も効果的です。
具体例：
- 「Pythonファイルを編集する場合 → ruff checkとruff formatを実行してからコミットする」
- 「新しいAPIエンドポイントを追加する場合 → OpenAPIスキーマも同時に更新する」
- 「データベースのスキーマを変更する場合 → マイグレーションファイルを生成し、ロールバック手順もコメントに記載する」
- 「.envファイルに触れようとした場合 → 即座に中止し、環境変数は環境変数管理ツール経由で設定するよう案内する」
原則4：200行以内に収める。超えたら分離する
CLAUDE.mdはすべてのセッションで読み込まれるため、長すぎるとコンテキストウィンドウを圧迫し、重要な指示が埋もれます。推奨は150〜200行以内です。
分離先の使い分け
| 配置場所 | 読み込みタイミング | 適する内容 |
|---|---|---|
| CLAUDE.md | 毎セッション自動 | 普遍的なプロジェクトルール |
| .claude/rules/*.md | 該当パスのファイル操作時 | ディレクトリ固有のルール |
| Skills（.claude/commands/） | ユーザーが明示的に呼び出し | 特定ワークフロー・手順書 |
| ~/.claude/CLAUDE.md | 毎セッション自動（個人） | 個人のコーディングスタイル |
.claude/rulesの活用例
YAMLフロントマターでパス指定を行うと、特定のファイルを扱うときだけルールが適用されます。
例：.claude/rules/api-routes.mdにYAMLフロントマターでglobs: src/routes/**/*.tsと指定すれば、APIルートファイルを編集するときだけ「レスポンスにはZodスキーマでバリデーションを入れる」といったルールが読み込まれます。
原則5：セキュリティ制約は最上部に書く
AIエージェントのセキュリティ事故で最も多いのは、以下の3つです。
事故1：誤デプロイ
AIがデプロイコマンドを生成する際、意図しない環境（本番環境やテスト用の別環境）にデプロイしてしまうケースです。CLAUDE.mdの最上部に、許可されたデプロイ先を明記します。
事故2：機密情報の露出
AIが.envファイルを読み取り、APIキーやトークンをプロンプトに含めてしまうケースです。.envファイルへのアクセスを明示的に禁止し、環境変数は環境変数管理ツール経由で設定するルールを記載します。
事故3：破壊的操作の実行
AIがrm -rfやgit reset --hardなど、不可逆な操作を実行してしまうケースです。禁止する破壊的コマンドのリストをCLAUDE.mdに明記します。
セキュリティセクションのテンプレート
CLAUDE.mdの冒頭に以下のようなセキュリティセクションを配置します。
# セキュリティ制約（最優先）
- デプロイ先: staging環境のみ。prod/本番へのデプロイは絶対禁止
- .envファイル: 読み取り・編集・表示を禁止
- 破壊的コマンド: rm -rf, git reset --hard, git push --force を禁止
- 認証情報: APIキー・トークン・パスワードをコードやプロンプトに含めない
- データベース: DROP TABLE, TRUNCATE を禁止。マイグレーションのみ許可原則6：チームで共有し、PRレビュー対象にする
CLAUDE.mdは個人の設定ファイルではなく、チームの共有資産です。以下の運用ルールを設けます。
- CLAUDE.mdの変更はPRレビュー対象とする（コードと同じ品質管理）
- 新メンバーがハマった問題は、CLAUDE.mdに追記するかどうかを検討する
- 四半期に1回、「まだ有効か」の棚卸しを行い、古くなったルールを削除する
- AIが同じ間違いを繰り返す場合は、CLAUDE.mdにルールを追加するシグナルとする
原則7：/initで生成した後、必ず人間がカスタマイズする
Claude Codeの/initコマンドは、プロジェクト構造を分析してCLAUDE.mdの初期版を自動生成します。しかし自動生成された内容はあくまで出発点であり、以下の項目は人間が追記する必要があります。
- デプロイ制約やセキュリティルール（AIは自発的に生成しない）
- チーム固有のワークフロー（PR作成のルール、レビュー手順等）
- 過去に発生した事故・トラブルから学んだルール
- 外部サービスとの連携方法（CI/CD、監視ツール等）
CLAUDE.mdの4つの運用パターン
プロジェクトの性質に応じて、CLAUDE.mdの構成パターンは異なります。
パターン1：プロジェクトガイド型
新規開発プロジェクトで、AIに全体像を把握させることが主目的。プロジェクトの目的、技術スタック、ディレクトリ構成、頻出コマンドを記載します。
パターン2：開発制約型
本番運用中のシステムで、AIの操作範囲を厳密に制限することが主目的。デプロイ制約、禁止操作、認証情報の取り扱いルールを重点的に記載します。
パターン3：CI/CD連携型
テスト自動化やデプロイパイプラインとの連携が主目的。テスト実行コマンド、Lintルール、PR作成時のチェックリストを記載します。
パターン4：マルチエージェント型
複数のAIエージェント（Claude Code + Codex等）を併用するプロジェクトで、各エージェントの役割分担を明記。AGENTS.mdと組み合わせて、作業エージェントとレビューエージェントの分離を定義します。
よくある失敗とアンチパターン
失敗1：デプロイ先の制約を書かない
CLAUDE.mdにデプロイ先の制約がないと、AIが意図しない環境にデプロイするリスクがあります。実際にテスト環境ではなく別のテスト環境にデプロイしてしまった事故が報告されています。
失敗2：.envのガードレールがない
セキュリティアラートの大半は.envファイルへのアクセスに起因します。CLAUDE.mdで明示的に禁止しないと、AIは平文で認証情報を表示してしまうことがあります。
失敗3：CLAUDE.mdを肥大化させる
500行を超えるCLAUDE.mdは逆効果です。AIはすべてを読みますが、重要な指示が埋もれて無視される可能性が高まります。200行を超えたら、.claude/rulesやSkillsへの分離を検討してください。
失敗4：曖昧な指示を書く
「コードの品質に気をつけてください」のような曖昧な指示はAIに対して意味をなしません。「関数は50行以内にする。超える場合は分割する」のように定量的・具体的に書きましょう。
まとめ：CLAUDE.mdは「育てる」もの
CLAUDE.mdは一度書いたら終わりではありません。AIが間違えるたびにルールを追加し、古くなったルールを削除し、チームの学びを反映して育てていくドキュメントです。
本記事の7原則（取捨選択テスト・断言形・トリガー形式・200行制限・セキュリティ最上部・チーム共有・/init後カスタマイズ）を適用すれば、AIエージェントの出力品質を確実に底上げできます。
AIエージェント活用・CLAUDE.md設計はRenueにご相談ください
Renueでは、14以上のプロジェクトリポジトリでCLAUDE.mdを運用し、プロジェクトガイド型・開発制約型・CI/CD連携型・マルチエージェント型の4パターンを実践しています。AIが誤デプロイした事故やセキュリティアラートへの対処経験をもとに、お客様のプロジェクトに最適なCLAUDE.md設計を支援します。