はじめに
株式会社ネクストスケープ Chief Technology Office所属の小野塚です。
ある程度AIツールを使っていくと「いつもこのプロンプト入力してるな」「毎回この指示を出すのは面倒だな」と思ったことがあると思います。
そういったものについてはなるべく設定ファイルにその指示を書き込み、手間を減らすことをお勧めします。
あるいはそういったファイルの存在は知っていて、書いた方が良いとはわかっているものの、具体的にどこに何をどう書けば良いのかわからず、そのまま使っている方もいるかもしれません。
そういった方向けにClaude、ClaudeCodeを使っている方向けに設定ファイル、CLAUDE.mdについて公式サイトの内容を改めて読み込み、まとめてみました。
スコープ
まず、スコープとしては以下の３つあります。
・Managed（IT管理・組織全体）
・User（個人・全プロジェクト共通）
・Project（プロジェクト・チーム共有）
それぞれにどういったファイルが置かれるか、置くべきかを更に説明します。
Managedは正直なところ私も今回の記事を作成するにあたり初めて知ったものでして、IT管理者がMDM（Intune・Group Policyなど）を使って組織展開するときに使うものだそうです。今回はManagedについては割愛させてください。
Userスコープ（個人・全プロジェクト共通）
置き場所は以下。
~/.claude/
ファイルは以下になります。
CLAUDE.md ：個人のグローバル指示
どのプロジェクトで作業していても毎セッション読み込まれる個人のデフォルト指示をここで記載します。
Projectスコープ（プロジェクト・チーム共有）
置き場所場所は各プロジェクトのフォルダ直下となります。Claude Codeを実行している場所ですね。
ファイルは以下の2種類となります。
・CLAUDE.md： プロジェクト指示（Git管理・チーム共有）
・CLAUDE.local.md： 個人用プロジェクト指示（.gitignore推奨）
あとはプロジェクト内の.claudeフォルダ配下に置く場合もありまして、これも同じくプロジェクトスコープとなります。
プロジェクトの規約、ビルドコマンド、アーキテクチャ方針など、チームで共有したい指示を書き、Gitで管理することでチーム全員に適用されます。
CLAUDE.local.md（個人用プロジェクト指示）
置き場所：<project>/CLAUDE.local.md（.gitignoreに追加推奨）
このCLAUDE.local.mdは初めて見る方もいらっしゃるかもしれません。同じプロジェクトで自分だけに適用したい指示を書く場所。用途例は「自分のサンドボックスURL」「好みのテストデータ」など、チームには共有しない個人的な設定。
そのため、Gitには上げずに.gitignoreに設定することをお勧めします。
CLAUDE.mdと同様に扱われ、同じディレクトリの `CLAUDE.md` の後に結合されます。つまり、こちらが優先されます。
書き方のポイント・タイミング
・サイズ：1ファイルあたり200行以内を目標にしてください。 長いほどコンテキストを消費し、指示の遵守率が下がります
・構造： Markdownの見出しと箇条書きで関連する指示をグループ化すること
・具体性：曖昧な指示を書かない（後述します）
あとは矛盾するルールが複数あるとClaudeが任意で選択してしまうため、定期的に見直して訂正もしくは不要なルールを削除することをお勧めします。
いつ追記するかですが、公式の推奨としては
・Claudeが同じミスを2回繰り返したとき
・コードレビューで、Claudeが知っておくべきだった指摘があったとき
・先週と同じ説明をチャットに打ち込んでいると気づいたとき
・新しいチームメンバーが生産的になるために必要な情報があるとき
だそうです。
/initで自動生成
恥ずかしながら最近は忘れていたのですが、プロジェクトルートで /initコマンドを実行すると、コードベースを分析してCLAUDE.mdを自動生成してくれます。また、すでに存在する場合は改善案を提案してくれます。
ただ、この/initコマンドによる出力結果としてのCLAUDE.mdは冗長になりがちです。一旦目を通してもらって、なぜその行が存在するのか理解できない、もしくは説明できない場合は削除してしまってください。
逆に不足している情報があるはずなのでそういったものを追記してください。
どこに何を書けばよいのか
と、ここまで読まれた方は置き場所によって動きが変わるのはわかったけど、じゃあ「結局どこに何を書けば良いのか」と思われたかもしれません。
書きたい内容が何かによるのですが、簡潔に書くと以下になります（rulesも含まれてますが、別途記事を書きますのでご容赦を。。）。
・ 全プロジェクト共通の個人設定 ： ~/.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
## 個人的な作業方針
- 実装前に必ず設計を見せてもらう
- コンポーネントを分割するときは先に相談する
ーーー
@path/to/import構文によるファイルインポート
この機能（記法）は恥ずかしながら今回この記事を書くにあたって初めて知りました。「@」で指定することで別のファイルをCLAUDE.mdから参照できます。手順書や仕様書が長くなってきたら切り出すのに便利です。
例えば
「markdownプロジェクトの概要は @README を参照」
「利用可能なnpmコマンドは @package.json を参照」
といったものです。
上のように書くとClaude Codeがセッション開始時に 例えばpackage.json の中身を読み込んで、CLAUDE.mdの文脈に展開してくれます。つまりは 「このファイルの内容もClaude.mdの一部として読んでね」 という指示になります。
ただし、インポートしたファイルもセッション開始時にコンテキストへ丸ごと展開されるので、ファイルが大きいとその分トークンを消費します。
トークン消費に影響しないということであればあまり意味を感じなくなる方もいらっしゃるかもしれませんが、「分割すれば節約できる」ということではなく、あくまでCLAUDE.mdを見やすくするための仕組みと捉えてもらえればと思います。
CLAUDE.mdを書く時の注意点
絶対守るべきというレベルではありませんが、公式に書かれている内容であったり、自身の経験上、こうしたほうがよいのではといった注意点があります。
既にCLAUDE.mdを使いこなしている方であればそういったノウハウを各自持たれているかもしれませんが、いくつか私が見聞きしたことを以下に挙げてみますので参考にしてください。
注意点１：具体性が肝心
CLAUDE.mdは検証できる粒度で書くことが重要です。曖昧な指示はClaudeが解釈に迷います。
例えば
「コードを適切にフォーマットする」
のではなく
「インデントは2スペースを使う」
といった具体的な指示を記載するようにしてください
注意点２：詳細なコードスタイルガイドラインは含めない
上の「具体性が肝心」の例で挙げた「インデントが。。。」といったコードスタイルに関する内容、例として挙げておきながらなんですが、あのようなコードスタイルについては例えばJavaScriptやTypeScriptであればリンターやフォーマッターで対応可能であり、わざわざこれに関してトークンを消費する必要は無いと思います。
注意点３：禁止事項を書く
「してほしい」ことを書くよりは「してほしくない」ことを優先して書くようにした方がよいかもしれません。変更してほしくないファイルや実行してほしくないコマンドがあればそういったものを明記しておいたほうがよいです。
注意点４：スキルやコマンドで済ませられるものは書かない
注意点２とも関連していますが、スキルやコマンドを実行すれば済むものをわざわざCLAUDE.mdに書く必要はないと思います。
CLAUDE.mdに書く量は200行未満が好ましいと言われていますので最小限に抑えるためにもスキルやコマンドを活用してください。
注意点５：プロジェクト概要を書く
最後の注意点としてかなり個人的な経験則ではありますが、プロジェクト概要（技術スタック、構造、目的等）を最初に書くことをお勧めします。
具体的に何が良い、もしくはどういったことに役に立つといったことはうまく説明できないのですが、返ってくるレスポンスは書かないよりも数段良い内容として返ってくる気がします。
用語集について
ちょっと取り留めもなく書いてしまいましたが、もう１つだけ。。
AIツールを利用する場合において用語集は非常に役に立つと思いますが、上で書いた通りCLAUDE.mdに書くにはデータ量に限度があります。
なので量と用途次第で置き場所、ファイルを変えた方がよさそうです。
例えばなのですが、
・用語集が少なく、かつプロジェクト全体に関わる
ー＞CLAUDE.mdに直接書くか、@docs/glossary.mdのように別ファイルに切り出して@でインポートさせる
・用語集が長い・多い、分野ごとに分けたい
ー＞rules/配下に分野別でファイルを置いて paths: で条件付き読み込み（例：請求まわりのコードを触るときだけ請求用語を読み込む）
途中でも少々触れましたが、rulesというのはCLAUDE.mdを補完するルールファイルの置き場所でして、CLAUDE.mdとの大きな違いは、「paths:」という目印を指定することで特定のファイルにアクセスしたときだけ読み込まれます。また別の機会に説明できればと思います。
そもそも無理に用語集としてCLAUDE.mdやrulesを活用することも無いと思いますので、あくまで一手段として参考にしてもらえればと思います。
終わりに
色々書いてしまいましたが、まずは「同じ説明を2回打ち込んだら」CLAUDE.mdへの追記のサインです。自分が作業の中で「また同じことを指示している」と気づいたらCLAUDE.mdに書くようにしましょう。
また、CLAUDE.mdには強制力はなく、記述した内容と異なる動きをする場合もあります。何かを強制する場合はsettings.jsonでhooksという機能を使うのですが、これはまた別の機会で紹介できればと思います。
Claudeユーザーの方でCLAUDE.mdをあまり触っていなかった方は是非これを機に自分ならでは、あるいはチーム・プロジェクトならではのCLAUDE.mdを育ててみてください。
当社ネクストスケープはこのように生成AIをはじめとした新しい技術・知識を日々取り入れており、Webサイト、スマホアプリ、Hololensアプリの開発をはじめ、CMSを利用したサイトの新規構築やリニューアルなど、お客様のニーズに幅広く対応いたします。お困りのことがございましたら、いつでもお気軽にお問い合わせください。
（以下当社お問合せフォーム）
当社では一緒に働いてくれる仲間を募集しています。是非以下のサイトよりお申込みください。
