CLAUDE.mdの書き方｜Claude Codeへ開発ルールを渡す設計

Claude Codeはコードベースを読み、ファイルを編集し、コマンドを実行できるエージェント型のコーディングツールです。その作業に継続的な前提を渡すのがCLAUDE.mdです。公式ドキュメントは、プロジェクトのアーキテクチャ、コーディング標準、共通ワークフローなどを用途として挙げています。初めて導入する場合は、先にClaude Codeの基本的な使い方を確認すると、指示ファイルが担う範囲を切り分けやすくなります。

依存関係はパッケージ管理ファイル、公開APIはコードやスキーマ、詳しい背景は設計文書にあります。同じ内容を長く転記すると、原本の変更後に食い違いが生まれます。コードを読めば判明する一覧より、リポジトリから推測しにくい制約と選択理由を優先するのが安全です。

新しいメンバーにも必要な情報を、すべて収めるべきでしょうか。人向けのオンボーディング資料と、毎回コンテキストへ入る指示では適切な密度が異なります。公式ドキュメントが挙げる追加の目安は、同じ説明や訂正を繰り返したとき、レビューで事前に知るべき事項が見つかったときです。実際に起きた摩擦を根拠に、常設する判断を選びます。

初版は、目的と前提、標準コマンド、変更の境界、完了条件の4項目から始めます。目的にはリポジトリが扱う対象と中心的な設計判断を置きます。標準コマンドにはセットアップ、ビルド、テスト、lint、型検査の正確な実行方法を記します。変更の境界では、編集できる領域、生成物、互換性の条件を特定します。完了条件は、通す検査と人が確認する事項を対応させます。

各項目は結果を確かめられる粒度にそろえます。「きれいなコードを書く」からは合否を判断できません。「APIハンドラーはsrc/api/handlersに置く」「変更後にnpm testを実行する」なら、差分と実行結果が証拠になります。4項目の数を守ることより、担当者とClaude Codeが同じ証拠で完了を判断できることが重要です。

箇条書きには「何をするか」だけでなく、必要なら「なぜ」と「どう確認するか」を近くに置きます。たとえば「既存の認証方式を使う」だけでは、対象が曖昧です。「認証処理はsrc/authの既存関数を利用し、新しい認証方式を追加しない。方式変更は担当者へ確認する」とすれば、参照先、禁止、例外時の行動がつながります。

「絶対」「必ず」という語を増やしても、対象や条件が曖昧なら解釈は揺れます。強調の度合いより、対象、条件、期待する証拠をそろえます。たとえば「パッケージ管理にはpnpmを使い、別のロックファイルを作らない」「実装後はpnpm lintとpnpm testを実行し、失敗を報告する」と記せば、観察する差分と結果が明確です。

生成物を扱うなら「src/generatedは直接編集せず、定義を変更して生成コマンドを実行する」のように原本と手順を結びます。外部公開APIの互換性を扱うなら、変更案を提示して担当者の確認を待つ条件まで書きます。例にあるパスやコマンドをコピーせず、リポジトリに実在する名称へ置き換えて初めて有効な指示になります。

プロジェクト共通の指示はリポジトリ直下のCLAUDE.mdまたは.claude/CLAUDE.mdへ置けます。バージョン管理すればチームで共有できます。個人の全プロジェクト向け指示はユーザー領域、同じプロジェクト内で個人だけが使う内容はCLAUDE.local.mdというように、対象者と範囲を分けられます。

ディレクトリ階層にも意味があります。Claude Codeは起動した作業ディレクトリから上位にあるCLAUDE.mdを読み、下位ディレクトリのファイルはその領域のファイルを読むときに読み込みます。大きなモノレポで、フロントエンドとバックエンドの規約が違うなら、ルートへ両方を詰め込まず、適用領域の近くへ置く方が矛盾を減らせます。

配置を増やす前に、同じ論点を複数ファイルへ書いていないか確認します。公式説明によると、発見された指示は文脈へ連結され、単純な置換にはなりません。上位に古い規約が残れば、近い場所の新しい指示と衝突します。チームがレビューする対象には、個々の文面に加えて、実際に読み込まれる組み合わせも含まれます。読み込みはClaude Codeの/contextで確認できます。

公式ドキュメントはCLAUDE.mdを200行未満にすることを目安とし、長い指示はコンテキストを消費して遵守されにくくなり得ると説明しています。この数字は収容量ではなく、見直しの合図です。各行がほぼすべての作業で必要かを先に問い、結果として短く保ちます。

