CLAUDE.mdの書き方｜Claude Codeに開発ルールを正しく伝える方法

Claude Codeを使っていると、毎回同じ開発ルールやコーディング規約を説明する場面があります。テストコマンド、ディレクトリ構成、命名規則などは、都度プロンプトで伝えるよりも、CLAUDE.mdに整理しておく方が効率的です。

CLAUDE.mdは、Claude Codeにプロジェクトの前提や開発ルールを伝えるMarkdownファイルです。ただし、内容が長すぎたり、抽象的だったり、矛盾したルールが混在していたりすると、かえって判断しにくくなります。

この記事では、CLAUDE.mdの役割、書くべき内容、伝わりやすい書き方、配置場所、チーム開発での管理方法を整理します。

CLAUDE.mdとは何か

CLAUDE.mdを書く前に、まずはこのファイルの役割を理解しておく必要があります。単なるメモやREADMEの代替ではなく、Claude Codeに開発時の前提を伝えるためのファイルとして整理することが大切です。

Claude Codeに継続的な指示を伝えるMarkdownファイル

CLAUDE.mdは、Claude Codeに対して継続的な指示を与えるMarkdownファイルです。プロジェクトの概要、コーディング規約、テスト方法、アーキテクチャ上の注意点など、作業時に参照してほしい情報をまとめます。
ただし、強制的な設定ファイルではなく、判断を補助するコンテキストとして扱うのが適切です。

READMEや通常のプロンプトとの違い

READMEは、人間の開発者に向けてプロジェクト概要やセットアップ方法を説明するドキュメントです。
通常のプロンプトは、その時点で依頼する個別作業の指示です。

CLAUDE.mdは、Claude Codeが作業時に参照する前提情報をまとめるファイルであり、毎回説明する必要があるルールを集約できます。

自動メモリとの違い

Claude Codeには、CLAUDE.mdとは別に自動メモリの仕組みもあります。CLAUDE.mdはユーザーが明示的に書く指示であり、自動メモリはやり取りから蓄積される情報です。
チームとして必ず守りたいルールや共通のコーディング規約は、自動メモリに任せずCLAUDE.mdに明示するべきです。

CLAUDE.mdに書くべき内容

CLAUDE.mdには、Claude Codeに毎回守ってほしい開発上の前提を書きます。何でも詰め込むのではなく、プロジェクト理解やコード変更の品質に関わる情報を優先することが重要です。

プロジェクト概要と技術スタック

まず書くべきなのは、プロジェクトの概要と技術スタックです。
何を目的としたアプリケーションなのか、どの言語やフレームワークを使っているのかを簡潔にまとめます。
「使いやすいシステムを目指す」のような抽象表現ではなく、「ReactとTypeScriptで構築された管理画面」「API通信はsrc/api配下に集約する」のように、作業判断に使える形で書くことが大切です。

ディレクトリ構成と責務

次に、ディレクトリ構成と各領域の責務を整理します。
どのフォルダに何を置くべきかが明確でないと、不要な場所にファイルを追加したり、既存の設計方針と異なる変更を行ったりする可能性があります。
「共通UIはsrc/components/commonに追加する」のように、行動に結びつく形で書くと実務に使いやすくなります。

コーディング規約と命名規則

CLAUDE.mdで特に重要なのが、コーディング規約と命名規則です。
AIによるコード生成では、同じ機能でも書き方がばらつくことがあります。「読みやすく書く」ではなく、「関数名は動詞から始める」「ReactコンポーネントはPascalCaseにする」「不要なコメントは追加しない」のように、判断できる形にします。

テストコマンド・ビルドコマンド・lint

変更後に実行すべきテストコマンドやビルドコマンドも、CLAUDE.mdに書いておくと有効です。
どのコマンドで確認すべきかが明確であれば、作業後の検証手順を伝えやすくなります。
コマンド名だけでなく、どの変更時に何を実行するのかまで書くと実務で使いやすくなります。

禁止事項と注意点

CLAUDE.mdには、避けてほしい行動も明記できます。
触ってはいけないファイル、変更前に確認すべき領域、既存仕様を壊さないための注意点などです。「自動生成ファイルは直接編集しない」「既存APIのレスポンス形式は変更しない」のように、品質や安全性に直結するものを具体的に書きます。

Claude Codeに伝わりやすいCLAUDE.mdの書き方

CLAUDE.mdは、書いた内容が機械的に強制される設定ファイルではありません。そのため、Claude Codeが参照しやすいように、簡潔で具体的な指示に整える必要があります。

抽象的な指示ではなく、具体的な行動に落とし込む

避けたいのは、抽象的な指示だけを書くことです。「きれいに書く」「保守性を高める」「適切にテストする」といった表現は、具体的な判断基準になりにくい指示です。
「2スペースのインデントを使用する」「変更後にテストを実行する」のように、確認可能な行動に落とし込むと伝わりやすくなります。

優先順位が分かるように書く

複数のルールを書く場合は、優先順位が分かるように整理します。すべてのルールを同じ重要度で並べると、Claude Codeが判断に迷いやすくなります。「必ず守るルール」「推奨する書き方」「判断に迷ったときの方針」のように分類し、セキュリティや既存仕様に関わるルールは優先度を高くします。

長すぎる説明は分割する

CLAUDE.mdが長くなりすぎると、重要なルールが埋もれます。詳細な手順や細かい運用ルールをすべて1つのファイルに入れると、参照すべき情報が分かりにくくなります。
複数ステップの手順や繰り返し使うチェックリストが増えてきた場合は、別ファイルやSkillsなどに分けることも検討します。

