CLAUDE.mdの書き方｜最小テンプレートと置き場所、読まれないときの確認手順

CLAUDE.mdは、Claude Codeへ渡す作業の説明書

CLAUDE.mdはMarkdown形式のテキストファイルです。Markdownは、見出しや箇条書きを記号で書ける形式で、特別な編集ソフトは必要ありません。Claude Codeがプロジェクトのルールや背景を読むために使います。普通のClaudeチャットへ同名のファイルを置けば、同じように自動適用されるという意味ではありません。

READMEが人向けの利用説明だとすると、CLAUDE.mdにはAIが作業中に迷いやすい点を絞って書きます。たとえば「テストはこのコマンド」「生成ファイルは直接直さない」「公開は依頼された場合だけ」といった内容です。

• 出典：Claude Code / memory（新しいタブ）

最初はプロジェクトの一番上に置く

例として、sample-appという作業フォルダーの中にpackage.json、src、testsがある構成を考えます。その一番上へCLAUDE.mdを置きます。Windowsでは、拡張子が非表示だとCLAUDE.md.txtになることがあるので、ファイル名も確認してください。

ユーザー共通の指示、プロジェクトの指示、特定フォルダーの指示では適用範囲が異なります。最初から複数へ同じ内容をコピーせず、一枚で確認してから分ける方が、どこから読まれたか追いやすくなります。

使うコマンドを確認してから、テンプレートを埋める

以下は、テスト用コマンドがnpm test、静的検査がnpm run lintとして定義されている架空のアプリ向けです。自分のpackage.jsonにそのコマンドがあることを確認して使ってください。存在しないコマンドをルールへ書くと、毎回同じところで止まります。

「きれいなコードにする」だけでは、何を確認するか曖昧です。変更した動作、実行した検査、まだ確認できていないことを報告させる形なら、人も結果を判断しやすくなります。秘密の値やAPIキーは、説明のためであっても書かないでください。

保存後は、読み込まれたファイルを確かめる

Claude Codeの公式資料では、/contextのMemory filesで読み込まれたCLAUDE.mdを確認でき、/memoryから関連ファイルを確認・編集できます。名称や表示は版により変わるため、手元の画面と公式資料を照合してください。

次に、実際の変更を始める前に「このプロジェクトで使うテストコマンドと、その根拠ファイルを示してください」と依頼します。正しいファイル名とコマンドが出るか確認します。回答だけでは内部のすべてを証明できないため、ファイル表示と作業ログも併せて見ます。

本文の構成とテンプレートは編集部の例です。Claude Codeをこの例で起動した実測ログは掲載していません。手元で読み込みを確認してから、自分の環境へ適用してください。

読まれないときは、追記する前に置き場所を見る

作業場所が別のフォルダー、名前が違う、まだ参照していない下位フォルダーへ置いた、というケースでは、指示を強い口調へ変えても解決しません。起動した場所と、対象ファイルへの経路を確認します。

また、Claude CodeはAGENTS.mdを同じ仕組みで自動的に読むとは限りません。共通の説明を使う場合は、公式の対応に従ってCLAUDE.mdから@AGENTS.mdのように参照する方法があります。参照先が外部の場合の確認や、読み込まれる範囲にも注意してください。

使った後に、失敗した一件だけ反映する

作業ごとの長い履歴は、CLAUDE.mdへ全部足さず、別の記録に残します。同じ間違いが繰り返される場合に、判断できる短いルールとして追加します。指示は実行を導く材料であり、権限制御やテストの代わりではありません。

Codexと共通化したい場合はAGENTS.mdの置き方へ。繰り返す作業を手順としてまとめるならSKILL.mdの最小構成で、常時読むルールと必要時に読む手順を分けてみてください。