Claude Codeをチームで導入する際、メンバーごとに使い方がバラバラになってしまう課題に直面していませんか？CLAUDE.mdは、Claude Codeの動作をプロジェクト単位で標準化するための設定ファイルです。コーディング規約の統一、禁止操作の明示、プロジェクト固有のルール設定など、チーム開発に不可欠な機能を提供します。本記事では、CLAUDE.mdの基本から実践的な設定パターンまでを網羅的に解説します。
CLAUDE.mdとは？Claude Codeの動作を制御する設定ファイル
CLAUDE.mdは、Claude Codeがコード生成やリファクタリングを行う際に参照する指示ファイルです。プロジェクトのルートディレクトリに配置することで、Claude Codeはそのファイルの内容を「システムプロンプト」として読み込み、すべての操作に反映させます。これにより、個人の好みに依存しない、チーム統一のAIコーディング体験が実現します。
CLAUDE.mdは複数の階層で配置できます。グローバル設定（~/.claude/CLAUDE.md）はすべてのプロジェクトに適用され、プロジェクトルートのCLAUDE.mdはそのリポジトリ内でのみ有効です。さらにサブディレクトリごとにも配置可能で、より細かい制御が可能です。優先順位はディレクトリの深さに応じて上書きされるため、チーム共通のルールを維持しつつ、個別の調整も柔軟に行えます。
CLAUDE.mdの主要設定項目を徹底解説
コーディング規約の設定
CLAUDE.mdで最も活用されるのがコーディング規約の指定です。たとえば「TypeScriptではinterface よりtype を優先する」「関数コンポーネントのみ使用する」「変数名はキャメルケースで統一する」といったルールを自然言語で記述できます。Claude Codeはこれらの指示に従ってコードを生成するため、レビューでのスタイル指摘が大幅に減少します。インデント幅、セミコロンの有無、インポート順序なども指定でき、Prettierやeslintの設定と合わせて運用することで二重チェック体制が構築できます。
禁止操作の明示
チーム開発において特に重要なのが「やってはいけないこと」の明文化です。CLAUDE.mdでは禁止操作を明記することで、Claude Codeが意図しない変更を行うリスクを最小化できます。具体例としては「本番環境のデータベースに直接接続するコードを生成しない」「git push --forceを実行しない」「.envファイルの内容をコード内にハードコードしない」「既存のAPIエンドポイントのパスを変更しない」などが挙げられます。これらのルールはAIの暴走を防ぐだけでなく、新人メンバーへの暗黙知の共有にも役立ちます。
プロジェクト固有ルールの設定
プロジェクトごとに異なる技術スタックやアーキテクチャに合わせたルールも設定できます。「このプロジェクトではNext.js App Routerを使用している」「状態管理にはZustandを使う」「APIクライアントにはaxiosではなくfetchを使用する」「テストフレームワークはVitestを使用する」といった技術的なコンテキストをClaude Codeに伝えることで、プロジェクトに適したコードが生成されます。また、ディレクトリ構造やファイル命名規則、コンポーネントの分割方針なども記載しておくと、一貫性のあるコードベースの維持に貢献します。
チーム共有のベストプラクティス
CLAUDE.mdをチームで効果的に運用するためのベストプラクティスを紹介します。まず、CLAUDE.mdはリポジトリにコミットして全メンバーで共有しましょう。個人的な好みは~/.claude/CLAUDE.mdに書き、プロジェクトのCLAUDE.mdにはチーム合意のルールのみを記載します。これにより、個人設定とチーム設定の分離が実現できます。
CLAUDE.mdの変更はPull Requestを通じてレビューすることを推奨します。コーディング規約の変更と同じ重要度で扱い、チーム全体の合意を得てからマージしましょう。また、定期的な見直しも重要です。プロジェクトの進行に伴い、新しいルールの追加や不要になったルールの削除を行うことで、CLAUDE.mdの品質を維持できます。四半期ごとのレビューをカレンダーに入れておくことをおすすめします。
記述のポイントとしては、曖昧な表現を避け、具体的な指示を書くことが重要です。「きれいなコードを書く」ではなく「関数は50行以内に収める」「ネストは3段階まで」のように定量的な基準を設けると、Claude Codeの出力が安定します。また、ルールの意図や背景も合わせて記載すると、Claude Codeがコンテキストをより深く理解し、例外的なケースにも適切に対応できるようになります。
実践的な設定例3パターン
パターン1：フロントエンド開発（React/Next.js）
フロントエンド開発向けのCLAUDE.md設定例です。「フレームワークはNext.js 15 App Routerを使用」「コンポーネントはすべてServer Componentをデフォルトとし、use clientは必要最小限にする」「スタイリングにはTailwind CSSを使用し、カスタムCSSは原則禁止」「UIコンポーネントはshadcn/uiを使用する」「フォームバリデーションにはzodを使用し、スキーマはsrc/schemas/に配置する」「画像はnext/imageコンポーネントを使用し、imgタグは使わない」「APIコールはServer Actionsで行い、クライアントサイドからの直接的なfetchは避ける」。このように具体的な技術選定と方針を明記することで、一貫性のあるフロントエンドコードが生成されます。
パターン2：バックエンド開発（Python/FastAPI）
バックエンド開発向けの設定例です。「PythonバージョンはPython 3.12を使用」「WebフレームワークはFastAPIを使用」「型ヒントをすべての関数に付与する」「ORMはSQLAlchemyを使用し、生のSQLクエリは原則禁止」「環境変数はpydantic-settingsで管理し、コード中にハードコードしない」「APIレスポンスは必ずPydanticモデルで型定義する」「例外処理はカスタムExceptionクラスを使用し、汎用的なExceptionのcatchは避ける」「ログ出力にはstructlogを使用し、printは使わない」「テストはpytestで書き、各エンドポイントに対して正常系・異常系のテストを必ず作成する」。バックエンド固有のセキュリティや型安全性に重点を置いた設定が効果的です。
パターン3：データ分析（Python/Jupyter）
データ分析プロジェクト向けの設定例です。「データ操作にはpandasを使用し、DataFrameの列名はスネークケースに統一する」「可視化にはplotlyを使用する（matplotlibは使わない）」「ノートブックのセルは1つの処理につき1セルとし、セルの先頭にマークダウンで処理内容を説明する」「大規模データの読み込みにはpolarsまたはduckdbを検討する」「分析結果はsrc/reports/に保存し、日付プレフィックスを付ける」「データの前処理パイプラインはsrc/preprocessing/にモジュール化する」「シード値は42で固定し、再現性を確保する」。データ分析は探索的な作業が多いため、再現性とドキュメンテーションを重視した設定が重要です。
hooksとの連携でさらに強力に
Claude Codeのhooks機能とCLAUDE.mdを組み合わせることで、より堅牢な開発ワークフローが構築できます。hooksは、Claude Codeの操作の前後に自動的にスクリプトを実行する仕組みです。たとえば、コード生成後に自動的にlinterを実行したり、ファイル保存時にフォーマッターを適用したりできます。
具体的な連携パターンとしては、CLAUDE.mdで「ESLintのルールに従う」と指定しつつ、hooksでコード生成後にeslint --fixを自動実行する設定が挙げられます。これにより、Claude Codeが生成したコードが自動的にフォーマットされ、スタイルの不一致が即座に解消されます。また、テスト関連のhooksとして、新しい関数が追加された際に対応するテストファイルの雛形を自動生成するスクリプトを設定することもできます。
セキュリティ面でもhooksは有効です。CLAUDE.mdで「機密情報をコードに含めない」と記載した上で、hooksでコミット前にシークレットスキャンを実行するよう設定すれば、二重の防御層が形成されます。git-secretsやtrivyなどのツールと連携させることで、APIキーやパスワードの誤コミットを防止できます。CLAUDE.mdによるソフトな制御とhooksによるハードな制御を組み合わせることが、チーム開発におけるベストプラクティスです。
CLAUDE.md導入時の注意点とトラブルシューティング
CLAUDE.mdを導入する際にありがちな問題と対策を紹介します。まず、ルールを詰め込みすぎる問題です。CLAUDE.mdの内容が膨大になると、Claude Codeが相反する指示に混乱する場合があります。ルールは優先度の高いものから記載し、200行以内に収めることを目安にしましょう。どうしても多くなる場合は、ディレクトリごとのCLAUDE.mdに分割することで管理しやすくなります。
次に、CLAUDE.mdが無視されているように見えるケースです。Claude Codeは確率的にテキストを生成するため、必ずしも100%ルールに従うわけではありません。重要なルールは冒頭に配置し、太字やリスト形式で強調すると遵守率が向上します。また、hooksによる自動チェックを併用することで、ルール違反をキャッチする仕組みを整えましょう。チーム内でCLAUDE.mdの運用ルールを定め、定期的にルールの有効性を振り返ることが長期的な成功の鍵となります。