CLAUDE.mdを育てる — AIコラボレーション設定ファイルの3ヶ月の変遷

#CLAUDE.mdとは

Claude Codeを起動すると、最初にプロジェクトルートの CLAUDE.md を読み込む。ここに書かれた内容がセッション全体の「前提知識」になる。技術スタック、コーディング規約、フォルダ構造、やってはいけないこと——プロジェクトの文脈をAIに伝えるための設定ファイルだ。

一言で言えば「AIへの取扱説明書」。人間の新メンバーにオンボーディング資料を渡すのと同じ発想で、AIにもプロジェクト固有の知識を渡す。

このポートフォリオサイト（211個のインタラクティブコンポーネントを持つ）で、3ヶ月間 CLAUDE.md を更新し続けた。323コミットを経て、何が効いて何が効かなかったかが見えてきた。この記事はその変遷の記録だ。

#初期（2026年1月頃）: 技術スタック列挙期

最初に書いた CLAUDE.md は、技術スタックの羅列だった。

- Framework: TanStack Start (React 19)
- Styling: Tailwind CSS v4
- Animation: Motion (motion/react)
- Package Manager: bun
- Linter: Biome

コマンドも丁寧に書いた。bun run dev で開発サーバーが起動する、bun run build でビルドできる、bun run check で lint が走る。

これはほとんど効果がなかった。

理由は単純で、AIは package.json と tsconfig.json を読めば技術スタックを把握できる。.ts ファイルが並んでいれば TypeScript だと分かるし、tailwind.config があれば Tailwind を使っていると分かる。「TypeScript を使え」と書かなくても、AIはプロジェクトの構成を見て判断する。

当たり前のことを書いても、コンテキストウィンドウを消費するだけだ。CLAUDE.md に書くべきは「ファイルを見ただけでは分からないこと」だった。

ただし、1つだけ例外があった。Biome のフォーマット設定（single quotes, 2 spaces, 100 width, semicolons asNeeded）は明示的に書く価値があった。これは biome.json を読めば分かるが、AIが毎回設定ファイルを確認しに行く手間を省ける。頻繁に参照される情報はインライン化する価値がある。

#中期（2026年2月）: ワークフロールール期

1月の反省を踏まえて、2月は「AIが間違えやすいポイント」に焦点を移した。

#プロジェクト固有の罠

このプロジェクトには、ファイルを見ただけでは分からない「罠」がいくつかある。

• Vite プラグインの順序: cloudflare は tanstackStart より前に配置しないとビルドが壊れる
• motion のインポートパス: framer-motion ではなく motion/react を使う（パッケージ名が変わった）
• ServerFn 不使用: Cloudflare Pages の既知バグで動かない。全データは静的 TypeScript 定数
• routeTree.gen.ts: TanStack Router が自動生成する。編集してはいけない

これらは「知らなければ確実に踏む地雷」だ。特に Vite プラグインの順序は、エラーメッセージからは原因が推測しにくい。CLAUDE.md に書くことで、AIが地雷を踏む前に回避できるようになった。

#ワークフローの定義

同時期に、takt ワークフローも定義した。タスクの規模に応じて作業フローを自動選択させるテーブルだ。

判断基準を表形式で明示したことで、AIが「まず計画を立てるべきか、すぐ実装すべきか」を自律的に判断できるようになった。曖昧な指示よりも、条件分岐のテーブルのほうがAIには伝わりやすい。

#ルール膨張の問題

しかし、2月後半にはルールが増えすぎた。git のコミットメッセージ規約、フォルダ構造の詳細説明、Canvas と DOM の使い分け基準、物理エンジンの設計方針……。CLAUDE.md が数百行に膨れ上がり、「読むだけでコンテキストを消費する」問題が顕在化した。

AIのコンテキストウィンドウは有限だ。CLAUDE.md が長すぎると、肝心のタスクに使えるコンテキストが減る。ルールの量と精度のトレードオフに直面した。

#現在（2026年3月）: 判断基準とフォールバック期

3月に入り、CLAUDE.md の方針を大きく変えた。「何をすべきか」のルールを減らし、「どう判断すべきか」のメタルールに集中した。

#メタルール: 判断の判断基準

現在の CLAUDE.md で最も効いているのは、以下のようなメタルールだ。

