Claude Codeの「グローバルCLAUDE.md」で開発体験を統一する方法

AIコーディングアシスタントを日常的に使うようになると、「毎回同じ指示を書くのが面倒だ」と感じる場面が増えてきます。プロジェクトごとにコミットメッセージの規約やコーディングスタイルを伝え直す手間は、地味にストレスではないでしょうか。Claude Codeには、こうした繰り返しを解消する「グローバルCLAUDE.md」という仕組みが用意されています。本記事では、その構造と実践的な活用方法を紹介します。

CLAUDE.mdとは何か

Claude Codeは、作業ディレクトリに配置された CLAUDE.md というMarkdownファイルを自動的に読み込み、会話のコンテキストとして利用します。ここに書かれた内容は、コード生成やレビューの判断基準としてClaude Codeの振る舞いに直接影響を与えます。

たとえば「変数名はキャメルケースで統一する」と書いておけば、Claude Codeが生成するコードはその規約に沿ったものになります。逆に何も指定しなければ、Claude Codeは一般的なベストプラクティスに従って判断するため、プロジェクト固有の慣習とのズレが生じることがあります。CLAUDE.mdは、そうした暗黙知を明文化してAIと共有するための橋渡し役といえます。

重要なのは、CLAUDE.mdにはスコープが異なる2種類が存在する点です。

プロジェクトCLAUDE.md: リポジトリのルートに配置し、そのプロジェクト固有のルールを定義する
グローバルCLAUDE.md: ~/.claude/CLAUDE.md に配置し、すべてのプロジェクトに共通で適用される

最初はプロジェクトCLAUDE.mdだけを使っていたのですが、複数リポジトリを横断して作業するうちに、同じルールをコピー＆ペーストしている自分に気づかされました。グローバルCLAUDE.mdを知ったときは、まさにこれが欲しかったと感じたものです。

プロジェクトCLAUDE.mdはリポジトリにコミットできるため、チームメンバー全員が同じルールのもとでClaude Codeを使えるという利点があります。一方、グローバルCLAUDE.mdは個人のホームディレクトリに置かれるため、チームには共有されません。この違いが、後述する「責務分離」の考え方につながります。

グローバルCLAUDE.mdの設定方法と読み込み優先順位

セットアップはシンプルで、~/.claude/CLAUDE.md にファイルを作成するだけです。特別なコマンドや初期化は必要ありません。

mkdir -p ~/.claude
touch ~/.claude/CLAUDE.md

作成したファイルをエディタで開き、Markdown形式でルールを記述します。見出しや箇条書きを使って構造化しておくと、後から見返したときにも把握しやすくなります。

Claude Codeは会話開始時に、グローバルCLAUDE.mdとプロジェクトCLAUDE.mdの両方を読み込みます。両者に矛盾する記述がある場合はプロジェクト側が優先されるため、グローバルには汎用的なルールを、プロジェクトには固有のルールを書くという使い分けが自然です。

具体的な優先順位を整理すると、以下のようになります。

プロジェクトCLAUDE.md（リポジトリルートの CLAUDE.md）── 最優先
グローバルCLAUDE.md（~/.claude/CLAUDE.md）── プロジェクト側に同じ項目がなければ適用

たとえばグローバルで「コミットメッセージは日本語で書く」と定義し、英語圏のクライアント向けプロジェクトでは「コミットメッセージは英語で書く」と上書きする、といった運用が可能です。この仕組みのおかげで、グローバル側に書いた内容が特定プロジェクトで不都合を起こす心配がありません。

設定の粒度をどこまで細かくするかはチームによって異なります。厳密に定めすぎるとかえって柔軟性を失うこともあるので、最初は最低限のルールから始めて徐々に育てていく方法をおすすめします。筆者自身も、最初はたった3行から始めました。使っていくうちに「これも統一したい」という項目が自然と見えてくるものです。

実務で効果的な記述パターン

同じように「何を書けばいいのか」で悩んでいる方も多いのではないでしょうか。実務でとくに効果を実感できた記述パターンをいくつか紹介します。

レスポンス言語の統一

日本語で開発しているチームでは、日本語で応答する と一行書くだけで、毎回の言語指定が不要になります。小さなことですが、日々の作業では確実に効いてきます。

Claude Codeはデフォルトでは英語で応答することが多いため、日本語話者にとってこの設定は最初に書くべき一行といっても過言ではありません。会話の途中で「日本語でお願いします」と書き直す手間がなくなるだけでも、集中力の維持に貢献してくれます。

コミットメッセージ規約

Conventional Commitsの形式やメッセージの言語を定義しておくと、Claude Codeが生成するコミットメッセージが一貫したものになります。チーム全体のgit logの可読性向上にもつながるため、投資対効果の高い設定です。

実際の記述例を示します。

## コミットメッセージ

- 日本語で書く
- Conventional Commits形式を使用:
  - feat: 新機能追加
  - fix: バグ修正
  - docs: ドキュメント
  - refactor: リファクタリング
  - test: テスト
  - chore: 雑務

このように定義しておくと、Claude Codeにコミットを依頼した際に feat: ユーザー認証機能を追加 のような統一されたメッセージが生成されるようになります。以前はプロジェクトごとに書式がばらついていたのですが、グローバルCLAUDE.mdで規約を定めてからは、どのリポジトリのgit logを開いても同じフォーマットで読めるようになりました。

ビルド・テストの方針

「明示的に依頼されない限りビルドを実行しない」「意味のないテストを実装しない」といったガードレールを設けることで、AIが意図しない操作を行うリスクを低減できます。振り返ると、こうした制約を書かずに不要なビルドが走ってしまった経験が、設定を充実させるきっかけでした。