特定のパスやファイル種別だけで必要な規約は.claude/rules/へ分け、pathsを指定します。複数段階の作業手順は必要時に使うスキルへ、背景や議論の履歴は設計文書へ移し、CLAUDE.mdには参照の入口を残します。役割に応じて読み込む時点を変える判断です。

@記法を使えば別ファイルをインポートできます。ただし、公式説明ではインポートした内容も起動時のコンテキストへ入ります。ファイル分割は所有者や見通しの改善には役立つものの、それだけで読み込み量は減りません。軽量化が目的なら、path指定や必要時に使う仕組みを選びます。

CLAUDE.mdへ「秘密情報を出力しない」「本番環境を変更しない」と書けば、行動方針を共有できます。違反を技術的に阻止する機能までは持ちません。公式ドキュメントはCLAUDE.mdを文脈と位置づけ、操作を遮断する用途には権限設定やPreToolUseフックなどを案内しています。具体的な許可範囲はClaude Codeの権限設定でも整理しています。

ここはチーム導入で最も重要な境界です。文章で期待を伝え、機械で守れる境界は機械に任せます。たとえば、実行してはいけないコマンドや読ませてはいけないパスは権限で制限し、編集後のフォーマットやコミット前の検査はフックやCIで実行します。レビュー承認が必要な変更は、開発プロセス側にも条件を置きます。

禁止事項が増え続けているなら、曖昧な表現、競合する指示、検査できない完了条件、広すぎる権限が混ざっていないかを調べます。判断の共有は文章、確実な遮断は設定、品質判定はテストやレビューというように、目的から制御手段を選び直します。

Claude Codeには、コードベースを分析してCLAUDE.mdの出発点を作る/initがあります。生成案にはリポジトリから分かる説明も含まれ得るため、チームが選んだ判断を残してレビューします。指示の所有者と変更理由を記録し、関連するコードやCIの変更と同じプルリクエストで確認できる運用が適しています。

更新の根拠は、同じ訂正が繰り返された、レビューで既知の制約が抜けた、標準コマンドやディレクトリの責務が変わった、といった観察可能な事実です。単発の依頼や個人の好みを共有規約へ昇格させる前に、他の作業にも適用する理由を確かめます。

レビューでは、追加した指示を差分や実行結果で確認できるか、既存のCLAUDE.md・下位ルール・CIと矛盾しないか、対象パスへ限定できないかを見ます。廃止したコマンドや古い構成も同時に削ります。行を足した量ではなく、再発する迷いを減らせるかが更新の判断基準です。

複数のAIコーディングツールを併用し、同じ規約をCLAUDE.mdとAGENTS.mdへ複製すると、片方だけ更新された時点で指示が分岐します。Claude CodeはCLAUDE.mdを扱い、CodexはAGENTS.mdから指示の連鎖を組み立てます。ファイル名も探索方法も同一ではありません。

Claude Codeの公式ドキュメントは、CLAUDE.mdから既存のAGENTS.mdを@AGENTS.mdとしてインポートし、Claude Code固有の指示を追記する構成を案内しています。共通規約の原本を一つにできる選択肢です。インポート部分はClaude Codeにも適用されるため、権限、利用可能なコマンド、運用手順に差がある場合は、共通部分とツール固有部分を明示してレビューします。

CLAUDE.mdは、目的と前提、標準コマンド、変更の境界、完了条件から書き始め、行動と確認方法が読める文にします。コードから分かる説明、一度きりの依頼、特定領域だけの詳しい手順は、それぞれの原本や必要時に読む仕組みへ置きます。

冒頭の問いは二つの基準で解けます。「Claude Codeが毎回知らなければ、チームで合意した判断を再現できないか」で記載事項を選び、「技術的に遮断または検査すべきか」で権限、フック、CIへ分けます。短さ自体を目標にせず、この選別を通った情報だけを残す設計です。

導入後は、指示の読み込み、テスト結果、レビュー差分を観察し、所有者を決めて更新します。CotomuではAI駆動開発研修を30万円、導入パッケージを50万円から、技術顧問を月15万円で提供しています。自社に必要なルールと制御の切り分けを相談したい場合、初回60分の相談は無料です。各支援は生産性や品質の向上を保証するものではなく、Claude CodeやCodexなどの公式認定・提携サービスでもありません。