同じ指摘を、何度もしていませんか。
前回、依頼を「目的・制約・確認方法」の型にすることを覚えました。これで1回の依頼の質は上がります。ただし、そこには落とし穴が残っています。今日気づいたことは、今日のセッションが終わると消えるという落とし穴です。
新しいセッションを開くたびに、同じ前提を説明し直していないでしょうか。先週指摘したのと同じ言い回しの誤りを、今週もまた指摘していないでしょうか。これが起きているなら、原因は覚える気がないことではありません。学びを持ち越す場所を持っていないことです。
その場所が、CLAUDE.mdです。
CLAUDE.mdとは何か
CLAUDE.mdは、書けば必ずそのとおりに動く設定ではありません。
プロジェクトの直下などに置く1つのテキストファイルです。セッションが始まるたびに全文が読み込まれ、Claudeの手元に文脈として残ります。書くのは人間です。何を大事にしているか、何を避けてほしいかを、ここに積み上げていきます。
置き場所は1つではありません。用途に応じて5階層があります。
複数に分かれていても、1つにまとめ直す必要はありません。@path/to/fileという書き方で他のファイルを呼び込めるので、階層を分けたまま必要な部分だけをつなぎ合わせられます。
大事な性質が1つあります。これは強制ではなく、お願いだということです。
“Claude treats CLAUDE.md files and auto memory as context, not enforced configuration.”
筆者訳ClaudeはCLAUDE.mdやauto memoryを、強制される設定としてではなく、文脈として扱う。
書いたことが必ずそのまま実行される保証はありません。読んで、判断の材料にするというのがCLAUDE.mdの立ち位置です。この性質は、後の節で効いてきます。
間違いを見たら書き足す
間違いに気づいたら、その場でCLAUDE.mdに書き足す。これがClaude Code作者本人の習慣です。
“Anytime we see Claude do something incorrectly we add it to the CLAUDE.md”
筆者訳Claudeが何か間違ったことをするたびに、それをCLAUDE.mdに書き足している。
チームは実際に、CLAUDE.mdを週に何度も更新しているそうです。一度書いて終わりの設定ファイルではなく、間違いの記録が積み重なっていく育児日記に近いものだと考えると分かりやすくなります。
習慣として型にすると、こうなります。
気づく
前回の「見る」の中で、同じ種類の誤りに気づく
1行にする
個別の指摘ではなく、繰り返し使える一般的なルールの形に直す
書き足す
CLAUDE.mdの該当する場所に追記する
効いているか確認する
次のセッションで同じ誤りが減っているか、実際に見る
多くの職場にある「ヒヤリハット」報告に似た構造です。個人の記憶だけに留めず、次に同じことが起きないよう手順書に反映する文化は、すでにあります。それをそのままCLAUDE.mdに持ち込むだけです。
お願いと強制の違い
CLAUDE.mdが「お願い」である以上、絶対に破られては困ることまでここだけに任せるのは危ういです。機密情報を書かない、破壊的な操作を実行しないといったルールがそれに当たります。
そうした「必ず守らせたいこと」のために、決定的に実行される仕組みがあります。Hooksです。特定のタイミングで、Claudeの判断を介さずシェルコマンドが強制実行されます。
読んで判断に反映する。柔軟で書きやすい。ただし、破られることがある。
判断を介さず、決められた通りに実行される。絶対に守らせたいルール向き。
日常的な好みはCLAUDE.md、命に関わる線引きはHooks、と役割を分けておくと、後で痛い目を見にくくなります。
肥大化を防ぐ仕分け
CLAUDE.mdは育てるほど良いわけではありません。全文が毎回読み込まれる以上、育ちすぎると、大事なルールが些末な手順の中に埋もれてしまいます。
書き足す前に、行ごとに問うべきテストがあります。
“For each line, ask: 'Would removing this cause Claude to make mistakes?' If not, cut it. Bloated CLAUDE.md files cause Claude to ignore your actual instructions!”
筆者訳各行について、この行を消したらClaudeが間違えるようになるかを問う。ならなければ削る。CLAUDE.mdが肥大化すると、Claudeは本当に守ってほしい指示のほうを無視するようになる。
この基準を行ごとに当てはめると、CLAUDE.mdに書くべきものとそうでないものが分かれます。
- Claudeが推測できないBashコマンド
- 標準と違うコードスタイル
- テストの回し方
- リポジトリ独自の作法
- アーキテクチャ上の判断
- 環境の癖
- 非自明な落とし穴
- 読めば分かること
- 標準的な言語の慣習
- 詳細なAPI文書
- 頻繁に変わる情報
- 長い説明
- 自明な作法
仕分けの軸は、その内容がいつ必要かです。
Skillsは、必要になったときだけ本文が読み込まれる仕組みです。毎回のセッションで抱える荷物と、必要なときだけ取り出す道具箱を分ける、と考えると整理しやすくなります。
よくある罠
注意
CLAUDE.mdで崩れやすい3点
個人の好みを詰め込みすぎる。誰も全文を読み切れないほど長くなると、かえって守られなくなります。
書けば絶対に守られると過信する。お願いであることを忘れると、破られたときに驚くことになります。
チーム共有のCLAUDE.mdに個人的な癖を書く。共有する範囲と、自分だけの設定を分けずに混ぜてしまう失敗です。
こうしてCLAUDE.mdが育つと、同じ間違いを二度指摘しなくて済むようになります。ですが、まだ根本的な問題は残っています。あなたはまだ、成果物のほぼ全部を自分の目で見ています。次回、この段最大の山に取り組みます。
今日のまとめ
- CLAUDE.mdは「お願い」であって「強制」ではない。絶対に守らせたいことはHooksに任せる
- 間違いに気づいたら、その場で終わらせず1行にして書き足す
- 常時のルールはCLAUDE.md、場面の手順はSkillsに仕分けると肥大化を防げる
明日のアクション
直近1週間で、同じ指摘を2回以上した経験を思い出してください。
それを一般化できる1行にして、CLAUDE.mdに書き足してください。思い当たらなければ、次にその種の間違いが起きた瞬間に書き足すと決めてください。
次のセッションを開いたとき、その1行が実際に効いているかを確認するところまでがこの演習です。