本文へ移動
BenriWorks LabBenriWorks トップ

ガイド更新日

CLAUDE.mdで、同じ説明を繰り返さない

この記事で分かること

Claude Code 集中講座の第9回。毎回伝えている検査コマンドや作業の約束をCLAUDE.mdに移します。短い規約の作り方と、自動メモリとの役割の違いを整理します。

規約のファイルを開いた画面の前で、こちらを向いている女性の開発者
目次 読みたいところから

「変更したら、このコマンドで検査して」。次の作業でも、同じ一文をまた入力している。毎回必要な約束には、依頼文とは別の置き場所を用意できます。

CLAUDE.mdは、プロジェクトの作業方針を書いておくファイルです。まずは実際に使う検査コマンドを置き、Claude自身が書き留める自動メモリとの違いも整理します。

覚える仕組みは2つある

Claude Code には性質の違う仕組みが2つあり、どちらもセッションの最初に読み込まれます。

CLAUDE.md自動メモリ
誰が書くかあなたClaude
何が入るか指示と規則学んだことと傾向
範囲プロジェクト、個人、組織リポジトリごと
何に使うか規約、手順、構成あなたの好み、訂正した内容

大事な前提が1つあります。公式ドキュメントは、どちらも文脈であって、強制される設定ではないと書いています。Claude はこれらを読んで従おうとしますが、必ず守られるとは限りません。

必ず実行されてほしいものは、第13回で扱うフックとして書きます。ここを取り違えると、「書いたのに守られない」に延々と悩むことになります。

CLAUDE.md がいつ、どの順で読まれるか

読まれる場所は4つあり、広い範囲から順に連結されます。

範囲場所共有先
組織のポリシーWindows なら C:\Program Files\ClaudeCode\CLAUDE.md組織の全員
個人~/.claude/CLAUDE.md自分の全プロジェクト
プロジェクト./CLAUDE.md または ./.claude/CLAUDE.mdチーム(リポジトリ経由)
ローカル./CLAUDE.local.md自分だけ(.gitignore に入れる)

上書きではなく連結です。ファイルシステムの根から作業フォルダに向かって並ぶので、起動した場所に近い指示ほどあとに読まれます。各フォルダの中では、CLAUDE.local.md が CLAUDE.md のあとに置かれます。

下位のフォルダにあるファイルは、起動時ではなく、Claude がそのフォルダのファイルを読み書きしたときに読み込まれます。

CLAUDE.mdが読まれる順序を示した図。組織のポリシー、個人、プロジェクト、ローカルの順に積み上がり、下にあるものほどあとに連結されることと、自動メモリが別の系統としてセッションに入ることが示されている
上書きではなく連結。近いものほどあとに来る

書いたのに効いていないと感じたら、置き場所とファイル名が上の表のとおりかを先に見てください。ファイルの中身を疑うより、そもそも読まれる場所に置けているかを確かめるほうが速く終わります。ターミナル版では /context all を実行すると、起動時に読み込まれた CLAUDE.md と CLAUDE.local.md が「Memory files」の欄に並びます。BenriWorks がデスクトップアプリで試したかぎり、この一覧は出ませんでした。

何を書くか

4つに絞ると迷いません。ビルドとテストの通し方、コードの規約、ディレクトリの構成、そして「常にこうする」という決まりごとです。

書き方には条件があります。公式ドキュメントが挙げている基準は具体性で、次のように対比されています。

  • 「コードを整形する」ではなく「インデントは半角スペース2つ」
  • 「変更をテストする」ではなく「コミット前に npm test を走らせる」
  • 「ファイルを整理する」ではなく「APIのハンドラは src/api/handlers/ に置く」

確かめられる形になっているかが判定の基準です。確かめられない規則は、守られたかどうかも分かりません。

長さの目安も示されています。1ファイルあたり200行未満です。長くなるほど文脈を食い、遵守の度合いが下がると書かれています。

実例として、このブログのファイル

BenriWorks のブログのリポジトリでは、検査の通し方をコマンドのまま並べています。

## 検証コマンド
npm run validate:content && npm run check:links
(加えて npm run typecheck / npm run lint / npm run test)

そして、不明点の扱い方を決めています。

不明な事実を推測で補完しない。
不明点は本文に {/* TODO: 要確認 — ... */} として残し、PRで報告する。

実際に一番働いているのが、この2行目です。分からないことを分からないまま書く形式を先に決めておくと、埋めるために推測する動機がなくなります。この講座の各回の冒頭にある注記も、ここから出ています。

書かないほうがよいこと

一般論は効きません。「読みやすいコードを書くこと」のような文は、書いても書かなくても結果が変わりませんでした。

更新が要る事実も、置き場所として向きません。バージョン番号や依存の一覧を書くと、直し忘れたときに古い情報が規約として効き続けます。そういうものは、実際の設定ファイルを読ませるほうが確実です。

矛盾も問題になります。公式ドキュメントは、2つの規則が食い違っていると、Claude がどちらかを恣意的に選ぶことがあると書いています。上位のフォルダの CLAUDE.md と下位のものが違うことを言っていないか、ときどき見直してください。

場所によって規則を変える

大きなリポジトリでは、場所によって規則が変わります。フロントエンドとバックエンドで書き方が揃わないのは、むしろ自然です。

.claude/rules/ に話題ごとのファイルを置くと、規則を分割できます。さらに、前書きに paths を書くと、該当するファイルを扱うときだけ読み込まれます。

---
paths:
  - "src/api/**/*.ts"
---

# API の規則

- すべてのエンドポイントで入力の検証を行う
- エラー応答は共通の形式を使う

