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

CLAUDE.mdに何を書くべきか|#2 設計論

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

    • Claude Codeに指示を出しても毎回違う結果が返ってくる

    • CLAUDE.mdを書いてみたが、書いた気がするだけで効果を感じられない

    • 同じミスを何度も繰り返させてしまう

    • チームで使っているが、人によって結果がバラバラ

    この記事を読むと「何をどう書けばClaude Codeが意図通りに動くか」が具体的にわかる。

    CLAUDE.mdはClaude Codeの「オリエンテーション資料」だ。

    新入社員を雇ったとき、会社のルール・使うツール・やってはいけないことを最初に伝えるように、Claude Codeにもプロジェクトの文脈を与える必要がある。それがCLAUDE.mdの役割だ。

    これを適切に設計できるかどうかで、Claude Codeの出力品質が大きく変わる。

    画像

    WHATルール:何を書くべきか

    CLAUDE.mdに書くべき内容は「Claude Codeが作業するために必要な情報」に絞る。

    書くべき4つのカテゴリ:

    1. 技術スタック

    使っている言語・フレームワーク・ライブラリを明示する。

    markdown

    ## 技術スタック
    - フロントエンド:Next.js 14(App Router)
    - バックエンド:Supabase
    - スタイリング:Tailwind CSS
    - 言語:TypeScript(strict mode)

    package.jsonを見れば自明な情報は書かなくていい。Claude Codeはファイルを読める。わざわざCLAUDE.mdに書いても冗長なだけだ。

    2. アーキテクチャの方針

    ディレクトリ構成の意図や、設計上の決定事項を書く。

    markdown

    ## アーキテクチャ
    - Server Componentsをデフォルトとする。Client Componentsは最小限に
    - APIルートは /app/api/ 配下に集約
    - DBアクセスはすべて /lib/supabase/ を経由すること

    3. ビルド・テストコマンド

    markdown

    ## コマンド
    - 開発:`npm run dev`
    - ビルド確認:`npm run build`
    - テスト:`npm run test`
    - 型チェック:`npm run typecheck`

    4. 禁止事項・制約

    Claude Codeが間違えやすいパターンを具体的に書く。

    markdown

    ## 禁止事項
    - `any` 型の使用禁止
    - console.logをコミットに含めない
    - 直接DBに書くな。必ずRLSポリシーを通すこと

    ポイント:具体的に書くほど遵守率が上がる。

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

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

    「コードをきれいに書いてください」ではなく「any型を使うな」と書く。これだけで遵守率が2倍以上変わる。

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

    4つのカテゴリは独立しているようで連動している。技術スタックがあるからアーキテクチャの判断ができる。アーキテクチャがあるから禁止事項が意味を持つ。コマンドがあるから検証まで自動でできる。

    今すぐできること:

    1. 自分のプロジェクトのCLAUDE.mdを開く

    2. 「コードをきれいに」のような曖昧なルールを探す

    3. 「any型の使用禁止」のように具体的な禁止事項に書き直す

    カスケード構造:4層のファイル設計

    CLAUDE.mdは1ファイルだけではない。4層構造で管理するのが正しい設計だ。

    ~/.claude/CLAUDE.md          # グローバル設定
    ./CLAUDE.md                  # プロジェクトルート
    ./CLAUDE.local.md            # 個人設定(.gitignore推奨)
    ./.claude/rules/*.md         # ディレクトリ別ルール

    層ごとの役割

    ① ~/.claude/CLAUDE.md(グローバル)

    自分のすべてのプロジェクトに適用したい設定を書く。50行以内が目安。

    markdown

    ## 共通ルール
    - コミットメッセージは日本語で書く
    - 作業前に必ずgit statusを確認する
    - 大きな変更の前にPlan Modeで計画を立てる

    ② ./CLAUDE.md(プロジェクトルート)

    プロジェクト固有のルール。チームで共有するのでGitで管理する。300行以内が目安。

    ③ ./CLAUDE.local.md(個人設定)

    自分だけの設定。APIキーのパス・ローカル環境の差異など。.gitignoreに追加してリポジトリに含めない。

    ④ ./.claude/rules/*.md(ディレクトリ別)

    特定のディレクトリにのみ適用したいルールを分割管理する。必要なときだけ読み込まれる。

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

    4層がどのように相互作用するか

    4層はフィルターのように重なる。Claude Codeがコードを書くとき、まずグローバルルールを読み、次にプロジェクトルール、さらに個人設定、最後に作業中のディレクトリのルールを重ねて適用する。

    つまり上の層ほど広く薄く、下の層ほど狭く深いルールを書く設計になる。

    • グローバル:「コミットメッセージは日本語」など全プロジェクト共通の習慣

    • プロジェクト:「DBアクセスは必ず/lib/supabase/を経由」などアーキテクチャ判断

    • 個人:「ローカルのAPIキーは.env.localにある」など環境差異

    • ディレクトリ別:「このAPIルートはJWT認証必須」などファイル単位の制約

    この構造があることで「なぜこのルールがあるのか」の文脈が自然に整理される。

    この章の実践アクション

    まず2層から始める。いきなり4層作る必要はない。

    ステップ1:グローバル設定を作る

    Claude Codeにこう伝える:

    ~/.claude/CLAUDE.md を作成して。
    内容は以下の共通ルールだけ書いてほしい。
    - コミットメッセージは日本語で書く
    - 作業前に必ずgit statusを確認する
    - 大きな変更の前にPlan Modeで計画を立てる

    全プロジェクト共通の習慣を3〜5個だけ書く。

    ステップ2:プロジェクト設定を作る

    Claude Codeにこう伝える:

    このプロジェクトのルートにCLAUDE.mdを作成して。
    技術スタック・アーキテクチャ方針・禁止事項を書いてほしい。
    内容は私が確認してから使うので、まず下書きを出して。

    出てきた下書きを確認・修正してから保存する。

    ディレクトリ別ルールはプロジェクトが大きくなってから必要に応じて追加する。

    適切な長さ

    全体で2,000トークン以内が推奨値だ。

    500行のTypeScriptファイルが約4,000トークンなので、CLAUDE.mdはその半分以下に収める感覚。

    長くなりすぎるとどうなるか。コンテキストを圧迫するだけでなく、ルールが埋もれて読まれなくなる(第6回のコンテキスト管理を参照)。

    長さとルールの優先度の関係

    「2,000トークン以内」という制約は単なる目安ではなく、重要なルールを際立たせるための設計原則だ。

    100個のルールが書いてあるCLAUDE.mdでは、Claude Codeが「何が最も重要か」を判断できない。20個に絞られたCLAUDE.mdでは、すべてのルールが等しく重要なものとして扱われる。

    つまり削ることがルールの優先度を上げる。

    この章の実践アクション

    今すぐできること:

    1. 現在のCLAUDE.mdのトークン数を確認する(文字数 ÷ 4 ≈ トークン数)

    2. 2,000トークンを超えていたら削除候補を探す

    3. 「package.jsonを見れば分かること」「READMEに書いてあること」は削除する

    運用方法:間違えたら追記する

    CLAUDE.mdは最初から完璧に書く必要はない。

    正しい運用サイクル:

    1. 最小限のCLAUDE.mdで開発を始める

    2. Claude Codeが同じ間違いを繰り返したら

    3. その禁止事項をCLAUDE.mdに追記する

    運用サイクルが品質を自動改善する仕組み

    このサイクルの核心は「間違いが発生するたびにCLAUDE.mdが賢くなる」点だ。

    最初は空に近いCLAUDE.mdでも、開発を続けるうちに「このプロジェクトで間違えやすいこと」が蓄積されていく。1ヶ月後には、そのプロジェクト専用の知識が詰まったCLAUDE.mdができあがっている。

    WHATルールで書いた「具体的な禁止事項」が、この運用サイクルで積み上がっていく。カスケード構造があるから、プロジェクト固有の知識とグローバルな習慣が混在しない。適切な長さの制約があるから、本当に重要なルールだけが残る。

    4つの章はすべてつながっている。

    この章の実践アクション

    今日から始められること:

    1. 開発セッションが終わったら「今日Claude Codeが間違えたこと」を1つ振り返る

    2. 同じ間違いが2回以上あったらCLAUDE.mdに追記する

    3. 週1回、CLAUDE.mdを見直して不要になったルールを削除する

    まとめ

    項目内容書くべきこと技術スタック・アーキテクチャ・コマンド・禁止事項書かなくていいことpackage.jsonで自明な情報具体的ルールの遵守率89%(曖昧なルールは35%)推奨トークン数2,000トークン以内グローバル設定50行以内プロジェクト設定300行以内運用の原則間違えるたびに追記・育てていくドキュメント

    実践:CLAUDE.mdチェッカーを使ってみる

    記事で学んだ内容を実際に手を動かして確認しよう。

    以下の手順でCLAUDE.mdの品質をその場でチェックできる。

    Claude chatに以下をそのまま貼り付ける:

    あなたはCLAUDE.mdのレビュアーです。
    私のCLAUDE.mdを以下の観点でチェックしてください。
    
    【チェック項目】
    1. 曖昧なルールがないか(「きれいに」「適切に」などの抽象表現)
       → あれば具体的な禁止事項に書き直す案を提示する
    2. package.jsonで自明な情報が含まれていないか
       → あれば削除候補として指摘する
    3. トークン数の概算(文字数 ÷ 4)が2,000を超えていないか
       → 超えていれば削除候補を提案する
    4. 4層のカスケード構造で分けるべき内容がないか
       → あれば振り分け案を提示する
    
    【私のCLAUDE.md】
    (ここに自分のCLAUDE.mdの内容を貼り付ける)

    このチェックを月1回やるだけで、CLAUDE.mdの品質が継続的に上がっていく。

    CLAUDE.md設計論を実施した際のフォルダ構成

    最小構成(まず2層から始める)

    ~/                                    # ホームディレクトリ
    └── .claude/
        └── CLAUDE.md                     # ① グローバル設定(50行以内)
                                          #   全プロジェクト共通の習慣を書く
    
    your-project/                         # プロジェクトルート
    └── CLAUDE.md                         # ② プロジェクト設定(300行以内)
                                          #   技術スタック・アーキテクチャ・禁止事項
    

    成長後の構成(大規模プロジェクト)

    ~/                                    # ホームディレクトリ
    └── .claude/
        └── CLAUDE.md                     # ① グローバル設定(50行以内)
                                          #   - コミットメッセージは日本語
                                          #   - 作業前にgit statusを確認
                                          #   - 大きな変更はPlan Modeで
    
    your-project/                         # プロジェクトルート
    ├── CLAUDE.md                         # ② プロジェクト設定(300行以内)
    │                                     #   - 技術スタック
    │                                     #   - アーキテクチャ方針
    │                                     #   - ビルド・テストコマンド
    │                                     #   - 禁止事項
    │
    ├── CLAUDE.local.md                   # ③ 個人設定(.gitignoreに追加)
    │                                     #   - ローカルのAPIキーのパス
    │                                     #   - 自分の環境固有の設定
    │
    ├── .gitignore
    │   └── CLAUDE.local.md を追加        # チームに共有しない
    │
    └── .claude/
        └── rules/                        # ④ ディレクトリ別ルール
            ├── frontend.md               #   /app 配下のルール
            │                             #   - Server Componentsをデフォルト
            │                             #   - Client Componentsは最小限に
            ├── api.md                    #   /app/api 配下のルール
            │                             #   - JWT認証必須
            │                             #   - エラーレスポンスの形式
            └── database.md              #   /lib/supabase 配下のルール
                                          #   - RLSポリシーを必ず通す
                                          #   - 直接DBに書かない
    

    各ファイルの中身のイメージ

    ① ~/.claude/CLAUDE.md(グローバル)

    ## 共通ルール
    - コミットメッセージは日本語で書く
    - 作業前に必ずgit statusを確認する
    - 3ファイル以上触るタスクはPlan Modeで計画を立てる
    - テストなしの実装禁止
    

    ② ./CLAUDE.md(プロジェクト)

    ## 技術スタック
    - フロントエンド:Next.js 14(App Router)
    - バックエンド:Supabase
    - 言語:TypeScript(strict mode)
    
    ## アーキテクチャ
    - Server Componentsをデフォルトとする
    - APIルートは /app/api/ 配下に集約
    - DBアクセスはすべて /lib/supabase/ を経由すること
    
    ## コマンド
    - 開発:npm run dev
    - ビルド確認:npm run build
    - 型チェック:npm run typecheck
    
    ## 禁止事項
    - any型の使用禁止
    - console.logをコミットに含めない
    - 直接DBに書くな。必ずRLSポリシーを通すこと
    

    ③ ./CLAUDE.local.md(個人設定)

    ## ローカル環境
    - .env.localにSupabaseのキーがある
    - ローカルDBのポートは54322
    

    ④ .claude/rules/database.md(ディレクトリ別)

    ## DBアクセスのルール
    - すべてのクエリはRLSポリシーを通すこと
    - トランザクションが必要な場合はsupabase.rpcを使う
    - N+1クエリ禁止
    

    優先度のイメージ

    広く・薄い
        ↑
        │  ~/.claude/CLAUDE.md        全プロジェクト共通の習慣
        │  ./CLAUDE.md                このプロジェクト固有のルール
        │  ./CLAUDE.local.md          自分の環境だけの設定
        │  .claude/rules/*.md         このディレクトリだけのルール
        ↓
    狭く・深い
    

    上の層ほど「いつでも・どこでも適用」 下の層ほど「このファイルを触るときだけ適用」

    追伸
    あなたの学びや挑戦の一歩を後押しできていたら幸いです。よければフォローやスキで応援してください。次の記事づくりの力になります。

    次回予告

    第3回は CLAUDE.mdの失敗パターン。

    設計論を知った上で「それでもやりがちなミス」を5つ解説する。Wikiダンプ・/initの罠・曖昧ルール・放置・1ファイル集約——それぞれの「なぜ失敗か」と「どう直すか」をセットで理解すると、この記事の設計論がより深く刺さる。

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

    あなたへのおすすめ