とくにNext.jsのようなフレームワークでは、ビルドに数十秒から数分かかることも珍しくありません。Claude Codeが確認のつもりで next build を実行してしまうと、その間ターミナルが占有されてしまいます。「明示的に依頼されない限りビルドを実行しない」という一文を加えてからは、こうした不意のビルドがなくなり、作業のリズムが崩れることがなくなりました。

コード生成時の品質ガードレール

ビルド・テスト以外にも、コード生成そのものに関するガードレールを設けておくと有用です。

## コード生成

- 不要なコメントやドキュメントを自動生成しない
- 実装時は既存のコードを確認し、重複を避ける

AIは丁寧さゆえに、すべての関数にJSDocコメントを付けたり、READMEを自動生成したりすることがあります。チームの方針として「コメントは複雑なロジックにのみ付ける」と決めている場合、意図しないコメントが大量に追加されるのは避けたいところです。こうしたルールをグローバルに定義しておくことで、どのプロジェクトでも一貫したコード品質を保てます。

グローバルCLAUDE.mdの記述で気をつけたいポイント

実際に運用してみると、「書き方」にもいくつかのコツがあることに気づきます。

簡潔さを保つ

CLAUDE.mdの内容はプロンプトのコンテキストウィンドウを消費します。長すぎる説明や背景情報を詰め込むと、肝心のコード生成に使えるトークンが減ってしまいます。ルールは箇条書きで端的に書き、補足が必要な場合のみ短い説明文を添えるのが実用的です。

筆者の感覚では、グローバルCLAUDE.mdは多くても50〜80行程度に収めるのがちょうどよいバランスです。それ以上になる場合は、本当にすべてのプロジェクトに共通するルールなのかを見直し、プロジェクト固有のものはプロジェクトCLAUDE.mdに移すことを検討してください。

指示は具体的に書く

「きれいなコードを書いて」のような曖昧な指示よりも、「変数名はキャメルケースで統一する」「関数は30行以内に収める」のように具体的な基準を示すほうが、Claude Codeは期待通りに動いてくれます。AI相手でも人間相手でも、曖昧な依頼からは曖昧な成果物しか生まれないという点は共通しています。

定期的に見直す

CLAUDE.mdは一度書いたら終わりではありません。開発スタイルが変わったり、新しい知見が得られたりしたタイミングで見直すことをおすすめします。筆者は月に一度程度、グローバルCLAUDE.mdを開いて「まだこのルールは必要か」「新しく追加すべき項目はないか」を確認するようにしています。

チーム導入時に意識したいこと

グローバルCLAUDE.mdは ~/.claude/ 配下に置くため、個人の開発環境に閉じたファイルです。一方、プロジェクトCLAUDE.mdはリポジトリにコミットされるため、チーム全体で共有できます。

この特性を活かすと、チーム共通のルールはプロジェクトCLAUDE.mdに、個人の好みや環境固有の設定はグローバルCLAUDE.mdに、という明確な責務分離が実現します。一概には言えない部分もありますが、レビュー方針やブランチ戦略はプロジェクト側、エディタ連携や応答言語はグローバル側に書くのが実用的なパターンかもしれません。

チームで導入する際の具体的な進め方として、以下のステップが参考になるかもしれません。

まずプロジェクトCLAUDE.mdを整備する: ブランチ戦略、コーディング規約、テスト方針など、チーム全員が従うべきルールを定義する
各メンバーがグローバルCLAUDE.mdを作成する: 応答言語やエディタ設定など、個人ごとに異なる好みを反映する
運用しながら調整する: 「これはプロジェクト側に書くべきだった」「これはグローバルで十分だ」という気づきをもとに、配置を最適化していく

大切なのは、最初から完璧を目指さないことです。CLAUDE.mdは設定ファイルというよりも、AIとの「申し合わせ事項」に近い性質を持っています。チームの成長とともに育てていくものだと捉えるほうが、導入のハードルも下がるのではないでしょうか。

また、CLAUDE.mdの内容はプロンプトのコンテキストウィンドウを消費します。情報を詰め込みすぎると本来の作業に使えるトークンが減るため、簡潔さを維持することも重要です。

プロジェクトCLAUDE.mdとの使い分け早見表

どちらに書くべきか迷ったときのために、代表的な設定項目の振り分け例を表にまとめました。

設定項目	グローバル	プロジェクト
応答言語（日本語で応答する等）	○
コミットメッセージ規約	○	○（上書き用）
ブランチ戦略		○
テストの方針	△（汎用）	○（具体的）
ビルドコマンドの制御	○	○（上書き用）
コーディング規約	△（汎用）	○（言語固有）
API仕様・環境変数の扱い		○

「△」は、汎用的なルールとしてグローバルに書くことも可能ですが、プロジェクト固有の事情がある場合はプロジェクト側で上書きするのが望ましい項目です。

まとめ

グローバルCLAUDE.mdは、AI支援開発における「自分だけのデフォルト設定」を定義できる仕組みです。一度整備すれば、どのプロジェクトでも一貫した開発体験が得られるようになります。設定ファイルひとつで開発効率が変わるというのは、エンジニアにとって馴染みのある体験ではないでしょうか。

最初の一歩は、~/.claude/CLAUDE.md を作成して「日本語で応答する」と一行書くことです。そこから少しずつルールを追加していくうちに、Claude Codeが自分の開発スタイルを理解したパートナーのように感じられる瞬間が訪れるはずです。AIとの協働は、こうした小さな積み重ねの先にあるものだと、日々の開発を通じて実感しています。

aduceでは、Claude Codeをはじめとした最新のAIツールを活用したシステム開発やDX推進を支援しています。AI時代の開発プロセスについてお悩みがあれば、ぜひaduceのお問い合わせはこちらからお気軽にご相談ください。