CLAUDE.mdの書き方【Claude Code設定ファイル完全ガイド】

ひとことで言うと「AIへの引き継ぎメモ」

CLAUDE.md（クロード・エムディ）とは、AIコーディングツール「Claude Code」（クロード・コード）が毎回のセッション開始時に自動で読み込む設定ファイルのことです。

ここに「このプロジェクトのルール」「やってはいけないこと」「作業の進め方」を書いておくと、毎回同じことをAIに説明しなくても、最初からわかった状態で作業してもらえます。

料理で例えるなら、毎日シフトが変わるキッチンスタッフに向けて「うちの店のレシピと禁止事項を書いた引き継ぎノート」を渡すようなイメージです。そのノートさえあれば、新しいスタッフでも即日同じ水準の料理が作れます。

なぜ今注目されているのか

AIは「毎回記憶がリセットされる」問題がある

ChatGPTやClaudeなどの生成AI（=人工知能）は、会話のセッション（=一回の作業のまとまり）が終わると、その内容をほとんど覚えていません。次のセッションでは「はじめまして」の状態から始まります。

これはまるで、毎日記憶がリセットされるパート社員に同じ説明を繰り返すようなもの。慣れてきた頃に終わってしまい、また最初から説明…というストレスが生まれます。

Claude Codeが登場し、プロの現場に広まった

AnthropicはAIを使ったコーディングツール「Claude Code」を開発し、2025年に一般公開しました。このツールは、プログラムを書く作業を自動化・補助するものです。Claude Codeが広まるにつれ、「どうすればAIに毎回同じ説明をしなくて済むか」という課題が注目されるようになりました。

その解決策として登場したのが CLAUDE.md です。

「一度書けばずっと使える」が革新的

CLAUDE.mdをプロジェクトフォルダ（=作業用のフォルダ）に置くだけで、Claude Codeが自動的に読み込みます。つまり、プロジェクトのルールや注意点をこのファイルに書いておけば、何度も繰り返し説明する必要がなくなるのです。

2026年時点では、Slack・Notion・Stripe・HubSpot・Supabaseといった実務で使う外部サービスと連携するための「MCPサーバー」が15種類以上公開されており、CLAUDE.mdでこれらを一元管理することで、Claude Codeが開発作業中にシームレスに各サービスを活用できるようになっています。

何ができて、何ができないか

できること

CLAUDE.mdには、次のような内容を書いておくことができます。

CLAUDE.mdファイルはプロジェクト全体だけでなく、サブフォルダ（=フォルダの中のフォルダ）ごとにも置くことができます。フロントエンド（=画面の部分）専用のルール、バックエンド（=サーバー側の部分）専用のルールと、場所によって内容を変えられるのも特徴です。

さらに、ホームディレクトリ（=自分のパソコン全体で共通の設定場所）にCLAUDE.mdを置くと、すべてのプロジェクトに共通するルールを一度だけ書いておくこともできます。

できないこと・注意すべき限界

一方で、CLAUDE.mdは「強制的な設定」ではありません。Anthropicの公式ドキュメントには、「Claudeはこれらをコンテキスト（=会話の背景情報）として扱い、強制的な設定ではない」と明記されています。

つまり、書いたからといって100%従ってくれるとは限りません。とくに、内容が長くなればなるほどAIが指示を見落とす可能性が高まります。公式ドキュメントでは1ファイルあたり200行以内を目安として推奨しています。

「あれもこれも書き込もう」とすると、かえって精度が下がるというわけです。

また、セッション途中でCLAUDE.mdのルールが消えてしまう「コンパクション問題」も報告されています。これへの対策については後述する永続メモリレイヤーの活用が有効です。

はじめてみるには

ステップ1：Claude Codeをインストールする

CLAUDE.mdを活用するには、まず Claude Code が必要です。Claude Codeはターミナル（=文字を入力する画面）から使うツールで、MacOS・Linux・Windowsで動作します。

ステップ2：/init コマンドで自動生成してもらう

一番手軽な始め方は、Claude Codeの /init コマンドを使うことです。このコマンドを実行すると、Claudeがプロジェクトを分析して、ビルドコマンドやテスト手順、プロジェクトのルールを含むCLAUDE.mdを自動で作ってくれます。

すでにCLAUDE.mdが存在する場合は、上書きせずに「改善の提案」をしてくれるので安心です。

ステップ3：自分の言葉で育てていく

自動生成されたファイルはあくまで出発点です。実際に使いながら、「こういうことも伝えておけばよかった」という気づきをその都度追加していきましょう。

ちょうど、新入社員向けの引き継ぎマニュアルが、実際に使ってみてはじめて細かい注意点が見えてくるのと同じです。

置き場所による違い

効果的な書き方：トークン最小化の3つの原則