paths のないファイルは常に読み込まれます。常に効かせたいものと、その場所でだけ効かせたいものを分けるための仕組みです。個人用の規則は ~/.claude/rules/ に置けば、全プロジェクトに効きます。

AGENTS.md をすでに持っている場合

別のコーディングエージェントを併用していると、AGENTS.md がすでにあるはずです。

作業フォルダとその上の階層に CLAUDE.md も CLAUDE.local.md もなければ、Claude Code は AGENTS.md をそのまま読みます(v2.1.277 以降)。どちらかが1つでもあると、読まれるのは CLAUDE.md の側だけです。両方を使いたいときに公式ドキュメントが勧めているのは、取り込みの1行を書いた CLAUDE.md を作る方法です。

@AGENTS.md

## Claude Code

`src/billing/` 以下の変更ではプランモードを使う。

取り込んだ内容が先に読まれ、そのあとに Claude 固有の指示が続きます。1つの内容を2か所に書かずに済みます。

シンボリックリンクでも同じことができますが、Windows では管理者権限か開発者モードが要るので、この取り込みの形のほうが確実です。

自動メモリは、Claude が自分で書く

もう1つの系統です。

公式ドキュメントによれば、Claude は作業しながら4種類のメモを自分のために保存します。あなたの役割と好み、あなたが与えた訂正、コードや履歴からは分からない進行中の事情、そして情報の在りかです。

保存しないものも決まっています。コードベースから分かること(構成、ファイルの場所、修正の内容)と、CLAUDE.md にすでに書いてあることは飛ばされます。あなたが書いたものと重複しないように作られています。

保存先は ~/.claude/projects/<プロジェクト>/memory/ で、索引の MEMORY.md と話題ごとのファイルに分かれます。セッションの最初に読み込まれるのは索引の先頭200行(または25KB)までで、話題ごとのファイルは必要になったときに読まれます。

画面に「Saved 2 memories」「Recalled 2 memories」と出たときが、その読み書きが起きた瞬間です。

自動メモリとの付き合い方

3つだけ押さえておけば足ります。

中身は読めます。 /memory から開けます。ただのマークダウンなので、書き換えも削除もできます。

機械ごとに別です。 同じリポジトリの作業ツリーどうしでは共有されますが、別のパソコンや、クラウドのセッションには引き継がれません。

切れます。 /memory の切り替えか、プロジェクトの設定で autoMemoryEnabled を false にします。

自動メモリは便利ですが、チームに共有したい内容を置く場所ではありません。「この判断はこうする」とチームで決めたことは、CLAUDE.md に書いてコミットしてください。自動メモリに入ったままだと、書いた本人の機械の中にしか存在しません。

育て方

足すタイミングを決めておくと楽になります。公式ドキュメントが挙げている目安は、Claude が同じ間違いを2回したとき、レビューで指摘されたことが Claude も知っておくべき内容だったとき、前のセッションと同じ訂正を打ったとき、そして新しい人にも同じ説明が要りそうなときです。

BenriWorks では、ここに「事故が起きたとき」を足しています。触ってはいけないファイルを触られた、入れてはいけない情報が入った。そういうときは、原因を直すのと一緒に規約へ1行足します。

どれも、思いついたときではなく、必要が証明されたときに足すという点が共通しています。先回りして書いた規則は、たいてい守られません。

規約の最初の数行

いま使っている検査コマンドと、どの作業でも守ってほしい約束を1つずつ選び、CLAUDE.mdの下書きにします。プロジェクトで実際に通る内容だけを書いてください。

次の依頼でその内容を読み、検査結果も確かめます。ファイルを置くことと、書いた約束が守られたかを確かめることは、どちらも必要です。

次の回

記事の公開など、その作業のときだけ使う長い手順は、必要なときに開ける形へまとめます。「Claude Codeのスキルで、いつもの手順を呼び出す」へ進めます。

参照した公式情報

  • Anthropic「How Claude remembers your project」(code.claude.com/docs、2026年11月時点)
  • 引用した規約は BenriWorks のブログリポジトリで実際に運用しているもの

READ NEXT

次はこれを読む

Claude Code 集中講座の次の回へ

Claude Codeのスキルで、いつもの手順を呼び出す

Claude Code 集中講座の第10回。記事の公開など、特定の作業で繰り返す手順をスキルにまとめます。SKILL.mdと説明文を書き、必要なときに呼び出す仕組みを学びます。

続きを読む →
手順書のファイルを手に持ち、こちらを向いて立っている男性

よくある質問

CLAUDE.md はどこに置きますか
チームで共有するならリポジトリの `./CLAUDE.md` か `./.claude/CLAUDE.md` です。自分だけの好みは `~/.claude/CLAUDE.md`、そのプロジェクトでの個人的な設定は `./CLAUDE.local.md` に置き、`.gitignore` に入れます。上の階層から順に連結され、作業フォルダに近いものがあとに来ます。
AGENTS.md をすでに使っています
作業フォルダとその上の階層に CLAUDE.md も CLAUDE.local.md もなければ、Claude Code は AGENTS.md をそのまま読みます。両方を使いたいなら、公式ドキュメントは `@AGENTS.md` の1行を書いた CLAUDE.md を作って取り込むことを勧めています。その下に Claude 固有の指示を足すこともできます。Windows ではシンボリックリンクに管理者権限が要るため、この取り込みの形が確実です。
書いたのに守られないことがあります
公式ドキュメントは、CLAUDE.md がシステムプロンプトの一部ではなく、そのあとに続く利用者のメッセージとして届くと説明しています。読んで従おうとしますが、厳密な遵守は保証されません。必ず実行されてほしいものは、第13回で扱うフックとして書いてください。