矛盾するルールを残さない

CLAUDE.mdでは、矛盾したルールを残さないことも重要です。ある箇所ではcamelCaseを求め、別の箇所ではsnake_caseを求めていると、どちらを優先すべきか判断しにくくなります。
CLAUDE.mdは情報量が多いほどよいのではなく、現在の開発ルールを正しく反映していることが重要です。

CLAUDE.mdの配置場所と管理方法

CLAUDE.mdは、どこに置くかによって適用範囲が変わります。個人用のルール、プロジェクト共通のルール、ローカル環境だけのルールを分けて管理することで、チーム利用でも扱いやすくなります。

プロジェクト用のCLAUDE.mdはリポジトリで管理する

チームで共有する開発ルールは、プロジェクト用のCLAUDE.mdにまとめます。アーキテクチャ、コーディング規約、テスト方針、レビュー観点、禁止事項などは、共有ファイルに整理した方が安定します。リポジトリで管理すれば、コードと同じように変更履歴を残せます。

個人用ルールはCLAUDE.local.mdに分ける

個人の作業環境や好みは、共有用のCLAUDE.mdに混ぜない方が安全です。ローカル環境や作業ショートカットなどは、チーム全体の開発ルールとは性質が異なります。
共有ルールと個人ルールを分けることで、チーム共通のCLAUDE.mdが個人の事情で複雑になるのを防げます。

/memoryで読み込み状況を確認する

CLAUDE.mdを書いたのに反映されていないと感じる場合は、まず読み込み状況を確認します。ファイル名や配置場所が誤っている、Claude Codeを起動したディレクトリが想定と違う、といった原因が考えられます。
文章を直す前に、まず対象ファイルが読み込まれているかを確認することが重要です。

CLAUDE.mdを書くときに避けるべきこと

CLAUDE.mdは便利な一方で、書き方を誤るとClaude Codeの出力を安定させるどころか、かえって判断を迷わせる原因になります。

ここでは、実務で避けるべき書き方を整理します。

目的が曖昧なルールを書く

もっとも避けたいのは、目的が曖昧なルールを書くことです。「よいコードを書く」「保守性を意識する」「分かりやすく実装する」といった表現は、具体的な判断基準にはなりません。
「同じ処理が複数回出る場合は共通化を検討する」のように、実際の作業に結びつく指示に変えることが重要です。

プロジェクトに関係のない情報を入れる

CLAUDE.mdには、プロジェクトの作業に必要な情報だけを書くべきです。個人の作業メモ、短期的なタスク、古い仕様、すでに使われていないコマンドなどを入れると、ファイルの信頼性が下がります。一時的な作業指示は通常のプロンプトやタスク管理ツールで扱います。

READMEや設計書の内容をそのまま貼り付ける

READMEや設計書の内容をそのままCLAUDE.mdに貼り付けるのも避けるべきです。人間向けのドキュメントは背景説明や補足が多く含まれるため、そのままでは冗長になる場合があります。

CLAUDE.mdに必要なのは、作業判断に使う要点です。

守れないルールを前提にする

CLAUDE.mdに、実現できない前提を書くことも避けるべきです。「すべてのバグを防ぐ」「完璧に仕様を判断する」といった指示は、現実的な開発ルールではありません。
結果保証ではなく、「影響範囲を説明する」「不明点がある場合は確認する」といった行動基準を書くべきです。

チーム開発でCLAUDE.mdを活用するポイント

チームでClaude Codeを使う場合、CLAUDE.mdは開発ルールの共有や出力品質のばらつきを抑えるための基盤になります。ただし、内容が古くなりやすい点に注意が必要です。

チーム共通の開発標準として扱う

チームで使うCLAUDE.mdは、AI向けの開発標準ドキュメントとして扱うとよいでしょう。コーディング規約、レビュー観点、テスト方針、禁止事項などを整理することで、メンバーごとの指示のばらつきを減らせます。
ただし、個人の好みは混ぜず、チームで合意したルールに絞ります。

変更時のレビュー対象にする

CLAUDE.mdは、コードと同じようにレビュー対象にするべきです。CLAUDE.mdに書かれたルールは、Claude Codeの出力に影響します。ビルドコマンド、ディレクトリ構成、レビュー観点、禁止事項を変更した場合は、CLAUDE.mdも更新対象に含めます。

最初から完璧を目指さず、運用しながら更新する

CLAUDE.mdは、最初から完璧な内容を作ろうとする必要はありません。
まずは、プロジェクト概要、主要な技術スタック、テストコマンド、最低限のコーディング規約、触ってはいけない領域を入れます。その後、同じ間違いやレビュー指摘が繰り返される箇所を追記します。

まとめ｜CLAUDE.mdはClaude Codeに開発前提を伝えるための設計書

CLAUDE.mdは、Claude Codeに任せるための魔法の設定ではなく、開発ルールや判断基準を整理して伝えるためのファイルです。正しく整備すれば、毎回の説明を減らし、チーム全体で出力品質をそろえやすくなります。

書くべき内容は、プロジェクト概要、技術スタック、ディレクトリ構成、コーディング規約、命名規則、テストコマンド、禁止事項などです。重要なのは、具体的で確認可能な形にすることです。

一方で、情報を詰め込みすぎると、重要なルールが埋もれます。長すぎる説明、矛盾したルール、古い仕様、個人の好みは、出力品質を不安定にする原因になります。CLAUDE.mdを継続的に見直し、開発フローに合わせて更新することで、Claude Codeをより安定した開発支援ツールとして活用しやすくなります。

---