Claude Codeに毎回、同じテスト方法や編集してはいけないファイルを説明している。
その指示をプロジェクトで共有するために使うのが、CLAUDE.mdです。
CLAUDE.mdは作業の指示を伝えるファイルで、操作を強制的に止める設定ではありません。
この記事は、Claude Codeを使う開発担当者と、その作業を管理する責任者向けです。
記入例、読み込まれる範囲、整理の方法、実際の作業で確認することを説明します。
この記事で分かること
- プロジェクトの目的、使っている技術、確認済みのコマンド、変更してよい範囲を記載します
- 新しいセッションで/contextを開き、「Memory files」に対象のパスがあるか確認します
- 現行公式は、CLAUDE.md一つにつき200行未満を目標にすることを推奨しています
CLAUDE.mdには何を書く?
プロジェクトの目的、使っている技術、確認済みのコマンド、変更してよい範囲を記載します。
「きれいなコードを書く」より、「変更後にテストを実行し、結果を確認する」のように、担当者が確認できる内容にします。
実行するコマンドも、プロジェクトで確認済みのものを書きます。
書けば必ず守られるわけではありません。
出力された変更と実行結果を確認し、読み込まれた指示と実際の動作を分けて判断します。
出典:Claude Code公式のメモリ説明。
以下の仕様は2026年10月7日に確認しました。
指示を使う範囲と保存場所
チーム共通のルールはプロジェクトへ置き、個人だけのルールはホームフォルダへ置きます。
| 保存先 | 何を書くか | 誰と共有するか |
~/.claude/CLAUDE.md 利用者のホームフォルダ内 | 個人が全プロジェクトで使う指示 | その利用者の環境 |
./CLAUDE.mdまたは./.claude/CLAUDE.md プロジェクトのフォルダ内 | プロジェクトの構成やテスト手順 | ソース管理を通じてチームへ共有 |
| 下位のディレクトリに置くCLAUDE.md | その領域に固有の指示 | 該当領域を編集する担当者 |
作業フォルダの親フォルダにある指示は開始時に読み込まれます。
子フォルダに置いた指示は、その領域を扱う必要が生じたときに読み込まれます。
ファイルを分けても、共通の指示が消えて個別の指示だけになるわけではありません。
同じ操作について矛盾した指示がないか確認します。
指示と操作制限の違いを示す設計例です。設定後は実際の動作を確認します。
CLAUDE.mdのテンプレート:
請求明細の照合ツールの記入例
以下は架空のPython製ツールを想定した完成例です。目的、保存先、確認する条件まで記入しています。
プログラムの配布や実行結果ではありません。記載したファイルとテストが存在するという想定であり、コマンドはこの記事の制作時には実行していません。
まず構成とコマンドが自分のプロジェクトに合うか確認し、違う箇所を変更してください。
# 請求明細の照合ツール
## 目的
経理担当者が請求明細と発注明細を照合するためのPython製ツール。
支払の承認・実行、取引先への送信は対象外。
## ファイルの場所
src/compare.py:照合処理
tests/:照合条件の単体テスト
samples/:架空の請求明細・発注明細
output/:照合結果。元のCSVとは別に保存する。
README.md:準備方法とCSVの列名の説明
## 作業開始時
README.mdと対象のコードを読んでから変更する。
存在しないファイルや依存関係を、存在するとして説明しない。
samples/以外の顧客資料や秘密情報を読まない。
## 照合条件
注文番号と明細番号で同じ注文を特定する。
商品コード・数量・税抜単価を比較する。
数量が空欄なら0にせず「確認待ち」とする。
注文番号と明細番号の組が重複したら、自動で統合しない。
発注明細が見つからない場合、似た商品から推測しない。
## 変更と確認
変更するのはsrc/とtests/。原本の上書きは禁止。
既存のテストを削除して失敗を隠さない。
テストの想定コマンド:python3 -m unittest discover -s tests
実行前にテストが存在するかと実行条件を確認する。
実行できなければ理由を報告し、成功とは書かない。
## 作業後の報告
変更したファイル、変更理由、実行したコマンドと結果を報告する。
空欄・重複・一致する発注明細がない場合の結果を確認する。
未実施の確認と、残った不具合を分けて書く。
本番への接続・外部送信・公開は実行しない。
この例の要点は、「高品質にする」ではなくどの入力で処理を止めるかまで指定することです。
反対に、個別の作業依頼や大量の仕様書をすべて詰め込む必要はありません。
今回だけの変更は会話で伝え、繰り返し必要な条件をファイルへ残します。
保存場所・起動場所と
読み込みの確認手順
- プロジェクトの最上位フォルダへ、正確な名前で
CLAUDE.mdを保存します。CLAUDE.md.txtになっていないかも確認します。
- 端末版ではそのプロジェクトへ移動して
claudeを起動します。IDEやデスクトップでは、対象のプロジェクトが開かれているか確認します。
- 新しいセッションで
/contextを開き、「Memory files」に対象のパスがあるか確認します。
- 機密情報を含まない小さな変更を依頼し、変更内容とテストの記録を確認します。
既存プロジェクトでは/initで指示ファイルの作成・改善を支援できます。生成内容をそのまま採用せず、実際の起動手順と照合してください。
「読み込まれていない」「読んだが従わなかった」「操作権限がない」は、別の問題です。次の表で切り分けます。
| 症状 | 先に確認すること | 対応 |
| Memory filesに出ない | 名前、保存先、開いているプロジェクト | 対象フォルダから新しいセッションを開始する。組織設定で読み込み元が制限されていないかも確認する。 |
| 子フォルダの指示が開始時に出ない | その領域のファイルをまだ扱っていないか | 必要時に読み込まれる仕様を確認する。全体で必要な指示だけ、プロジェクト共通のファイルへ移す。 |
| 古いコマンドを使う | 個人・親フォルダ・プロジェクトの指示とREADMEの食い違い | 現在の手順を確認し、古い記載を削除する。末尾への追記だけで解消したことにしない。 |
| 読み込まれた禁止事項を守らない | 曖昧な指示や、別ファイルの矛盾した指示 | 具体的な条件へ直し、結果を確認する。禁止操作は権限制御も別に設定する。 |
| コマンドの実行が拒否される | 操作の許可設定と実行環境 | 必要な範囲を管理者と確認する。指示ファイルに「許可」と書いても権限は増えない。 |
個人とプロジェクトの指示に矛盾があると、どちらに従うかを期待どおりに固定できません。両方を整合させてから、読み込みと作業結果を確認します。
7項目の記入例から、
必要なものを選ぶ
以下は、記入内容を考えるための例です。
7項目は公式の必須要件ではなく、弊社が整理する際の候補です。
1.プロジェクトの目的
何を作り、誰が使うかを短く書きます。
# 請求明細の照合ツール
目的:経理担当者が、請求明細と発注明細の差異を確認する。
支払の承認や実行は、このツールの対象にしない。
2.実際に使っている技術
ライブラリや版は、実際の設定ファイルと照合します。
テンプレートに書いてある技術を、使っていることにしてはいけません。
## 技術
言語とライブラリの版は、プロジェクトの設定ファイルで確認する。
新しい依存関係を追加する前に、既存の実装を確認する。
3.コードを変更するときのルール
レビューで確認できる指示にします。
抽象的な品質目標だけでは、どの変更を許可するか決められません。
## 変更時の確認
既存のテストを削除して、失敗を隠さない。
エラーを無視して、正常終了として表示しない。
仕様を変える場合は、変更理由と影響する処理を報告する。
4.業務で禁止する処理
請求書の例なら、空欄や重複をどう扱うかを書きます。
元の書類と照合する条件は、業務担当者が確認します。
## 業務上の条件
数量の空欄を0に置き換えない。
注文番号と明細番号が重複したら、確認待ちにする。
未確認の取引先や商品コードを推測で確定しない。
支払処理は実装・実行しない。
重要な禁止操作は、権限設定、サンドボックス、操作前に判定するフックなどで別に制限します。フックを置くだけで、OSや外部サービスの権限まで制限できるわけではありません。
外部サービスへの接続権限と、本番へ反映する手順も確認します。出典:Claude Code公式のセキュリティ説明。
5.過去に決めたことと、その理由
判断の理由を残すと、条件が変わったときに見直せます。
実際に確認していない出来事を、過去の決定として記載しないでください。
## 判断の記録
日付、決めた内容、理由、見直す条件を残す。
例:取り込み済みの請求を再登録しないため、原本IDと登録状態を保存する。
6.ファイルの保存場所
原本、試験データ、プログラムの場所を記載します。実際に存在するパスへ置き換えてください。
## 保存場所
原本:変更せず保管する場所を記入
試験データ:機密情報を除いたデータの場所を記入
プログラム:実際のファイルの場所を記入
確認結果:テスト結果と承認を残す場所を記入
7.確認済みの実行コマンド
起動やテストのコマンドは、担当者が実際に確認したものを書きます。
使っていないコマンドを例からコピーしないでください。
## 実行と確認
起動コマンド:[実際に確認したコマンド]
テストコマンド:[実際に確認したコマンド]
必要な設定:[秘密情報そのものは書かず、設定する方法を記載]
失敗時の対応:[担当者と確認する記録を記載]
長くなったら、
古い指示を整理する
現行公式は、CLAUDE.md一つにつき200行未満を目標にすることを推奨しています。
ハードな上限ではありません。
古いコマンド、使わなくなった技術、重複した注意を削除します。
新しい失敗ごとに追記するだけでは、矛盾と読み込みの負担が増えます。
特定のフォルダやファイルを扱うときだけ読み込む指示は、.claude/rules/のパス別ルールなどで整理します。
@で別ファイルの内容を指示へ追加しても、開始時にその内容まで読み込まれます。
ファイルを分けるだけでは、AIが毎回読む量は減りません。
特定のコードだけに必要な
条件は、
パス別ルールへ分ける
照合処理だけに必要な条件は、.claude/rules/invoice-check.mdへ記載します。
以下は架空のプロジェクトの記入例です。
---
paths:
- "src/**/*.py"
---
# 請求明細を照合するPythonコードの条件
数量が空欄なら「確認待ち」とし、0に変換しない。
同じ注文番号・明細番号が重複したら、自動で統合しない。
上記の条件を変更した場合は、対応するテストも確認する。
このルールは対象パスのファイルを扱う際に読み込まれます。
pathsのないルールは開始時に読み込まれます。ファイルを分割するだけでは、読み込む時点は変わりません。
指示を書いた後は、
実際の作業で確認する
指示が読み込まれたことと、作業結果が正しいことは別々に確認します。図は手順の説明であり、実行結果のスクリーンショットではありません。
照合ツールなら、数量が空欄の行や重複した明細を含むデータで試します。
担当者が先に期待結果を決め、AIが変更したコードと実行結果を確認します。
指示に「空欄は確認待ち」と書いたことと、実際に確認待ちになったことは別です。
原本の読取、照合、確認、承認済みデータの登録までつなぐ場合は、各工程でも同じ条件が守られるかを確認します。
登録先が空欄を0へ変えてしまうなら、指示の文章ではなく、連携する処理を直す必要があります。
弊社は、CLAUDE.mdを長くすることより、業務の条件を実際のテストと承認へつなぐ運用が重要だと考えています。
チームで導入するなら、指示ファイルの更新者と、コードのレビュー担当者も決めます。指示を共有することと、変更を承認することを同じ作業にしないためです。