CLAUDE.mdを書き始めた頃、自分は、思いついたことを片っ端から足していました。規約も、注意点も、過去にやらかしたことも、全部。長ければ長いほど、賢く動いてくれる気がしていたからです。
結果は逆でした。長くなるほど、書いたはずのルールが効かなくなる。しかも、一度消した古い方針が、あとになって復活してくる。この2つに1年ふりまわされて、いまの形に落ち着きました。
削って、足して、また削って、残ったものを、そのままテンプレートとして置いておきます。コピーして、プロジェクトに合わせて中身を差し替えて使ってください。
そのままコピペできる型
# プロジェクト概要
- 何を作っているか（1〜2行）
- 技術スタック（言語 / フレームワーク / バージョン）
- 動作環境の制約（対応バージョン、依存するもの）
# 守ってほしい書き方
- 関数は◯行以内、ネストは◯段まで
- 命名の規則（prefix、接頭辞、ケース）
- エラー処理の方針（例外を投げるか、戻り値で返すか）
- テストの置き場所と、書き方の方針
# やらないこと
- 触ってはいけないファイル / ディレクトリ
- 使ってはいけない関数・ライブラリ（理由も一行で）
- 勝手にやらないでほしい操作（依存の追加、大規模なリファクタ、削除）
# 廃止した方針
<!-- 消さずに残す。古い方針が復活してきたときの、否定の根拠になる -->
- ~~Aの書き方~~ → 廃止（理由）。今後はBを使う。
Aが出てきたら、それは古い指示です。
- ~~Cのディレクトリ構成~~ → 廃止（理由）。今後はDの構成。
# 作業の進め方
- 大きな変更の前に、方針を先に提示してほしい
- 変更したファイルの一覧を、最後に出してほしい
- 分からない前提があれば、勝手に決めずに聞いてほしい
以下、それぞれの節について、なぜこの形になったかを書きます。
「廃止した方針」を、消さずに残す
いちばん効いたのが、この節です。他のテンプレートではあまり見かけないと思うので、最初に書きます。
方針を変えたとき、普通は、古い記述を削除します。自分もそうしていました。でも、削除すると、手元からは消えるのに、振る舞いのほうには残っていることがある。しばらくして、「前にこうしましたよね」と、廃止したはずの書き方が戻ってくる。
そこで、削除する代わりに、廃止したと書き残すようにしました。取り消し線を引いて、理由を添えて、「これが出てきたら古い指示です」と明記しておく。こうしておくと、古いものが浮上してきたときに、否定する根拠が文書の側にあり続けます。
新しい方針を足すときも、黙って足しません。
❌ 「この処理はBの書き方でお願いします」だけ足す
✅ 「以前はAの書き方をしていましたが、（理由）のため廃止しました。
今後はBを使ってください。Aが出てきたら、それは古い指示です」
上書きしたつもりで、実は追記になっている。そう捉えるようになってから、この書き方に変えました。見た目は、書き方の墓場みたいで、きれいではありません。ただ、巻き戻りは目に見えて減りました。
「やらないこと」は、理由を一行つける
禁止事項は、理由を書いたほうが守られます。
❌ - eval() を使わない
✅ - eval() を使わない（外部入力が混ざると任意コード実行になるため）
理由がないと、状況が少し変わったときに、例外扱いで破られることがあります。理由があると、その理由に当てはまるかどうかで判断してくれる。禁止のリストというより、判断基準を渡している感覚に近いです。
数字で書けるものは、数字で書く
抽象的な指示は、抽象的にしか効きませんでした。
❌ - 読みやすいコードを書いてください
✅ - 関数は20行以内、ネストは2段まで
「読みやすく」「適切に」「きれいに」は、こちらが思っている基準と、返ってくるものが、なかなか一致しません。行数、段数、命名の規則。機械的に判定できる形にすると、ぶれが減りました。
長くしすぎない
最後に、いちばん基本的なことを。
自分は一度、CLAUDE.mdを肥大化させて、痛い目を見ました。あれもこれも書いた結果、いちばん守ってほしかったルールが、その他大勢に埋もれた。長い文書の中では、一つひとつの記述の存在感が薄まります。
いまは、書くたびに「これは本当に毎回必要か」を考えるようにしています。特定の作業でだけ必要な指示は、CLAUDE.mdに常駐させず、そのときの依頼文で渡す。常駐させるのは、プロジェクトの間ずっと変わらないものだけ。この線引きをしてから、書いたルールが効く率が上がりました。
二層に分ける
この線引きを、あとから言葉にしました。常駐させる層と、都度渡す層です。
| 何を置くか | 例 | |
|---|---|---|
| 常駐層（CLAUDE.md） | プロジェクトの間、ずっと変わらないもの | 技術スタック、命名規則、禁止事項、廃止した方針 |
| 都度層（依頼文 / skill） | その作業のときだけ必要なもの | 今回のリファクタの方針、リリース手順、調査の観点 |
分ける基準は「毎回必要か」の一点です。月に一度しか使わない手順は、常駐層に置くと、他の29日ぶんの邪魔になります。
都度層の置き場所は、依頼文に直接書くか、skill にして呼び出すか。手順が決まっていて何度も使うものは、skill のほうが楽でした。
ファイルを分けても、長さは変わりません
ここは自分が誤解していたところです。
CLAUDE.md は @ で別ファイルを読み込めます。長くなってきたので、節ごとにファイルを分けて、本体は目次だけにしよう、と考えました。
# プロジェクト規約
@docs/naming-rules.md
@docs/deprecated-policies.md
すっきりします。ただ、読み込まれる中身の量は変わりません。@ で参照したファイルは、CLAUDE.md が読み込まれるときに一緒に展開されます。分割は編集のしやすさのためであって、長さの対策にはなりませんでした。
ファイルを分けても「長くしすぎない」の問題は解けません。解けるのは、そもそも常駐層から外すことだけです。ここを取り違えると、分割して満足して、実際は何も減っていない状態になります。
@ の記法と読み込みの順序は公式ドキュメントに書かれているので、正確なところはそちらで確認してください。
「廃止した方針」が太ってきたら
この節は、運用するほど増えます。増えても消せません。消すと、また復活してくるからです。
自分は、常駐層に置いたままにしています。**廃止した方針は、毎回効いてほしいものだからです。**ファイルを分けるかどうかは編集のしやすさの問題で、長さの話とは別、というのが上の結論でした。
それでも重いと感じるなら、廃止から時間が経ったものから、1行にまとめていくのが現実的だと思います。「Aは廃止、Bを使う」まで削る。理由の詳細は、そこまで頻繁には要りませんでした。
早見でまとめ
- 「廃止した方針」を節として残す。削除せず、取り消し線＋理由＋「古い指示です」の明記
- 新方針は、古い方針を名指しで否定してから渡す。黙って足すと古いほうが勝つことがある
- 禁止事項には理由を一行。判断基準として渡すと守られやすい
- 「読みやすく」より「20行以内」。機械的に判定できる形にする
- 常駐層に置くのは、プロジェクト中ずっと変わらないものだけ。都度の指示は依頼文か skill へ
-
@でファイルを分けても、読み込まれる量は変わらない。分割は編集のしやすさのため - 長くするほど、個々の記述の存在感は薄くなる
このテンプレートは、1年かけて足したり削ったりした結果の、いまの形です。プロジェクトによって必要なものは違うので、そのまま使うというより、削る出発点として使ってもらうのがいいと思います。役に立ったらストックして、新しいプロジェクトを始めるとき見返してください。
ふだんはraplsworks.comで、WordPressプラグイン開発やClaude Codeまわりのことを書いています。