• 「同じ問題で2回失敗 → /clear」: コンテキストが汚染されたと判断し、セッションをリセットする
• 「先にバリデーション手段を与える → 品質2-3倍」: テストや期待出力を最初に渡すことで、AIの自己修正ループを回す
• 「1セッション1タスク」: コンテキストは最も希少なリソースだから、詰め込まない
• 「効かないルールはまず削除を試みる」: ルール自体の棚卸しをメタルールとして定義

これらは「具体的な行動」ではなく「判断のフレームワーク」だ。AIは状況に応じてこれらの基準を適用する。具体的なルール100個よりも、判断基準10個のほうが効く。

#フォールバックの明示

もう1つの変化は、フォールバックの明示だ。

判断に迷ったら quick-fix を選ぶ（最低限のレビューを保証）

このたった1行が、AIの「フリーズ」を防ぐ。判断基準に該当しないエッジケースに遭遇したとき、AIが安全な方向にフォールバックできる。デフォルト値を定義するのと同じ発想だ。

#効いたルール Top 5

3ヶ月の運用で、特に効果が高かったルールを5つ挙げる。

#1. Viteプラグイン順序

tailwindcss → tsConfigPaths → cloudflare → tanstackStart → react
Cloudflare は TanStack Start より前に配置すること。

これが最も「書いてよかった」ルールだ。プラグイン順序のバグは、エラーメッセージから原因を特定するのが極めて難しい。AIがこの罠を踏むと、原因調査だけで数十ターンを消費する。1行の注意書きでそれを完全に防げる。

#2. motion のインポートパス

motion のインポートは motion/react（framer-motion ではない）

Framer Motion が Motion にリブランドされた際にインポートパスが変わった。ネット上の情報はまだ framer-motion が多いため、AIは古い情報に引きずられやすい。明示することで、毎回正しいパスを使うようになった。

#3. routeTree.gen.ts は自動生成

src/routeTree.gen.ts は自動生成。編集しない・コミットしない

AIはファイルの存在を見つけると、それを「編集可能なファイル」と認識してしまうことがある。自動生成ファイルを明示的にマークすることで、誤編集を防げた。

#4. ServerFn 不使用

ServerFn 不使用: CF Pages の既知バグ回避。全データは src/data/ の静的 TypeScript 定数

TanStack Startは ServerFn（サーバー関数）を標準機能として持つ。AIは新機能追加時にこれを使おうとするが、Cloudflare Pagesではまだ動かない。「使わない」ことと「その理由」をセットで書くことで、AIが別のアプローチを自律的に選べるようになった。理由なしの禁止ルールは無視されやすい。

#5. takt ワークフロー自動選択表

条件分岐のテーブルは、自然言語よりも正確にAIに伝わる。「大きな変更のときは計画を立ててから実装して」よりも、条件と選択肢のマトリクスのほうが、AIにとっては解釈の余地が少ない。

#効かなかったルール Top 3

逆に、書いても効果がなかったルールも記録しておく。

#1. 「コードにコメントを書く」

AIは明示的に「この関数にコメントを書いて」と指示しない限り、自発的にコメントを書かない。CLAUDE.md に「適切なコメントを残す」と書いても、ほぼ無視された。これは CLAUDE.md が「助言的」であることの典型例だ。

#2. 「エラーハンドリングを必ず入れる」

抽象的すぎて機能しなかった。「エラーハンドリング」が指す範囲が広すぎて、AIはどの程度の防御コードを書くべきか判断できない。実際、結局 200コンポーネントの一括修正で AudioContext のエラーハンドリングを後から追加する羽目になった。

代わりに効いたのは具体的なパターンの提示だ。「new AudioContext() は try-catch で囲み、失敗時は音なしで動作を継続する」のように、具体的なコードパターンまで落とし込むと従ってくれる。

#3. 「テストを書いてからコードを書く」

TDD をワークフローとして CLAUDE.md に書いたが、AIは「テストを書いて」と明示的に言わない限り、テストを先に書くことはなかった。ワークフローの順序制御は CLAUDE.md だけでは難しい。

これを解決するには、takt のようなワークフロー定義と組み合わせて「plan フェーズでテスト項目を列挙 → implement フェーズでテストを先に書く」と明確にステップを定義する必要がある。

#「助言的」vs「決定論的」

3ヶ月の運用で最も重要な学びは、CLAUDE.md は助言であって強制ではないということだ。

