メインコンテンツへスキップ
見出し画像

やりがちなCLAUDE.mdの失敗パターン|#3

    この記事を読むとどんな悩みが解決するか

    • CLAUDE.mdを書いたのに、Claude Codeの挙動が全然変わらない

    • /init で自動生成したものをそのまま使っているが問題ないか不安

    • 書けば書くほど効果が薄くなっている気がする

    • チームのCLAUDE.mdが膨らみ続けていてどう整理すればいいか分からない

    この記事を読むと「なぜ効果が出ないのか」の原因が特定でき、今すぐ直せる。

    画像

    第2回でCLAUDE.mdの設計論を学んでも、実際に書くと陥りやすいミスがある。5つの失敗パターンはそれぞれ独立した問題ではなく、1つを直すと別の問題も連鎖して解決していく構造になっている。


    失敗パターン1:Wikiダンプ

    症状:プロジェクトに関するあらゆる情報をCLAUDE.mdに詰め込む。

    ## プロジェクト概要
    このプロジェクトは2024年4月に開始した、ECサイトのリニューアル案件です。
    クライアントはXX株式会社で、月間PVは約100万、ユーザー数は...(以下延々と続く)
    
    ## 使用技術
    Node.jsはv20.x系を使用しています。npmはv10以上が必要です。
    TypeScriptのバージョンは5.3で、tsconfig.jsonのtargetはES2022に...
    

    なぜ失敗か:

    Claude Codeはファイルを読める。package.json・tsconfig.json・README.mdを直接参照できるので、そこに書いてある情報をCLAUDE.mdに転記しても意味がない。

    むしろ害がある。CLAUDE.mdが長くなるとコンテキストを圧迫し、本当に重要なルールが埋もれる。2,000トークンという推奨上限(第2回参照)はこのためにある。

    直し方:

    「Claude Codeがファイルを読めば自明にわかること」は全部削除する。CLAUDE.mdに残すのは、ファイルを読んでも分からない判断基準・方針・禁止事項だけだ。

    この章の相互作用と実践アクション

    Wikiダンプを直すと、必然的に「何が本当に重要か」を選別することになる。この選別の作業が、次のパターン2(/initの罠)とパターン3(曖昧なルール)を直すきっかけになる。不要な情報を削ったあとに残るのが「本当に書くべき内容」だからだ。

    今すぐできること:

    Claude Codeにこう伝える:

    CLAUDE.mdを開いて、package.json・tsconfig.json・README.mdを読めば
    分かる情報をすべてリストアップして。削除候補として提示してほしい。
    

    提示されたリストを確認して、不要な情報を削除する。


    失敗パターン2:/initの自動生成をそのまま使う

    症状:/init を実行して生成されたCLAUDE.mdをそのまま使い続ける。

    /init が生成するCLAUDE.mdの典型例:

    # Project Overview
    This is a Next.js project using TypeScript and Tailwind CSS.
    
    ## Tech Stack
    - Next.js 14.2.0
    - React 18.3.0
    - TypeScript 5.3.3
    - Tailwind CSS 3.4.0
    
    ## Scripts
    - `npm run dev`: Start development server
    - `npm run build`: Build for production
    - `npm run test`: Run tests
    

    なぜ失敗か:

    package.jsonを見れば全部わかる情報しか書かれていない。Claude Codeにとって新しい情報がゼロだ。コンテキストを消費するだけで、挙動改善には何も貢献しない。

    これはパターン1(Wikiダンプ)の自動生成版だ。手動で詰め込むか、ツールに詰め込ませるかの違いだけで、問題の本質は同じ。

    直し方:

    /init はあくまでファイルを生成するだけのコマンドだと理解する。生成後に内容を確認して、自明な情報はすべて削除する。残すのは自分が意図的に書き加えた内容だけ。

    最終的にCLAUDE.mdがほぼ空になっても構わない。「書くことがない=プロジェクトの制約が少ない」ということで、それは正常な状態だ。

    この章の相互作用と実践アクション

    パターン1でWikiダンプを削除した後、/initの自動生成も削除すると、CLAUDE.mdにはほぼ何も残らない。それが正しいスタート地点だ。

    空になったCLAUDE.mdに、次のパターン3で学ぶ「具体的なルール」を自分の手で書き加えていく。削除と追加のサイクルが、精度の高いCLAUDE.mdを育てる。

    今すぐできること:

    Claude Codeにこう伝える:

    CLAUDE.md を確認して、/init で自動生成されたと思われる内容
    (バージョン番号・スクリプト一覧・プロジェクト概要)を
    すべて削除候補としてリストアップして。
    

    失敗パターン3:曖昧なルールを書く

    症状:良かれと思って抽象的なルールを書く。

    ## コーディング規約
    - コードはきれいに書いてください
    - 適切なエラーハンドリングを心がけてください
    - パフォーマンスに配慮してください
    

    なぜ失敗か:

    「きれいに」「適切に」「配慮して」は判断基準がない。Claude Codeは確率的に動くシステムで、曖昧な指示は解釈がブレる。

    数字で見ると明確だ。

    • 具体的なルール → 遵守率 89%

    • 曖昧なルール → 遵守率 35%

    同じルールでも書き方次第で遵守率が2倍以上変わる。

    直し方:

    抽象的なルールを具体的な禁止事項・条件に書き直す。

    ## 禁止事項
    - `any` 型の使用禁止(`unknown` を使うこと)
    - try-catchなしの非同期処理禁止
    - レンダリングごとに新しいオブジェクトを生成する書き方禁止
    

    「何をしてはいけないか」を具体的に書くのが最も効果的だ。

    この章の相互作用と実践アクション

    パターン1・2で不要な情報を削除し、ここで初めて「何を書くべきか」の答えが見えてくる。削って残ったスペースに、具体的な禁止事項を書き加える。

    この「削る→具体的に書く」の流れが、第2回のWHATルール(89%遵守)を実現する実践的な手順だ。

    また、ここで書いた具体的な禁止事項は次のパターン4(更新しない)と直結する。禁止事項は一度書いて終わりではなく、Claude Codeが間違えるたびに追加していくものだ。

    今すぐできること:

    現在のCLAUDE.mdを開いて、「きれいに」「適切に」「心がけて」などの抽象表現を探す。

    Claude Codeにこう伝える:

    CLAUDE.mdの中で曖昧な表現(「きれいに」「適切に」「配慮して」など)を
    すべて見つけて、具体的な禁止事項に書き直す案を提示して。
    

    失敗パターン4:一度書いたら更新しない

    症状:最初にCLAUDE.mdを書いて、そのまま放置する。

    なぜ失敗か:

    Claude Codeが同じミスを繰り返しているのに、CLAUDE.mdに追記しないのは機会損失だ。同じ指摘を毎回プロンプトで伝えるのは非効率で、セッションをまたいだら引き継がれない。

    直し方:

    「また同じミスをした」と感じた瞬間がCLAUDE.mdに追記するタイミングだ。

    運用サイクルはシンプル:

    Claude Codeが間違えた
        ↓
    なぜ間違えたかを考える
        ↓
    CLAUDE.mdに具体的な禁止事項を追記
        ↓
    同じミスが減る
    

    CLAUDE.mdは完成させるものではなく、育てていくドキュメントだ。

    この章の相互作用と実践アクション

    パターン3で「具体的に書く」習慣ができると、このサイクルが自然に回り始める。「また同じミスをした → 禁止事項に追記する」という反射が身につく。

    ただし追記し続けると今度はパターン5(1ファイルに集約)に陥る。追記するたびに「これはプロジェクト全体のルールか、特定のディレクトリだけのルールか」を意識する習慣をセットで持つと良い。

    今すぐできること:

    開発セッション終了時にClaude Codeにこう伝える:

    今日のセッションで私が修正を指示した箇所を振り返って、
    CLAUDE.mdに追記すべき禁止事項を提案して。
    

    失敗パターン5:すべてをルートのCLAUDE.mdに書く

    症状:プロジェクトが大きくなっても、CLAUDE.mdが1ファイルのまま膨らんでいく。

    なぜ失敗か:

    フロントエンドのルールもバックエンドのルールもDBのルールも全部混在すると、どのルールがどの文脈で適用されるか不明確になる。Claude Codeが参照するコンテキストも不必要に大きくなる。

    直し方:

    第2回で解説したカスケード構造を使う。特定のディレクトリにしか適用しないルールは .claude/rules/ に分割する。

    .claude/rules/
    ├── frontend.md    # /app 配下のルール
    ├── api.md         # /app/api 配下のルール
    └── database.md    # /lib/supabase 配下のルール
    

    ルートの CLAUDE.md はプロジェクト全体に適用する最小限のルールだけ残す。

    この章の相互作用と実践アクション

    5つのパターンの集大成がここだ。パターン1〜4を通じて「削る・具体化・更新する」を繰り返すと、CLAUDE.mdが肥大化してくる。その肥大化を防ぐ仕組みがカスケード構造だ。

    「このルールはどのディレクトリにだけ適用したいか」という問いが、自然とCLAUDE.mdを分割する動機になる。分割することで2,000トークンの上限も守りやすくなる。

    今すぐできること:

    Claude Codeにこう伝える:

    現在のCLAUDE.mdを確認して、特定のディレクトリ(フロントエンド・API・DBなど)
    にしか適用しないルールを見つけて。
    .claude/rules/ に分割する案を提示してほしい。
    

    まとめ

    ▼ Wikiダンプ
    問題:コンテキスト圧迫・重要ルールが埋もれる
    対処:自明な情報をすべて削除する
    ▼ /init そのまま使用
    問題:有用な情報ゼロ
    対処:生成後に中身を精査・削除する
    ▼ 曖昧なルール
    問題:遵守率35%に低下
    対処:具体的な禁止事項に書き直す
    ▼ 更新しない
    問題:同じミスが繰り返される
    対処:間違えるたびに追記する
    ▼ 1ファイルに集約
    問題:肥大化・文脈が混在
    対処:カスケード構造で分割する


    実践1:CLAUDE.md一括診断プロンプト

    5つの失敗パターンをまとめて診断できる。Claude chatに以下をそのまま貼り付ける:

    あなたはCLAUDE.mdの診断医です。
    以下の5つの失敗パターンをチェックして、問題点と修正案を提示してください。
    
    【チェック項目】
    1. Wikiダンプ:package.json・README等を読めば分かる情報が含まれていないか
       → あれば削除候補をリストアップ
    2. /init の残骸:自動生成されたと思われる情報が残っていないか
       → あれば削除候補をリストアップ
    3. 曖昧なルール:「きれいに」「適切に」などの抽象表現がないか
       → あれば具体的な禁止事項に書き直す案を提示
    4. 追記できていないルール:よくある間違いで追記すべき内容がありそうか
       → プロジェクトの内容から推測して提案
    5. 1ファイル集約:ディレクトリ別に分割すべきルールがないか
       → あれば .claude/rules/ への振り分け案を提示
    
    【私のCLAUDE.md】
    (ここに内容を貼り付ける)
    

    実践2:失敗パターンをすべて直した後のフォルダ構成

    your-project/
    ├── CLAUDE.md                   # プロジェクト全体のルール(2,000トークン以内)
    │                               # ・アーキテクチャ方針
    │                               # ・プロジェクト全体の禁止事項
    │                               # ・ビルド・テストコマンド
    │
    ├── CLAUDE.local.md             # 個人設定(.gitignoreに追加)
    │                               は# ・ローカル環境の差異
    │                               # ・個人のAPIキーパス
    │
    └── .claude/
        └── rules/
            ├── frontend.md         # /app 配下のルール
            │                       # ・Server Components優先
            │                       # ・Client Componentsの制約
            ├── api.md              # /app/api 配下のルール
            │                       # ・認証チェック必須
            │                       # ・エラーレスポンスの形式
            └── database.md         # /lib/supabase 配下のルール
                                    # ・RLSポリシーを必ず通す
                                    # ・直接DBに書かない
    
    ~/
    └── .claude/
        └── CLAUDE.md               # グローバル設定(50行以内)
                                    # ・全プロジェクト共通の習慣
                                    # ・コミットメッセージのルール
    

    ビフォー・アフターの違い:

    【Before】
    CLAUDE.md(500行・Wikiダンプ+/init残骸+曖昧ルール混在)
    
    【After】
    CLAUDE.md(50行・具体的なルールのみ)
    .claude/rules/frontend.md(20行)
    .claude/rules/api.md(15行)
    .claude/rules/database.md(15行)
    合計100行・すべて具体的・役割が明確
    

    次回予告

    第4回は Plan Mode開発手法(80/20ルール)。

    タスクの80%でPlan Modeを使うべき理由、Read-onlyモードの活用法、「計画→実行」の正しいフローを解説する。CLAUDE.mdを正しく設計した上でPlan Modeを使うと、「計画フェーズでCLAUDE.mdのルールを前提にした設計」ができるようになる。2つの回がセットで機能する理由がここにある。


     
     
    Claude Codeで0からデプロイ・保守運用まで 必要な知識を発信中。 最新の開発手法の扱い方なども詳しく解説していきます。

    あなたへのおすすめ