メインコンテンツへスキップ

あらためてCLAUDE.mdについて

    ある程度AIツールを使っていくと「いつもこのプロンプト入力してるな」「毎回この指示を出すのは面倒だな」と思ったことがあると思います。
    そういったものについてはなるべく設定ファイルにその指示を書き込み、手間を減らすことをお勧めします。
    あるいはそういったファイルの存在は知っていて、書いた方が良いとはわかっているものの、具体的にどこに何をどう書けば良いのかわからず、そのまま使っている方もいるかもしれません。
    そういった方向けにClaude、ClaudeCodeを使っている方向けに設定ファイル、CLAUDE.mdについて公式サイトの内容を改めて読み込み、まとめてみました。

    スコープ

    まず、スコープとしては以下の3つあります。
    ・Managed(IT管理・組織全体)
    ・User(個人・全プロジェクト共通)
    ・Project(プロジェクト・チーム共有)
    それぞれにどういったファイルが置かれるか、置くべきかを更に説明します。
    Managedは正直なところ私も今回の記事を作成するにあたり初めて知ったものでして、IT管理者がMDM(Intune・Group Policyなど)を使って組織展開するときに使うものだそうです。今回はManagedについては割愛させてください。

    Userスコープ(個人・全プロジェクト共通)

    場所は以下。
    ~/.claude/
    ファイルは以下になります。
    CLAUDE.md :個人のグローバル指示
    settings.json :グローバル設定
    rules/*.md :個人ルール
    どのプロジェクトで作業していても毎セッション読み込まれる個人のデフォルト指示。コードスタイルの好みや個人ツールのショートカットなど。
    本記事ではCLAUDE.mdに着目します。
    rules/*.mdについてもまた別途記事を書きたいと思います。

    Projectスコープ(プロジェクト・チーム共有)

    場所は各プロジェクトのフォルダ直下となります。Claude Codeを実行している場所ですね。
    ファイルは以下の通りです。
    ・CLAUDE.md: プロジェクト指示(Git管理・チーム共有)
    ・CLAUDE.local.md: 個人用プロジェクト指示(.gitignore推奨)

    あとは.claudeフォルダ配下に置く場合もありまして、これも同じくプロジェクトスコープとなります。
    プロジェクトの規約、ビルドコマンド、アーキテクチャ方針など、チームで共有したい指示を書くメインファイル。Gitで管理することでチーム全員に適用されます。

    いつ追記するか

    いつ追記するかですが、公式の推奨としては
    ・Claudeが同じミスを2回繰り返したとき
    ・コードレビューで、Claudeが知っておくべきだった指摘があったとき
    ・先週と同じ説明をチャットに打ち込んでいると気づいたとき
    ・新しいチームメンバーが生産的になるために必要な情報があるとき

    CLAUDE.local.md(個人用プロジェクト指示

    )
    置き場所:<project>/CLAUDE.local.md(.gitignoreに追加推奨)
    このCLAUDE.local.mdは初めて見る方もいらっしゃるかもしれません。同じプロジェクトで自分だけに適用したい指示を書く場所。用途例は「自分のサンドボックスURL」「好みのテストデータ」など、チームには共有しない個人的な設定。
    そのため、Gitには上げずに.gitignoreに設定することをお勧めします。
    CLAUDE.mdと同様に扱われ、同じディレクトリの `CLAUDE.md` の後に結合されます。つまり、こちらが優先されます。

    書き方のポイント(公式ドキュメントより)

    ・サイズ:1ファイルあたり200行以内を目標に。 長いほどコンテキストを消費し、指示の遵守率が下がる
    ・構造: Markdownの見出しと箇条書きで関連する指示をグループ化する
    ・具体性: 検証できる粒度で書く
    「2スペースインデントを使う」
    「コードを適切にフォーマットする」
    矛盾するルールが複数あるとClaudeが任意で選択する。定期的に見直して古いルールを削除する

    ヒント:`/init` で自動生成
    プロジェクトルートで `/init` を実行すると、コードベースを分析して初期CLAUDE.mdを自動生成してくれる。すでに存在する場合は改善案を提案する。

    書きたい内容は何かによって
    ・ 全プロジェクト共通の個人設定 → ~/.claude/CLAUDE.md
     ・チームで共有するプロジェクト指示 → ./CLAUDE.md(Git管理)
     ・自分だけのプロジェクト設定 → ./CLAUDE.local.md
     ・特定ファイルにアクセスしたときだけ → .claude/rules/.md(paths:設定)
     ・長い手順書・めったに使わないリファレンス →.claude/skills/~/SKILL.md

    書き方

    書き方としてはMarkdownファイルで特別な書式は必須ではなく、見出しと箇条書きを使って書くだけで十分です。
    人間が読む場合と同じで、まとまりのあるセクションを設けた方がただただ文章だけを書いていくよりも指示に従いやすくなります。
    例えばCLAUDE.local.mdの例として以下のような感じになります。

    # 個人設定(Gitにはコミットしない)
    
    ## ローカル環境
    - ローカルのAPIサーバー: http://localhost:8000
    - テスト用ログインID: test-user@example.com
    - ステージング環境: https://staging.example.com
    
    ## 個人的な作業方針
    - 実装前に必ず設計を見せてもらう
    - コンポーネントを分割するときは先に相談する

    具体性が肝心

    検証できる粒度で書くことが重要です。曖昧な指示はClaudeが解釈に迷います。
    例えば
    「コードを適切にフォーマットする」
    のではなく
    「インデントは2スペースを使う」
    といった具体的な書き方にすることです。

    @ によるファイルインポート

    別のファイルをCLAUDE.mdから参照できます。手順書や仕様書が長くなってきたら切り出すのに便利です。
    例えば
    ・markdownプロジェクトの概要は @README を参照。
    ・利用可能なnpmコマンドは @package.json を参照。
    といったものです。
    Claude Codeがセッション開始時に package.json の中身を読み込んで、CLAUDE.mdの文脈に展開してくれます。つまり 「このファイルの内容もClaude.mdの一部として読んでね」 という指示です。
    ただし、インポートしたファイルもセッション開始時にコンテキストへ丸ごと展開されるので、ファイルが大きいとその分トークンを消費します。
    。。という書き方をしてしまうとあまり意味を感じなくなる方もいらっしゃるかもしれませんが、「分割すれば節約できる」ではなく、あくまでCLAUDE.mdの整理整頓のための仕組みという考えになります。

    CLAUDE.mdを書くコツ

    ・普通のMarkdownでOK — 特殊な書式は不要です。見出しと箇条書きが基本です。
    ・1ファイル200行以内 — 長くなったら rules/ や skills/ に分割を検討してください
    ・具体的に書く — 既に書いていますが、「適切に」「ちゃんと」といった曖昧な指示は避け、動作を明確にしましょう
    ・矛盾を作らない — 複数のファイルで矛盾する指示があるとClaudeが任意でどの指示に従うか選びます
    ・同じ説明を2回打ち込んだら追記のサイン ー 自分が作業の中で「また同じことを指示している」と気づいたらCLAUDE.mdに書くようにしましょう

    あなたへのおすすめ