2026-09-04 · claudecode · ai · claude · 個人開発
CLAUDE.md に何を書くと効いて、何を書いても効かないのか
CLAUDE.md に「きれいなコードを書いてください」と書いても、何も変わりません。
3ヶ月で個人アプリを10本作る過程で、CLAUDE.md を何度も書き直しました。
効いたものと効かなかったものがはっきり分かれたので、その線引きを書きます。
効かないもの
形容詞で指示する
- きれいなコードを書く
- 保守性の高い設計にする
- 適切にエラーハンドリングする
- パフォーマンスを意識する
これらは全部効きません。 「きれい」も「適切」も判定できないからです。 判定できない指示は、守っているかどうかを自分でも確認できません。
そして書いた本人も、あとで「守られているか」を確かめられません。 確かめられないルールは、無いのと同じです。
一般的なベストプラクティスを書く
- DRY 原則を守る
- 単一責任の原則に従う
- マジックナンバーを使わない
モデルはこれらを既に知っています。書いても情報が増えません。
CLAUDE.md の役割は、モデルが知らないこと（このプロジェクト固有の事情）を伝えることです。
コードを読めば分かることを書く
- 状態管理には Zustand を使っています
- テストは Vitest です
package.json を見れば分かります。書くなら「なぜそれを選んだか」「何をしてはいけないか」
のほうです。
- 状態管理は Zustand。Redux への移行は検討済みだが、
ボイラープレートが増えるため見送った。提案しなくてよい
これは書く価値があります。同じ提案を毎回されなくなります。
効くもの
禁止を、判定できる形で書く
- 純黒 `#000000` と純白 `#ffffff` を使わない
- グラデーション背景・グラデーション見出し文字を使わない
- 1画面でモーションは3種類まで
grep '#000000' で確認できます。判定できるので、守られているかを機械で検査できます。
UI の造形そのものは、本来 CLAUDE.md ではなく UI 仕様書で決めるべきものです。
ここに書くのは仕様書に落とす前の最低ライン、つまり仕様書が無い場面でも
踏み外してほしくない下限として扱っています。造形の判断を実装役にさせない、
という原則は変わりません。
「きれいなUIにする」は効かず、「純黒を使わない」は効く。この差は モデルの理解力ではなく、指示が判定可能かどうかです。
権限を落とす
一番効いたのはこれでした。
- 担当している Issue の Scope に書かれたパス以外を変更しない
- Scope 外の変更が必要になったら、実装を止めて報告する
- main へのマージは Reviewer だけが行う
「〜する」より「〜できない」のほうが効きます。 やってよいことを増やす指示は解釈の幅が広く、禁止は狭いからです。
特に「実装を止めて報告する」の一文が効きました。これが無いと、 制約にぶつかったときモデルは何とかして進もうとします。 出口を用意しておくと、そこに逃げてくれます。
例外を明示する
禁止を書くと、必ず「これは例外では」というケースが出ます。先に書いておきます。
Scope 外として扱わないもの:
- ロックファイルの、依存追加に伴う自動更新
- 変更したファイルに対応するテストファイル
書いておかないと、毎回判断がぶれます。ぶれる判断は、ルールを形骸化させます。
順序と依存を書く
- UI を含む Issue は、UI 仕様書が status:done になるまで着手しない
- 並列着手グループ内の Coder は、1メッセージ内で同時に起動する
2つ目は実際に効きました。呼び出しを分けると直列になるので、 明示しておかないと並列になりません。
表を使う
状態やラベルの一覧は、箇条書きより表のほうが参照されやすい印象があります。
| ラベル | 意味 | 付与するタイミング |
|---|---|---|
| `status:planned` | Issue 作成済み、未着手 | Architect が Issue 作成時 |
| `status:review` | PR 作成済み、レビュー待ち | Coder が PR 作成時 |
「いつ付けるか」まで書くのが重要です。意味だけ書くと付け忘れます （結局これは GitHub Actions に寄せましたが、それは別の話です）。
長さについて
短いほうが効きます。
一度 74KB まで膨らんだ CLAUDE.md を書いたことがありますが、後半ほど守られなく
なりました。 検証したわけではないので断言はしませんが、体感として明確でした。
いま使っているものは 7KB 前後です。内訳はこうです。
| 部分 | 割合 |
|---|---|
| 役割ごとの権限（何ができて、何ができないか） | 4割 |
| 全体の流れ（誰が何を受け取って誰に渡すか） | 3割 |
| 状態管理（ラベルと、その付与タイミング） | 2割 |
| 例外の明示 | 1割 |
一般論は1行も入っていません。
膨らんだ原因は「念のため書いておく」でした。念のための行は、判定できない指示に なりがちです。判定できない指示は効かないので、書くだけ薄まります。
検証のしかた
書いたルールが効いているかは、破られたときに気づけるかで判断します。
- Scope 違反 →
gh pr diff --name-onlyで分かる - 色の直書き →
grepで分かる - ラベルの付け忘れ → Issue 一覧を見れば分かる
- 「きれいなコード」 → 分からない
最後だけ検証手段がありません。だから効きません。 書く前に「これが破られたとき、自分は気づけるか」を考えると、 効かない行を書かずに済みます。
まとめ
- 形容詞で指示しない。判定できない指示は効かない
- 一般的なベストプラクティスは書かない。モデルは既に知っている
- コードを読めば分かることは書かない。書くなら「なぜ」と「何をしないか」
- 禁止を、機械で検査できる形で書く
- 「〜する」より「〜できない」。そして必ず逃げ道（止めて報告する）を用意する
- 例外を先に明示する。ぶれる判断はルールを形骸化させる
- 短くする。「念のため」の行は効かない行になりやすい
- 書く前に「破られたら気づけるか」を確かめる
この考え方で書いた CLAUDE.md と、4人格ぶんのサブエージェント定義を MIT で公開しています。
関連する記事
- Claude Code に5人格を分担させて並列開発する — 人格を分ける全体像
- AI が作った画面が「AIっぽい」のを直す — 造形を実装役に決めさせない
Claude Code に設計・実装・レビューを別々の人格として分担させ、GitHub Issue と
ブランチを軸に並列開発を回すための設定一式を MIT で公開しています。
コピーして ./setup.sh を叩けば動きます。技術スタックには依存しません。
https://github.com/quintetkit/quartet
このワークフローだけで実際にツールを 1 つ作りました。Issue の分割から PR、 レビュー、マージまで記録が全部残っています。うまくいかなかった箇所も消していません。
https://github.com/quintetkit/mdlinkcheck
UI 設計人格・レビュー基準・Issue 単位の並列実行スクリプト・実践ガイド 10 章を 足したものは製品ページにあります。