株式会社renue
renueについて
renueは、AIで業務を実装する会社です
AIコンサルティングから図面AI・広告運用エージェント・コールセンターAIまで、実際に動いているサービスをご覧いただけます。renueが何をしている会社か、まずはサービス一覧からご確認ください。
この記事でわかること
- CLAUDE.mdに何を書くべきか・書くべきでないかの判断基準
- デプロイ制約、禁止操作、コードスタイルなど実務で必須の記載パターン
- CLAUDE.md・Skills・.claude/rulesの使い分けとチーム運用のベストプラクティス
はじめに：CLAUDE.mdはAIエージェントへの「プロジェクト憲法」
CLAUDE.mdは、Claude Codeに継続して伝える指示を置くファイルです。作業ディレクトリとその上位のファイルは開始時に、下位のファイルは該当ディレクトリ内のファイルを読む際に取り込まれます。人間の新メンバーに渡す「プロジェクトのオンボーディング資料」に相当します。新しいセッションは新しいコンテキストで始まりますが、CLAUDE.mdや自動メモリで引き継ぐ情報もあります。指示の品質は出力に影響する要素の一つです（公式：メモリと指示の読み込み）。
CLAUDE.mdを「とりあえずプロジェクト構成を書いただけ」の状態にすると、必要な指示が不足する場合があります。本記事では、AIエージェントに期待する行動を明確にし、チーム全体の開発品質を改善するための設計方法を、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はコンテキストを使うため、長すぎると重要な指示が埋もれるおそれがあります。公式は1ファイル200行未満を目安としています。本記事では150〜200行程度を整理の目標としますが、行数だけで有効性が決まるわけではありません（公式：CLAUDE.mdの長さ）。
分離先の使い分け
| 配置場所 | 読み込みタイミング | 適する内容 |
|---|---|---|
| CLAUDE.md | 作業場所と上位は開始時、下位は該当ファイルを読む際 | 普遍的なプロジェクトルール |
| .claude/rules/*.md | paths指定なしは開始時、指定ありは一致するファイルを読む際 | 共通ルール、またはディレクトリ固有のルール |
| Skills | ユーザーの呼び出し、または関連性に応じたClaudeの選択（設定で制限可能） | 特定ワークフロー・手順書 |
| ~/.claude/CLAUDE.md | 毎セッション自動（個人） | 個人のコーディングスタイル |
.claude/rulesの活用例
YAMLフロントマターのpathsで対象を指定すると、一致するファイルを読む際にルールが取り込まれます。指定のないルールは無条件で読み込まれます。Skillsは手動呼び出しのほか、説明に基づく自動選択もあり、disable-model-invocation等で呼び出し方法を制御できます（公式：パス別ルール、公式：Skillsの呼び出し）。
例：.claude/rules/api-routes.mdの先頭に、---で囲んだYAMLフロントマターでpaths: ["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の冒頭に、以下のようなセキュリティセクションを配置します。この文章は方針を伝えるための例です。実際の禁止はClaude Codeの権限設定やPreToolUseフック、実行環境のアクセス権、デプロイ・DB側の権限でも実施します。例えばファイル読み取りの制限だけでは、シェル経由のアクセスまで同じ設定で防げるとは限りません（公式：権限制御、公式：フックによる操作の制御）。
# セキュリティ制約（最優先）
- デプロイ先: 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の初期版を自動生成します。既存のCLAUDE.mdがあれば改善を提案します。生成内容は出発点であり、以下の項目が実際の運用と一致するか人間が確認し、不足を追記します（公式：/initによる初期設定）。
- デプロイ制約やセキュリティルール（生成の有無にかかわらず、実際の許可範囲と照合）
- チーム固有のワークフロー（PR作成のルール、レビュー手順等）
- 過去に発生した事故・トラブルから学んだルール
- 外部サービスとの連携方法（CI/CD、監視ツール等）
CLAUDE.mdの4つの運用パターン
プロジェクトの性質に応じて、CLAUDE.mdの構成パターンは異なります。
パターン1：プロジェクトガイド型
新規開発プロジェクトで、AIに全体像を把握させることが主目的。プロジェクトの目的、技術スタック、ディレクトリ構成、頻出コマンドを記載します。
パターン2：開発制約型
本番運用中のシステムで、AIに許可する操作範囲を明確にすることが主目的。デプロイ制約、禁止操作、認証情報の取り扱いルールを重点的に記載し、実際の制限は権限設定と組み合わせます。
パターン3：CI/CD連携型
テスト自動化やデプロイパイプラインとの連携が主目的。テスト実行コマンド、Lintルール、PR作成時のチェックリストを記載します。
パターン4：マルチエージェント型
複数のAIエージェント（Claude Code + Codex等）を併用するプロジェクトで、各エージェントの役割分担を明記。AGENTS.mdと組み合わせて、作業エージェントとレビューエージェントの分離を定義します。Claude CodeがAGENTS.mdを自動的に読むことを前提にせず、共通指示はCLAUDE.mdからインポートする等、各ツールの読み込み方式を確認します（公式：AGENTS.mdとの共有）。
よくある失敗とアンチパターン
失敗1：デプロイ先の制約を書かない
CLAUDE.mdにデプロイ先の制約がないと、AIが意図しない環境にデプロイするリスクがあります。テスト環境が複数ある構成では、環境名だけでなく対象プロジェクトや接続先も指定し、実行前に照合します。デプロイ権限も対象環境に限定する設計を検討してください。
失敗2：.envのガードレールがない
.env等から読み取った認証情報が、応答や実行ログに表示されるおそれがあります。CLAUDE.mdには取り扱い方針を明記し、ファイル・シェル双方のアクセス権とログ出力を確認してください。指示の有無だけで露出を防げるわけではありません（公式：ツールとファイルの権限）。
失敗3：CLAUDE.mdを肥大化させる
長いCLAUDE.mdでは、重要な指示が埋もれるおそれがあります。500行を境に必ず逆効果になるという仕様ではありません。200行程度を整理の目安に、条件付きの指示はパス指定した.claude/rulesへ、必要な時だけ使う手順はSkillsへ分離することを検討してください。パス指定のないrulesへ分けるだけでは、開始時に読む総量は減りません。
失敗4：曖昧な指示を書く
「コードの品質に気をつけてください」のような曖昧な指示はAIに対して意味をなしません。「関数は50行以内にする。超える場合は分割する」のように定量的・具体的に書きましょう。
まとめ：CLAUDE.mdは「育てる」もの
CLAUDE.mdは一度書いたら終わりではありません。AIが間違えるたびにルールを追加し、古くなったルールを削除し、チームの学びを反映して育てていくドキュメントです。
本記事の7原則（取捨選択テスト・断言形・トリガー形式・200行程度を目安とした整理・セキュリティ最上部・チーム共有・/init後カスタマイズ）を改善の出発点とし、実際の出力や操作を確かめながら見直してください。記載だけで品質や禁止操作の遵守を保証するものではありません。
AIエージェント活用・CLAUDE.md設計はrenueにご相談ください
renueでは、プロジェクトガイド型・開発制約型・CI/CD連携型・マルチエージェント型の4パターンを選択肢として、プロジェクトの用途や許可する操作範囲に合わせたCLAUDE.md設計を支援します。AIエージェント運用で想定されるリスクを整理し、指示書と権限設定、レビュー手順を組み合わせて検討します。