CLAUDE.mdは長いほど良いわけではありません。ファイルの内容はセッション開始のたびにトークン（=AIが処理する情報の単位）として消費されます。長くなるほどAIの処理に負荷がかかり、指示の守られ方が下がっていきます。さらに、長すぎるCLAUDE.mdは「後半の重要な指示を無視される」という現象も引き起こします。

「大事なことだけ、短く、具体的に書く」ことが、CLAUDE.mdをうまく使うコツです。以下の3原則を意識してみましょう。

原則1：階層化と優先度付け

最初に全体を説明するのではなく、今のタスク・今のプロジェクト段階に必要な情報だけを最上位に配置します。プロジェクト全般の説明や技術スタック、コード規約は「背景」として下に置き、直近の作業に関連する指示が上に来るような構造にします。

原則2：「説明」から「マッピング」へ

「このプロジェクトは〜〜という構成になっています…」という文章説明は、思ったより多くのトークンを消費します。代わりに、ディレクトリ構造をテキスト図で示す、ファイル一覧表を用いるなど、視覚的・構造的な表現に切り替えます。

原則3：「全体」から「差分」へ

プロジェクト全体の技術スタックは、通常GitHubのREADMEやpackage.jsonに既に書いてあります。CLAUDE.mdには「このプロジェクトで使っている独自慣習」「よくあるバグパターンと回避方法」「外部ドキュメントへのリンク」など、CLAUDE.mdにしか書いていない情報を優先して記載します。

推奨テンプレート構造

これらの原則を踏まえた、効果的なCLAUDE.mdのテンプレート構造は以下のとおりです。

# Project Context for Claude Code

## 1. Current Mission（現在のミッション）
<!-- 今このタスクで何を作っているのか、1段落で -->

## 2. Non-Negotiables（譲れないルール）
<!-- 絶対に守らなければいけない制約。リスト形式で -->
- ルール1
- ルール2

## 3. Architecture Map（アーキテクチャ図）
<!-- テキスト図、またはディレクトリ構造テーブル -->

## 4. Key Files Reference（主要ファイルの役割）
| ファイルパス | 役割 | 編集時の注意 |
|-----------|-----|----------|

## 5. Common Pitfalls（よくあるバグとその原因）
<!-- このプロジェクト特有のアンチパターン -->

## 6. Code Examples（参考コード）
<!-- 正解例を提示。テンプレートとして使う -->

## 7. External References（外部ドキュメント）
<!-- 詳細な仕様や設計書へのリンク -->

この構造の良さは、AIが最初に読むべき「必須情報」と「参照情報」が明確に分離されていることです。セクション7で詳細を外部リンクに委ねることで、CLAUDE.md本体を簡潔に保てます。

MCPサーバーとの連携（2026年時点の最新情報）

CLAUDE.mdの活用が広がるにつれ、外部サービスとの連携を担う「MCPサーバー」（Model Context Protocol）との組み合わせが注目されています。2026年時点でProduction-Ready（=実用レベル）なMCPサーバーは15種類以上リリースされており、以下のようなサービスと連携できます。

• Notion（@modelcontextprotocol/server-notion）
• Stripe（@modelcontextprotocol/server-stripe）
• HubSpot（@modelcontextprotocol/server-hubspot）
• Slack（@modelcontextprotocol/server-slack）
• Supabase（@modelcontextprotocol/server-supabase）
• その他10種類以上

CLAUDE.mdにMCPサーバーの情報を記述しておくと、「Slackの最新メッセージを取得して要約して」「Notionのデータベースに追加して」といった高レベルの指示だけで、Claude Codeが自動的に外部サービスへアクセスして処理を完結させます。

MCPサーバーの設定例

mcp_servers:
  - name: "notion"
    command: "npx"
    args: ["@modelcontextprotocol/server-notion"]
    env:
      NOTION_API_KEY: "${NOTION_API_KEY}"
  
  - name: "slack"
    command: "npx"
    args: ["@modelcontextprotocol/server-slack"]
    env:
      SLACK_BOT_TOKEN: "${SLACK_BOT_TOKEN}"
      SLACK_TEAM_ID: "${SLACK_TEAM_ID}"

APIキーは環境変数（${KEY_NAME}の形式）で参照し、.envファイルに実際の値を記述します。CLAUDE.mdに直接APIキーを書き込むのは絶対に避けてください。Gitリポジトリに含まれると第三者に漏洩するリスクがあります。

セッションをまたいで記憶を保つ：永続メモリレイヤーという考え方

CLAUDE.mdは「毎回読み込まれる設定ファイル」として有用ですが、複数セッションにわたるエージェント開発では、それだけでは不十分なケースが出てきます。前回のセッションで発見したバグの修正方法、進行中のタスクの状態、プロジェクト固有の学習内容——これらをセッションをまたいで保持するための仕組みが「永続メモリレイヤー」です。

