Claude Codeを育てる - Part 3：説得編

Part 2 では強制（permissions.deny での禁止 + Hooks での自動化）の話を書いた。 ただ、強制で扱えるのはコマンド文字列で機械判定できる事項だけ。 コード上の判断や設計方針 — 「変更前にレビュー観点を提示する」「過剰設計を避ける」「禁止系には代替案も書く」など — は機械判定できないので、ここからは説得 = CLAUDE.md の領域になる。

今回は CLAUDE.md は何を書くか / 書かないか / どの粒度で書くか。

■ CLAUDE.md は最小から始める

CLAUDE.md は毎ターン会話に注入される。 長くするとトークン浪費 + 注意散漫が起きる。

目安：

👉 最初は50行以下、200行を超えたら分離検討

長いCLAUDE.mdは：

• 後ろのほうのルールがClaude側で漏れる
• トークンが毎ターン積み上がる
• 矛盾するルールが混入する

「とりあえず全部書いておく」は逆効果。インシデントが出たら追加するスタイルが正解。

■ CLAUDE.md に書くこと

書いていいもの：

• ロール定義 — パートナー / 執事 / レビュアー 等の1つに固定
• 判断軸 — KISS優先、過剰抽象化を避ける、エラーは握り潰さない、等
• プロジェクト固有の前提 — 言語、フレームワーク、デプロイ先、テストランナー
• 慣習との差 — このプロジェクトの異常な部分（標準と違う方法を採っている理由）

特に「慣習との差」は重要。Claudeは標準的なコーディングパターンを学習しているので、プロジェクト独自の理由で違うやり方をしている場合、明記しないと標準に戻される。

■ CLAUDE.md に書かないこと

書かないほうがいいもの：

• コードを読めば分かること — ディレクトリ構成、命名規則、import順
• 長い手順 — Skills に逃がす
• イベント駆動の処理 — Hooks に逃がす
• 状態 — 進捗、TODO、誰が何をやっている → git/issue tracker
• 過去のインシデント説明 — 結論だけ書く。経緯は git log や PR description に

「書いておけば安心」は罠。読まれないルールは無いのと同じ。

■ ルールは「判断できる粒度」で書く

ダメな例：

良いコードを書くこと
セキュリティに気をつけること

→ Claudeが判断できない。「良い」も「気をつける」も主観。

OKな例：

- 認証/認可コード（auth/, middleware/auth*）を編集する前に、
  変更点と影響範囲を提示してユーザー確認を取る
- 依存追加（package.json, requirements.txt, go.mod）は
  理由を述べてから実行
- DBスキーマ変更（migrations/）はロールバック手順とセットで提示

二つの原則：

• 「何を見て判断するか」をファイルパスやパターンで指定する
• 「禁止」だけでなく「代わりにこうする」をセットで書く

■ 「禁止だけ」がClaudeを詰まらせる

これは強く言いたい。

- try/except で例外を握り潰さない

→ じゃあどうすればいい？ Claudeが手詰まりで止まる。

書き直し：

- try/except で例外を握り潰さない。
  catchが必要な場合は、ログに出力 + 再raise、
  または上位に意味のある型で投げ直す。

「禁止 + 代替」のセットでようやくClaudeは動ける。 禁止だけ書くと「動かないか、無視するか」のどちらかになる。

■ ロール定義は1つに固定

CLAUDE.md に「執事 / 先生 / パートナー / レビュアー」を全部書くと、Claudeはそれを平均化して「中途半端なパートナー」になる。

メインエージェントは1つに固定する。 明確に違う動きをさせたいなら Subagent に分離（Part 4で扱う）。

例：

# 役割

あなたは単なる実装作業者ではなく、
設計・保守性・安全性を考慮する開発パートナーです。

不明確、危険、保守性を損なう変更は、実装前に懸念点を述べてください。
ただし過剰設計は避け、KISS原則を優先してください。

これくらいシンプルでいい。

■ 今回のまとめ

CLAUDE.mdは説得の場。守るかどうかはClaude次第。だから：

• 50行以下から始める
• 「コードを読めば分かること」は書かない
• ルールは判断できる粒度で
• 「禁止 + 代替」のセットで書く
• ロールは1つに固定

書いた瞬間からClaudeが100%守ってくれる、と思わない。 説得には限界があるから強制（禁止 + 自動化）で補完するし、強制では機械判定できない領域があるから説得が必要。両輪。

次回 Part 4 は拡張編。Skills と Subagents の使いどころと書き方。