/init で CLAUDE.md を作ったあと、中身をほとんど触っていないプロジェクトがあります。
足したほうがよさそうなことは何となく分かるのに、何を書けばいいのかが決まらないまま日が過ぎていました。
この記事は、書く対象を同じ指摘の2回目に絞ったうえで、どこに置き、いつ直すかまでを、自分の運用から手順の形にしたものです。
忙しい人のための要約
書き戻しを1つのループとして回すだけなら、この3点で足ります。
- 書き戻すきっかけは同じ指摘を2回目にしたとき。1回目はその場で直すだけにする
- 置き場所は長さと手順の有無で決まる。1〜2行で済むものは CLAUDE.md、手順がぶら下がるものはスキルへ回す
- 足すだけだと古い記述が残って食い違うので、書き足すついでに周辺を直すところまでが1ループ
CLAUDE.md が放置される理由
/init で生成した直後の CLAUDE.md には、プロジェクトの構成やよく使うコマンドが並んでいます。
書いてあるのは、いまのプロジェクトの説明です。
そこから何を足すかは、書かれていません。
更新が止まるのもそこが理由です。
意識が足りないからというより、書き戻すきっかけが決まっていないからだと考えています。
気づいたら書く、という決め方をすると、気づく瞬間そのものが定義されないままになります。
そのため、書き足す候補が毎日のセッションに転がっていても、拾う基準がないまま通り過ぎていきます。
では何なら書く対象になるのか。
自分がファイルに移しているのは、同じことを2回言ったところだけです。
もう一度同じことを口で説明していると気づいた時点で、ようやく書く対象になります。
書き戻すタイミングは2つある
きっかけを決めるといっても、作業中ずっと身構えている必要はありません。
きっかけ自体は「2回目」の1つですが、それを拾う場面は2つに分かれます。
その場で書くときと、あとでまとめて見直すときです。
その場で書く: 同じ指摘を2回目にしたとき
回数で決めています。
1回目はその場で直すだけにして、ファイルには手を付けません。
1回きりの指摘は、そのときだけの事情だったり、こちらの言い方が足りなかっただけだったりするからです。
先回りしてルールにすると、次から意味を持たない決めごとが1行増えます。
対して、書くのは2回目。
さっきも同じことを言ったな、と気づいたなら、その指摘はすでに再発しています。
テストと確認をどのコマンドで走らせるかを2回言い直したなら、それは書いておけば二度と言わずに済む種類の指摘です。
再発したものだけを書けば、CLAUDE.md に載るのは自分が繰り返し必要としたルールに絞られます。
セッション末にまとめて棚卸しする
もうひとつは、作業がひと段落したタイミングです。
セッションの終わりに、今日のやり取りで書き戻す候補がないかを見てもらうことがよくあります。
その日に何を2回言ったかをまだ覚えているうちに拾えるのが、このタイミングの利点です。
ただし毎回ではありません。
自動で走らせる固定の仕組みも作っておらず、会話の流れの中で口頭で頼んでいるだけです。
CLAUDE.md 行きとスキル行きの分かれ目
書くきっかけが来たら、次に決まるのは置き場所です。
Claude Code には CLAUDE.md のほかにスキル（SKILL.md）という置き場があります。
決まった作業の手順や判断基準をひとまとまりの説明書にしておき、必要な場面でだけ読み込ませる仕組みです。
物差しは2つだけ
振り分けは次の2つで足りています。
- 1〜2行で済む禁止事項や前提は CLAUDE.md に書く
- 手順や判断基準がぶら下がるものはスキルへ回す
長さを見るのは、CLAUDE.md が毎回読まれる前提のファイルだからです。
手順書をそのまま置くと、全セッションで読まれる場所を1つの作業の説明が占めることになります。
手順の有無を見るのは、読ませたいタイミングが違うからです。
1行の前提は毎回効かせたいのに対し、手順はその作業をする場面でだけ読めば足ります。
こういうときはこうする、が2段3段と続くものは、書き出した時点で1行には戻りません。
逆に、1行で済む決めごとをスキルへ切り出すと、呼び出す手間のほうが大きくなります。
3つの書き戻しを振り分ける
実際に書き戻した3つを、この物差しで並べるとこうなります。
| 書き戻した内容 | 置き場所 | 物差し |
|---|---|---|
| テスト・確認コマンドの指定 | CLAUDE.md | コマンド名の1行で足りる |
| コードの書き方 | CLAUDE.md | 前提として短く書ける |
| Issue 着手から PR 作成までの流れ | スキル | 手順が数段階に分かれる |
3つ目だけ、途中で置き場所が変わりました。
はじめは CLAUDE.md に書いていて、手順が伸びてきた時点でスキルへ移しました。
置き場所はあとから移せるので、最初の判断で悩みすぎる必要はないと考えています。
振り分けをもっと細かく決めたい場合は、別の記事で書きました。
棚卸しは候補を出させてから選ぶ
セッション末の棚卸しに話を戻すと、頼み方にもコツがあります。
棚卸しを頼むときに、いきなり CLAUDE.md を書き換えさせることはしません。
候補を出させてから、採るものを自分で選びます。
そのまま書き換えさせると増えるのは、自分が2回言ったかどうかとは関係のない、それらしいルールです。
しかも増えた分は次のセッションから毎回読まれるので、あとで消すほうが手間になります。
たとえばこう頼むと、候補の形で返ってきます。
今日のセッションで、私が2回以上同じ指摘をした箇所はありますか。
CLAUDE.md に書き戻す候補として挙げてください。書き換えはまだしないでください。
効果があるのは、書き換えを止める一文です。
これがあると、採否を決める前の提案として返ってきます。
そこから採るのは1つか2つで、残りは今回だけの話として落とします。
選ぶ作業が自分の側に残っている限り、増えるのは自分が2回言ったものだけで、CLAUDE.md は毎回読ませても惜しくない量に収まります。
足すだけでは壊れる
書き戻す運用が回り始めると、CLAUDE.md の記述は当然ながら増えていきます。
そこで起きるのが、古い記述が残ったまま新しい記述と食い違う状態です。
厄介なのは、食い違っていても手元では何も起きない点です。
エラーも警告も出ません。
書いた本人は、食い違いに気づかないまま次の作業へ移ります。
自分の場合、その食い違いにはAI に指摘されて気づきました。
挙動がおかしくなって発覚したわけでも、読み返していて見つけたわけでもありません。
なので、書き足すときに、その場所だけを見ないようにしています。
1回の書き戻しは、足して終わりではありません。
1ループでやることは次の2つで、書き足すのはその前半にすぎません。
- 2回目になった指摘を書き足す
- 書き足した周辺の古い記述を読み直し、食い違っていればその場で直す
ここまでは食い違い、つまり中身の質の話でした。
記述が増える量そのものが問題になる場合は、コンテキストを消費する分を .claude/rules/ に移す手があります。
手順を持たないルール文だけを別ファイルに切り出しておく置き場で、手順や判断基準がぶら下がるスキルとはそこが違います。
こちらは以前にまとめました。
まとめ
同じ指摘を2回目にした時点で書き、長さと手順の有無で置き場所を決め、古い記述を直すところまでを1ループにする。
この3つを決めてから、CLAUDE.md が作ったきりのファイルではなくなりました。
食い違いに自分では気づけなかった身としては、足すだけの運用に戻す気になれません。
CLAUDE.md への書き戻しを含めて、Claude Code でアプリを1本作りきる流れは、9月8日発売の書籍にまとめました。
4.3 で CLAUDE.md に書き込むところを扱い、8章ではこのループをアプリ1本分通して体験できます。
Xをフォローいただけると嬉しいです！
AI駆動開発（特に Claude Code）のノウハウや Tips をよく発信しています！