特に以下のような場面で効果を発揮します。

• 前回のセッションで発見したバグの修正方法を、次のセッションで即座に活用したい
• CLAUDE.mdのコンパクション問題（セッション中にルールが消える）を回避したい
• どのタスクが成功・失敗したかを後から追跡したい
• AIが実行結果を分析して、次の実行時の動作を改善する（自己改善）

MEMORY.mdで4層構造を作る

永続メモリの実装は、シンプルなMarkdownファイル MEMORY.md で始められます。構造は以下の4層が基本です。

ルール層（Rules Layer）: コーディング規約・API設計ルール・チーム規約など、CLAUDE.mdの補完として機能するルールを記録します。セッション開始時に /read MEMORY.md で読み込むことで、コンパクション問題を回避できます。

学習層（Learnings Layer）: 過去のセッションで発見したバグパターン・パフォーマンス知見・トラブルシューティング情報を蓄積します。

### バグ修正パターン
- **Issue**: CSS Modulesでクラス名がnullになる
  - **原因**: tsconfig path aliasが反映されていない
  - **解決策**: `moduleResolution`を"bundler"に変更
  - **発見日**: 2026-07-05

実行履歴層（Execution Log Layer）: タスクの成功・失敗・所要時間を時系列で記録し、後から追跡できるようにします。

状態層（Current State Layer）: 進行中のタスクの進捗や、セッション中に決定した設定値を保持します。

運用フロー

注意点

ファイルが大きくなりすぎると、Claude の入力トークン数の制限に達してレスポンスが遅くなります。実行履歴は定期的にアーカイブ化し、古い学習情報は要約にまとめましょう。目安として、1ファイル200行以内はCLAUDE.mdと同様の基準が参考になります。さらに規模が大きくなった場合は、LangChainとChromaを組み合わせたベクトル検索の導入も選択肢のひとつです。

注意したいこと

書きすぎはかえって逆効果

CLAUDE.mdは長いほど良いわけではありません。「大事なことだけ、短く、具体的に書く」ことが基本です。たとえば「きちんとコードを書いてください」という曖昧な指示より、「変更のたびに必ずテストを実行し、すべてのテストが通るまでタスク完了としない」のように、確認できるほど具体的に書くほうが効果的です。

機密情報の取り扱いに注意

CLAUDE.mdをチームで共有する場合は、個人情報や社外秘の情報を書き込まないよう注意が必要です。とくにAPIキーは環境変数で参照する形式にし、.envファイルは必ず.gitignoreに追加してください。個人的なメモや機密情報は別ファイルに分けて管理することをおすすめします。

古い情報を放置しない

プロジェクトが変わっていくのに、CLAUDE.mdの内容が古いままだと、Claudeが間違った前提で作業を進めてしまう可能性があります。コードに大きな変更を加えたときや、月に一度を目安に内容を見直す習慣をつけましょう。確認すべき項目は次のとおりです。

• ルールに矛盾がないか
• ファイルパスが現在のコードベースと一致しているか
• 最近発見されたバグパターンを追加すべきか
• 外部参照リンクが最新版を指しているか

「これさえあれば安心」ではない

CLAUDE.mdはあくまでAIへのヒント集であり、AIの出力を完全に制御するものではありません。重要な変更をAIに任せるときは、必ず人間がレビュー（=確認）する仕組みを残しておきましょう。

まとめ

CLAUDE.mdは、AIコーディングツール「Claude Code」に「毎回覚えておいてほしいこと」を伝えるための設定ファイルです。一度書いておけば、セッションが変わっても同じルールで動いてくれます。

2026年時点では、Slack・Notion・Stripeなど15種類以上の外部サービスと連携するMCPサーバーも実用レベルで利用できるようになっており、CLAUDE.mdを活用することでClaude Codeは単なるコード補完ツールを超えたエージェント型の開発パートナーとして機能します。

さらに、複数セッションにわたる開発では MEMORY.md による永続メモリレイヤーを組み合わせることで、過去の学習・タスク履歴・プロジェクト固有のルールをセッションをまたいで保持できます。CLAUDE.mdのコンパクション問題への対策としても有効です。

はじめは /init コマンドで自動生成し、使いながら少しずつ育てていくのがおすすめです。「階層化と優先度付け」「説明から図表へ」「プロジェクト固有の差分情報を優先」という3原則を意識しながら、書きすぎず、具体的に、200行以内を目安に保つと効果的に機能します。

AIに毎回同じ説明をする手間を省いて、本当に大切な作業に集中できる環境を整えてみてください。

あわせて読みたい

• 会話を覚えるAIの秘密：「メモリ」をどう残すのか
• Claudeのプロンプト設計って何？AIに正確に指示する方法を基本から解説
• MCPとは何か？2026年版：Model Context Protocolをわかりやすく解説