📋 記事サマリー
Claude CodeやCodexを使い続けていると、CLAUDE.mdやAGENTS.mdがいつの間にか数百行の「何でも帳」に巨大化してしまう問題。筆者の白井暁彦氏（AICU Japan）は、これらの指示書を大幅に棚卸しした結果、AIコーディングの精度が劇的に向上したと報告しています。331ブックマークを集めた注目の実践記事です。
⚠️ 巨大化の原因：指示書が「作業日報」に化ける
最初は数十行だった指示書が、注意事項の追加、作業手順の書き足し、引き継ぎ事項の記録、過去のトラブル対応によって膨張。結果として：
- 古い進捗、完了済みタスク、特定プロジェクト限定ルールが毎回読み込まれる
- 重要な指示がノイズに埋もれる
- 禁止事項や「トラウマの塊」になり、ネガティブワードばかりの状態に悪化
核心の気づき
情報をたくさん渡せばAIが賢くなる、は間違い。長い指示書は重要な指示を埋もれさせ、逆効果になる。
情報をたくさん渡せばAIが賢くなる、は間違い。長い指示書は重要な指示を埋もれさせ、逆効果になる。
🔧 棚卸しの4つの原則
1. 静的な指示書に「現在地」を書かない
進捗や引き継ぎ（「この設定は完了」「次は認証機能を実装」等）は、数日後には状況が変わって陳腐化します。これらはIssue・タスク管理ツール・handoffファイルに分離すべき。
ルール：静的ファイルには「いま何をしているか」ではなく、「このリポジトリでは今後も何を守るべきか」を書く。
2. グローバル設定には全プロジェクト共通ルールのみ
特定サイトのURL規則、特定DBの構造などをグローバルに書くと、無関係プロジェクトでも毎回読み込まれる無駄が発生。これは「料理のたびに家中の取扱説明書を台所に持ち込むようなもの」。
- プロジェクト固有ルール → 各リポジトリのCLAUDE.md/AGENTS.mdへ
- グローバルには → コミット方針、危険操作の禁止、共通コーディング方針のみ
3. 残すべきは「説明」ではなく「踏むと壊れる罠」
短ければよいわけではない。残す価値が高いのは、コードを読んだだけでは分からず、間違えると実害が出る情報：
- 特定の値の組み合わせで無限リダイレクトが発生する
- ある配列が常に存在する前提だと本番環境だけで落ちる
- マイグレーションを自動実行してはいけない
- メールアドレスではなく認証基盤の不変IDを突合キーに使う
これらは「過去の事故から得た地雷原の地図」。マインスイーパーにとって不可欠な情報。
削除候補：ディレクトリ構成、package.jsonを読めば分かること、一般的なフレームワークの使い方、コードで強制済みの命名規則。
判断基準は「この文章がなくてもAIはコードやテストから正しい結論に到達できるか」。到達できるなら消す。
判断基準は「この文章がなくてもAIはコードやテストから正しい結論に到達できるか」。到達できるなら消す。
4. AI自身に棚卸しさせる
削る前に、Claude Codeに「CLAUDE.mdとAGENTS.mdを新しい世代のモデルに向けて適切にしてみよう」と提案すると、いろいろ削ってくれる。確認しながら実施するのがコツ。また /doctor コマンドも活用。
💡 ポイントまとめ
- CLAUDE.md/AGENTS.mdの巨大化はAIの精度を下げる（情報の埋没）
- 進捗・引き継ぎ情報は別システムに分離（Issue、handoff、ログ）
- グローバル設定には全プロジェクト共通ルールのみ残す
- 残すべきは「地雷情報（罠）」だけで、説明や命名規則は削除候補
- 「ポジティブワード」で書く（「〜するなら〜がいい」形式）
- AI自身に棚卸しを提案すると効果的