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