



WithCodeMedia-1-pc
WithCodeMedia-2-pc
WithCodeMedia-3-pc
WithCodeMedia-4-pc




WithCodeMedia-1-sp
WithCodeMedia-2-sp
WithCodeMedia-3-sp
WithCodeMedia-4-sp









生徒Claude Codeに毎回『このプロジェクトはこういうルールで』って説明するのが面倒で…。一度覚えさせておくことってできないんですか?
ペン博士それが『CLAUDE.md』の役割だよ。プロジェクトのルールや前提を書いておくと、Claude Codeが毎回それを読んでから作業してくれる。置き場所と書き方、実際の記述例から運用のコツまで、この記事で全部まとめて紹介するね!
Claude Codeを使っていると「毎回同じ前提を説明するのが手間」と感じます。それを解決するのがCLAUDE.md。プロジェクトのルールや作業方針を書いておくと、Claude Codeが起動時に自動で読み込み、それに沿って作業してくれる指示ファイルです。この記事では、配置場所と優先順位、何を書くと効くのか、実際のCLAUDE.mdの書き方、良い例と悪い例の対比、@インポートや/initの活用、チーム運用のコツ、よくある失敗とFAQ、そのまま使えるテンプレート集まで、CLAUDE.mdに関して知っておきたいことを完全版として一気に解説します。
CLAUDE.mdは、人が明示的に書く“Claude Codeへの指示書”です。AIが会話の中で自動的に記録していくメモとは別物で、「このプロジェクトではこうしてほしい」というルールを、人間があらかじめ書き残しておくためのMarkdownファイルです。
Claude Codeは起動時、そして作業の文脈に応じて、このファイルの内容を読み込みます。つまりCLAUDE.mdに書いた内容は、毎回のチャットで自分が口頭で伝えていた前提を、ファイルとして一度だけ書いておけば済むようになる、という発想のものです。
Claude Codeのようなコーディング支援AIは非常に賢いものの、あなたのプロジェクト固有の事情までは知りません。たとえば次のような情報は、放っておくとAIが推測で動いてしまい、意図とズレた結果になりがちです。
npm test なのか pytest なのか)こうした“毎回伝えていること”をCLAUDE.mdにまとめておくと、会話のたびに説明する手間がなくなり、AIの出力も安定します。人が増えても、新メンバーは同じルールでAIを使えるようになります。
名前のとおり拡張子は .md、つまりただのMarkdownテキストファイルです。特別なフォーマットや独自の構文を覚える必要はありません。見出し(#)、箇条書き(-)、コードブロック(```)といった、ふだんREADMEを書くのと同じ書式がそのまま使えます。
ポイントは、“きれいな文章”より“AIが守りやすい明確な指示”を書くこと。装飾よりも、何をしてほしいか・何をしてほしくないかが一目でわかる構造が大切です。
CLAUDE.mdは1か所だけでなく、複数の場所に置けて、用途で使い分けるのが特徴です。まず全体像を表で押さえましょう。
| 場所 | 適用範囲 | 主な用途 | Git共有 |
|---|---|---|---|
| ~/.claude/CLAUDE.md | 全プロジェクト(個人) | 自分の共通ルール・話し方の好み | しない(個人設定) |
| ./CLAUDE.md | そのプロジェクト | ビルド手順・規約・構成 | する(チーム共有) |
| ./CLAUDE.local.md | そのプロジェクト(個人) | 自分用メモ・個人的な実験設定 | しない(.gitignore) |
プロジェクト用はGitで共有し、個人用ローカルは.gitignoreに入れる——これが基本の使い分けです。それぞれの役割をもう少し詳しく見ていきましょう。
ホームディレクトリの ~/.claude/CLAUDE.md は、あなたが関わる“すべてのプロジェクト”に共通して効く個人設定です。プロジェクトをまたいで毎回伝えたいこと、たとえば次のような内容を書くのに向いています。
この場所はあなた専用なので、チームには共有されません。好みや習慣など“自分だけのルール”を書く場所だと考えるとわかりやすいです。
プロジェクトのルート(リポジトリの一番上の階層)に置く ./CLAUDE.md は、そのプロジェクトに関わる全員で共有する“チームの合意”を書く場所です。Gitにコミットして共有するのが前提で、もっとも重要なファイルだと言えます。
プロジェクト用CLAUDE.mdは、リポジトリ内のサブディレクトリにも置けます。たとえばモノレポで packages/api/CLAUDE.md のように置くと、そのディレクトリ配下を作業しているときに、より局所的なルールを追加で読ませることができます。全体ルールはルートに、個別ルールは各サブディレクトリに、という整理が可能です。
./CLAUDE.local.md は、そのプロジェクト内で“自分だけ”が使う個人メモです。チームには共有したくない実験的な設定や、自分の作業環境固有のメモ(ローカルのパスやポート番号など)を書くのに向いています。
CLAUDE.local.md は必ず .gitignore に入れるのが鉄則です。共有してしまうと、他のメンバーの環境と食い違って混乱の原因になります。なお、近年は「ローカル設定はサブディレクトリのCLAUDE.mdやインポートで管理する」運用も増えていますが、いずれにせよ“共有するもの/しないもの”を明確に分けるという考え方が大切です。
複数のCLAUDE.mdが同時に効く場合、基本的により具体的(プロジェクトに近い)ものが、より一般的(個人共通)なものを補完・上書きするイメージで考えると整理しやすいです。
矛盾するルールを複数の場所に書くと、AIが迷う原因になります。「個人用には汎用ルール」「プロジェクト用には固有ルール」と役割を分け、重複や矛盾を避けることを意識しましょう。
CLAUDE.mdは、あれもこれも詰め込むより、“毎回伝えていること”だけを簡潔に書くのがコツです。長すぎると逆効果になることもあります(理由は後述します)。まずは効果の高い定番項目を押さえましょう。
もっとも効果が出やすいのがこれです。「テストはどう実行するか」「開発サーバーはどう起動するか」をAIが知っていると、作業後の確認まで自走してくれます。
npm test / pytest / go test ./... などnpm run dev / python app.py などnpm run build / make などnpm run lint / ruff check など命名ルール・使用ライブラリ・フォーマットの方針を書いておくと、生成されるコードがプロジェクトの既存コードになじみます。
主要ディレクトリの役割と、触ってはいけない場所を明記すると、AIが見当違いの場所を編集する事故が減ります。
## ディレクトリ構成
- src/components/ … 再利用するUIコンポーネント
- src/pages/ … 画面(ルーティング単位)
- src/lib/ … APIクライアント・ユーティリティ
- supabase/ … DBマイグレーション(手で編集しない)
- public/ … 静的ファイル意外と効くのが“やってほしくないこと”を明示することです。AIは「できること」を積極的に提案しがちなので、ガードレールを言葉にしておくと安心です。
git push --force はしない」コードそのもの以外の好みも書けます。「説明は日本語で」「変更前に方針を提示してから着手」「コミットメッセージは英語の命令形で」など、自分やチームのスタイルに合わせられます。
プロジェクトが依存している外部サービスや、環境ならではの注意点も効きます。AIが知りようのない“このプロジェクト特有の事情”ほど、書く価値が高いと考えてください。
これらは一般的な開発知識だけでは推測できない情報です。“ここを知らないと事故るポイント”を先回りして書いておくことで、AIの提案が一気に的確になります。
ここからは、そのまま参考にできる実際のCLAUDE.mdの記述例をいくつか紹介します。プロジェクトの種類ごとに、どんな粒度で書くとよいかを見ていきましょう。
# プロジェクト概要
このリポジトリは、Next.js(App Router)+ TypeScript の
コーポレートサイトです。
## よく使うコマンド
- 開発サーバー起動:npm run dev
- テスト:npm test
- Lint:npm run lint
- ビルド:npm run build
## コーディング規約
- コンポーネントは関数コンポーネント+TypeScript で書く
- スタイルは Tailwind CSS を使う(CSS Modules は新規追加しない)
- 状態管理は React の標準フックで完結させる
- import は絶対パス(@/...)を使う
## 構成
- app/ … ルーティングと画面
- components/ … 再利用UI
- lib/ … APIクライアント・ユーティリティ
## やってほしくないこと
- 既存の依存パッケージのバージョンを勝手に上げない
- 指示にない大規模リファクタリングはしない
- .env 系のファイルは変更しないポイントは、最初に「このリポジトリは何か」を1〜2文で説明していること。AIは全体像をつかんでから個別ルールを読むほうが、的確に動けます。
# このプロジェクトについて
CSVデータを集計してレポートを生成するPython製のCLIツールです。
## 環境とコマンド
- Python は 3.10 系を使用
- 仮想環境:venv(.venv/)
- テスト:pytest
- 整形・Lint:ruff format / ruff check
## 規約
- 型ヒントは必ず付ける
- 関数は1つの責務に絞る
- 例外は握りつぶさず、わかるメッセージで再送出する
## 注意
- data/ 配下には実データが入る。中身を勝手に書き換えない
- 新しい外部ライブラリの追加は事前に相談する# 開発ルール(チーム共有)
## ブランチ運用
- main から feature/xxx を切って作業する
- main へ直接 push しない(必ずPR経由)
## コミットメッセージ
- 形式:種別: 内容(例 fix: ログイン時の不具合を修正)
- 種別は feat / fix / docs / refactor / test から選ぶ
## レビュー前チェック
- npm test が通ること
- npm run lint が通ること
- 不要な console.log を残さないチーム用のCLAUDE.mdは、人間向けの開発ガイドラインとほぼ同じ内容になることが多いです。AIにとってもチームメンバーにとっても同じドキュメントが役立つので、一石二鳥になります。
同じことを書くにも、AIが守りやすい書き方と、守りにくい書き方があります。具体例で対比してみましょう。
| 悪い例(曖昧) | 良い例(具体的) |
|---|---|
| きれいなコードを書いて | 関数は50行以内、1関数1責務にする |
| ちゃんとテストして | 変更後は npm test を実行し、通ることを確認する |
| いい感じに命名して | コンポーネントはPascalCase、変数はcamelCase |
「きれいに」「ちゃんと」「いい感じに」は人によって解釈が違うため、AIも判断に迷います。判断基準を数値や具体名で書くほど、結果が安定します。
「念のため全部書いておこう」と何百行も書くのは逆効果です。CLAUDE.mdは毎回読み込まれるため、長すぎると“文脈(コンテキスト)”を圧迫し、肝心の指示が埋もれてしまいます。
AIがもともと持っている一般常識まで書く必要はありません。「このプロジェクトだから特別に必要なこと」だけを書くと意識すると、自然と簡潔になります。
なぜ長さが問題になるのかというと、AIは一度に扱える文脈(コンテキスト)に上限があるからです。CLAUDE.mdは作業のたびに読み込まれるため、ここが長大だと肝心のソースコードや会話に割けるスペースが圧迫され、結果的に精度が落ちることがあります。「全部書く」より「効くものだけ書く」ほうが、トータルで賢く動いてくれるのです。
だらだらと文章で書くより、見出しと箇条書きで構造化したほうがAIも人も読みやすくなります。
「○○するな」だけだと、AIは「では何をすればいいか」で迷うことがあります。禁止する場合は、できれば代わりの方法もセットで書くと効果的です。
ここまでの内容を、「CLAUDE.mdがある場合とない場合で、AIの動きがどう違うか」という観点で具体的に見てみましょう。同じ「ログイン機能のバグを直して」という依頼をしたとします。
AIはプロジェクトの前提を知らないため、推測で動きます。その結果、たとえば次のようなズレが起こりがちです。
毎回これを口頭で補足すれば防げますが、依頼のたびに同じ説明を繰り返す必要があり、説明し忘れると事故になる——これがCLAUDE.md無しの状態です。
同じ依頼でも、CLAUDE.mdに前提が書いてあれば、AIは最初から正しいルールに沿って動き、作業後の確認まで自走します。
つまりCLAUDE.mdは、“AIに毎回同じ注意をする手間”を“一度書くだけ”に置き換える仕組みです。書く労力は一度きり、その効果は毎回のセッションで積み重なっていきます。
混同しやすいので整理しておきます。Claude Codeには、会話の中で得た情報をAIが自動で記録していく“メモ”的な仕組みもあります。これとCLAUDE.mdは「誰が書くか」「いつ効くか」が違います。
| 観点 | CLAUDE.md | 自動メモ(AIが記録) |
|---|---|---|
| 書く主体 | 人間が明示的に書く | AIが会話から自動で記録 |
| 性質 | 守ってほしいルール・指示 | 覚えておくと便利な事実・経緯 |
| 管理 | Gitで共有・レビューできる | AI任せで蓄積される |
「絶対に守ってほしいルール」はCLAUDE.mdに人が書くのが基本です。自動メモは補助的な記憶であり、確実に効かせたい約束事はCLAUDE.mdに明示するのが安全です。
CLAUDE.mdの中に @ から始まるパスを書くと、別のファイルの内容を読み込ませる(インポートする)ことができます。CLAUDE.md本体を肥大化させずに、詳細な資料を必要に応じて参照させたいときに便利です。
# プロジェクトのルール
詳しいコーディング規約は別ファイルにまとめています。
@docs/coding-guidelines.md
@docs/api-conventions.md
## このプロジェクト固有の注意
- 決済まわりは src/payments/ にまとまっている
- テストは npm test で実行するこの書き方のメリットは、CLAUDE.md本体は短く保ちつつ、必要な詳細を分割して管理できることです。ガイドラインのような長い文書は別ファイルに切り出し、CLAUDE.mdからは @ で参照する、という整理ができます。
なお、ファイルを文脈に取り込む方法としては、チャットの中で @ファイル名 と入力してその場で取り込む使い方もあります。CLAUDE.md内の@は“常に取り込む”、チャット内の@は“その時だけ取り込む”という違いで覚えておくと混乱しません。
「ゼロから書くのは面倒」という場合は、/init コマンドでCLAUDE.mdのひな形を自動生成できます。Claude Codeがプロジェクトを解析し、構成や使われている技術をもとに、たたき台を作ってくれます。
# Claude Code を起動したあと、対話画面で実行
/init実行すると、ディレクトリ構成・主要なコマンド・使用技術などをまとめた CLAUDE.md が生成されます。これをそのまま使うのではなく、たたき台として“育てていく”のが正しい使い方です。
CLAUDE.mdは一度書いて終わりではありません。「AIが間違えたら、その都度ルールを1行足す」というサイクルで、少しずつ精度を上げていくのが理想的な運用です。
CLAUDE.mdは個人利用でも便利ですが、チームで共有すると効果が何倍にもなるファイルです。全員が同じルールでAIを使えるようになり、コードの一貫性が保たれます。運用上のポイントを押さえましょう。
./CLAUDE.md は必ずリポジトリにコミットして共有します。READMEと同じ感覚で、プロジェクトの“正”として全員が参照・更新できる状態にしておきます。
一方で、個人の好みやローカル環境固有の設定は共有しません。CLAUDE.local.md は .gitignore に入れるのを徹底します。.gitignore には次のように書いておきます。
# 個人用のローカルCLAUDE設定
CLAUDE.local.mdCLAUDE.mdの変更は、コードと同じようにプルリクエストでレビューするのがおすすめです。「このルールを足したい」を全員で議論できるので、ルールが独りよがりになりません。
よく整理されたCLAUDE.mdは、そのまま新メンバー向けの開発ガイドにもなるという副次効果があります。AIのためのルールが、人のための入門資料を兼ねるわけです。
運用を続けると、似たようなルールが増えたり、古い規約が残ったりします。定期的に見直して、矛盾・重複・不要になったルールを削ることで、CLAUDE.mdは常に“効くファイル”であり続けます。
CLAUDE.mdは便利な反面、書き方を誤ると「書いたのに効かない」「かえって混乱する」ことがあります。典型的な失敗パターンと対策をまとめておきます。
| 失敗パターン | 何が起きるか | 対策 |
|---|---|---|
| 内容を詰め込みすぎ | コンテキストを圧迫し、肝心の指示が埋もれる | 毎回必要な要点だけに絞る・@で分割 |
| 曖昧な表現 | AIが解釈に迷い、結果がぶれる | 数値や具体名で判断基準を書く |
| 矛盾するルール | AIがどちらに従うか不安定になる | 個人用と固有ルールの役割を分ける |
| 更新しないまま放置 | 古い規約に沿った誤った提案が出る | 間違いに気づくたび1行ずつ更新 |
| 機密情報を直書き | Gitに乗ると情報漏えいのリスク | 鍵やパスワードは書かない・環境変数で管理 |
特に最後の「機密情報を書かない」は絶対のルールです。CLAUDE.mdはGitで共有することが多いため、APIキー・パスワード・トークンなどを直接書くと、リポジトリ経由で外部に漏れる恐れがあります。秘密情報は環境変数(.env)など別の安全な仕組みで管理し、CLAUDE.mdには「鍵は .env を参照する」といった“場所だけ”を書くようにします。
いいえ、無くてもClaude Codeは動きます。ただし、毎回同じ前提を説明している自覚があるなら、作る価値は十分にあります。まずは /init でたたき台を作るだけでも効果を実感できます。
基本的に、Claude Codeはセッションの中でCLAUDE.mdを読み込みます。編集した内容を確実に反映させたいときは、新しいセッションを開始する、もしくは設定を読み直すと安心です。
明確な決まりはありませんが、目安は「ひと目で全体を見渡せる長さ」です。数十〜百数十行程度に収め、それ以上に詳しい資料は @ インポートで別ファイルに切り出すのが現実的です。
READMEは主に“人”に向けた説明、CLAUDE.mdは主に“AI”に向けた指示です。内容は重なる部分もありますが、CLAUDE.mdには「やってほしくないこと」「守ってほしいルール」など、AIの振る舞いを制御する記述を多めにするのがコツです。
両方とも読み込まれ、個人用の汎用ルールの上に、プロジェクト用の固有ルールが重なるイメージで効きます。矛盾しないように、役割を分けて書くのがポイントです。
問題ありません。日本語でも英語でも、AIは内容を理解します。チームの共通言語に合わせて書けばよく、無理に英語にする必要はありません。
いくつか原因が考えられます。①記述が曖昧で解釈の余地がある、②内容が長すぎて埋もれている、③矛盾するルールが別の場所にある——のいずれかが多いです。まずは該当のルールを具体的な表現に直し、それでも効きにくければ、文頭や重要セクションに移して目立たせると改善します。それでも徹底したい強い制約(危険なコマンドの禁止など)は、フックなどの仕組みで“技術的に止める”ことも検討しましょう。
できます。各サブディレクトリにCLAUDE.mdを置けば、そこを作業しているときに局所的なルールが追加で効きます。共通ルールはルートに、パッケージ固有のルールは各パッケージ配下に、という整理がきれいです。
最後に、コピーして自分のプロジェクトに合わせて埋めるだけで使えるテンプレートを用意しました。まずはミニマル版から始め、必要に応じて項目を足していくのがおすすめです。
# プロジェクト概要
(このリポジトリが何をするものか、1〜2文で)
## よく使うコマンド
- 起動:
- テスト:
- ビルド:
- Lint:
## やってほしくないこと
-
-# プロジェクト概要
(このリポジトリの目的・技術スタックを簡潔に)
## よく使うコマンド
- 開発サーバー起動:
- テスト:
- ビルド:
- Lint/整形:
## ディレクトリ構成
- src/ …
- tests/ …
- (触ってほしくない場所があれば明記)
## コーディング規約
- 命名:
- 使用ライブラリ:
- 整形ルール:
## やってほしくないこと
- 本番設定(.env 系)は変更しない
- 依存バージョンを勝手に上げない
- 指示にない大規模リファクタリングはしない
## 回答・進め方の好み
- 説明は日本語で
- 変更前に方針を提示してから着手する# プロジェクトのルール
詳細は別ファイルにまとめています。
@docs/architecture.md
@docs/coding-guidelines.md
## このプロジェクト固有の最重要ルール
- テストは npm test、必ず通してから完了とする
- supabase/ のマイグレーションは手で編集しない
- 機密情報(鍵・トークン)は .env を参照し、コードに書かない| 用語 | 意味 |
|---|---|
| CLAUDE.md | Claude Codeに作業ルールを覚えさせる指示ファイル |
| ~/.claude/ | 個人共通の設定を置くホーム配下のフォルダ |
| CLAUDE.local.md | そのプロジェクトの“自分だけ”のローカル設定 |
| @インポート | @パス で別ファイルの内容を取り込む書き方 |
| /init | プロジェクトを解析してCLAUDE.mdのひな形を作るコマンド |
| コンテキスト | AIが一度に読み込める文脈の量。長文は圧迫する |
CLAUDE.mdは、Claude Codeに自分やチームのルールを覚えさせるための指示ファイルです。個人用・プロジェクト用・ローカル用を役割で使い分け、ビルド手順や規約、禁止事項を簡潔にまとめておけば、毎回の説明が不要になり、AIの出力も安定します。曖昧な表現を避けて判断基準を具体的に書き、長くなりすぎないよう @ インポートで分割し、間違いに気づくたびに少しずつ育てていく——この運用ができれば、Claude Codeはあなたのプロジェクトに最適化された相棒になります。まずは /init でたたき台を作るところから始めてみましょう。
・役割:Claude Codeへの永続的な指示書(人が書くルール)
・置き場所:個人用(~/.claude)・プロジェクト用・ローカル用を使い分け
・書き方:要点だけ簡潔に・具体的に・構造化して書く
・運用:/initで生成し、@で分割、間違うたびに1行ずつ育てる
良いルールを書くには、良い設計を知っていることが前提です。WithCodeで実務的な開発の型を学べば、AIに渡す指示の質も自然と上がり、CLAUDE.mdの精度も一段高くなります。

副業・フリーランスが主流になっている今こそ、自らのスキルで稼げる人材を目指してみませんか?
未経験でも心配することはありません。初級コースを受講される方の大多数はプログラミング未経験です。まずは無料カウンセリングで、悩みや不安をお聞かせください!
WithCodeでWeb制作を習得後、フリーランスエンジニアとして活動。HTML/CSS・JavaScript・WordPress案件を中心に年間20件以上の制作実績を持つ。「難しい技術をわかりやすく」をモットーに、初心者〜中級者向けの技術記事を執筆。副業・フリーランス独立を目指す方に向けた情報発信に注力している。
公式サイト より
今すぐ
無料カウンセリング
を予約!