hooks は決定論的、CLAUDE.md は助言的

この一文が現在の CLAUDE.md に書かれている。

• CLAUDE.md = 助言。AIが文脈に応じて判断し、従うかどうかを決める
• pre-commit hooks = 決定論的。条件を満たさなければコミットが物理的にできない

例えば「Biome の lint を通す」ことを本当に守らせたいなら、CLAUDE.md に書くだけでは不十分だ。pre-commit hook で bun run check を走らせれば、lint エラーがあるコードは絶対にコミットされない。

この区分けが明確になってから、CLAUDE.md に書く内容が変わった。

• 本当に守らせたいルール → hooks に書く（決定論的に強制）
• できればこうしてほしいこと → CLAUDE.md に書く（助言として提示）
• 判断基準 → CLAUDE.md に書く（AIの自律判断を支援）

CLAUDE.md に「絶対に」「必ず」と書いても、それは助言の強調でしかない。強制力が必要なら仕組みで担保する。

#ユーザーレベル vs プロジェクトレベル

CLAUDE.md には2つの階層がある。

#~/.claude/CLAUDE.md（ユーザーレベル）

全プロジェクトで共通のルールを書く場所。自分の場合は:

• npx ではなく bunx を優先
• 設計原則（DB設計に集中投資、疎結合モジュール設計）
• ワークフローの共通ルール（2回失敗 → /clear、1セッション1タスク）
• AI活用の Tips（バリデーション手段を先に与える）

これらはプロジェクトに関係なく適用したいルールだ。

#プロジェクト/CLAUDE.md（プロジェクトレベル）

このリポジトリ固有の情報を書く場所:

• Tech Stack の詳細（TanStack Start v1.x, Tailwind CSS v4）
• アーキテクチャ判断（Canvas vs DOM の使い分け、ServerFn 不使用の理由）
• Vite プラグイン順序
• フォルダ構造

#分離の効果

最初はプロジェクトの CLAUDE.md に全てを詰め込んでいた。ユーザーレベルの設定を分離したことで、プロジェクトの CLAUDE.md はプロジェクト固有の情報に集中できるようになった。

また、新しいプロジェクトを始めたときに、ユーザーレベルのルールが自動的に適用される。「bunx を使え」と毎回書く必要がなくなった。

#定量的な変化

CLAUDE.md の改善前後で、体感できた変化を記録しておく。

• Vite ビルドエラーの調査時間: 以前はプラグイン順序の問題で5-10ターン消費 → 注意書き追加後はゼロ
• motion インポートの修正回数: 以前は新コンポーネント作成時に約30%の確率で framer-motion を使用 → 明示後はゼロ
• takt ワークフローの適用率: テーブル形式にしてから、適切なワークフローが選択される確率が体感で大幅に向上

定量データとしては精密ではないが、「書いた瞬間から効果がゼロかイチか」が分かるのが CLAUDE.md の特徴だ。効くルールは書いた瞬間から100%効く。効かないルールは何回書き直しても効かない。

#まとめ: CLAUDE.md は育てるもの

3ヶ月間 CLAUDE.md を更新し続けて分かったことをまとめる。

CLAUDE.md は最初から完璧にはならない。 プロジェクトの進行とともに、AIが踏む地雷が見えてきて、それを防ぐルールが増えていく。逆に、効かないルールは削除していく。

効くルールの共通点:

• 具体的（「エラーハンドリングを入れる」ではなく「AudioContext は try-catch で囲む」）
• 判断基準を含む（条件分岐のテーブル、フォールバックの定義）
• ファイルを見ただけでは分からない情報（プラグイン順序、非推奨APIの代替）

効かないルールの共通点:

• 抽象的（「適切なコメントを書く」「エラーハンドリングを必ず入れる」）
• ファイルを見れば分かること（「TypeScript を使う」「React を使う」）
• 強制力が必要なこと（本当に守らせたいなら hooks で強制する）

定期的な棚卸しが必要だ。 CLAUDE.md はコードと同じで、メンテナンスしないと腐る。使われていないルール、効果のないルール、古くなった情報は積極的に削除する。「効かないルールはまず削除を試みる」——このメタルール自体が、3ヶ月の運用から生まれた最も重要な教訓かもしれない。

CLAUDE.md はAIとの協業の「契約書」ではない。育てていく「関係性の記録」だ。