CLAUDE.mdの書き方と設計パターン｜規模別の分割・階層設計とチーム運用

CLAUDE.mdは、Claude Codeにプロジェクトの前提・ルール・作法を教える設定ファイルです。1ファイルに詰め込まず、プロジェクト規模に応じて「常に読ませるもの」と「必要なときだけ読ませるもの」を分けて設計します。

「CLAUDE.mdを書き始めたが、どこまで細かく書くべきか分からない」「プロジェクトが大きくなるにつれてCLAUDE.mdが肥大化し、Claude Code自体の動作が重くなってきた」「チームの誰かが書き足したルールと、別の人のルールが食い違っている」——CLAUDE.mdを使い込むほどに直面する設計上の悩みです。

CLAUDE.mdの設計とは、ルールを「全体に効くもの」「特定の領域にだけ効くもの」「特定の作業のときだけ効くもの」に分け、それぞれを適切な置き場所に配置することです。小規模ならルートの1ファイル、中規模なら.claude/rules/とpaths指定による分割、モノレポならディレクトリごとの階層化が基本の型になります。

Claude Codeの使い方・コマンド・並列実行・料金の全体像はClaude Code完全ガイド（ハブ）で目的別に整理しています。

この記事でわかること

CLAUDE.mdの設計パターンを学び、プロジェクトに最適化したい開発リーダーに向けた記事です。規模別の置き場所の決め方から、チームでルールを育てていく運用までを順に解説します。

• 読み込みの優先順位と階層構造 — Claude Codeは複数の設定ファイルを階層的に読み込みます。どこに書いたルールがどの範囲に効くのかを整理します。
• インポートと.claude/rules/による分割 — 外部ファイルの取り込みと、pathsフロントマターで特定のファイルパスにだけルールを適用する方法を解説します。
• モノレポでの階層設計 — 複数プロジェクト・複数チームが同居するリポジトリで、ルールをどう分けるかを実例で示します。
• 個人設定とチーム共有の使い分け — マネージドCLAUDE.mdとローカルCLAUDE.mdに、それぞれ何を書くかを整理します。
• スキル・サブエージェント時代の置き場所 — 長い手順をスキルへ切り出す判断や、サブエージェントのモデル固定の考え方を解説します。

CLAUDE.mdとは｜AIに渡すオンボーディングドキュメント

CLAUDE.mdは、Claude Codeに「このプロジェクトではどう振る舞うべきか」を教えるための設定ファイルです。まずは役割と、なぜ設計の考え方が要るのかを整理します。ここを押さえておくと、後半の分割パターンを選ぶ基準がぶれにくくなります。

プロジェクトのルールをAIに伝える仕組み

Claude Codeは、プロジェクトのルートに配置されたCLAUDE.mdを読み込み、その内容に基づいて応答スタイル、コーディング規約、禁止事項、ワークフローなどを適用します。人間のチームにおける「オンボーディングドキュメント」に相当し、新しいメンバーが入社したときに渡す「このプロジェクトのルール集」と同じ役割を、AIエージェントに対して果たします。

ゼロから書くのが負担な場合は、/initコマンドでコードベースを読ませて最初のCLAUDE.mdを生成できます（出典：Manage Claude's memory）。AIに叩き台を作らせ、チームの実情に合わない記述を人間が削って整えるという進め方が、取っ掛かりとしてはやりやすいと考えています。

1ファイルへの詰め込みが破綻する理由

プロジェクトの初期は、ルールをすべてルートのCLAUDE.mdに書いても問題なく回ります。ところがチームが増え、フロントエンド・バックエンド・インフラと担当領域が分かれてくると、ある領域にしか関係しないルールまで毎回すべて読み込まれるようになります。内容が長くなるほど、関係のないルールがコンテキストを占め、ルール同士の矛盾も見つけにくくなります。

これは、スプレッドシートで顧客管理をしていて、シートとタブが増えるほど「どれが最新の情報か」が分からなくなる状況とよく似ています。ルールが複数の会話や個人のメモ、口頭の申し送りに散らばっている状態も同じです。置き場所を決めて一元管理し、読み込ませる範囲を仕組みで絞ることが、CLAUDE.md設計の出発点になります。

README.mdとの役割の違い

README.mdは人間の開発者向けのドキュメントで、セットアップ手順や使い方を記載します。CLAUDE.mdはAIエージェント向けの設定ファイルで、コーディング規約や禁止事項を記載します。

両者は目的が異なるため、どちらか一方に統合するのではなく、それぞれ独立して管理することをおすすめします。

設定ファイルの読み込み優先順位と階層構造

Claude Codeは複数の設定ファイルを階層的に読み込みます。どのファイルがどの範囲に効き、どれが優先されるのかを把握すると、「全体に適用するルール」と「特定の領域にだけ適用するルール」を無駄なく設計できます。ここでは優先順位の一覧と、設計への生かし方を解説します。

優先順位の一覧

優先順位（後から読まれたものが上書き）は以下の通りです。

範囲が狭いものほど優先度が高い、と覚えておくと整理しやすくなります。全員に共通する原則は上位の広いファイルに、例外や領域固有の作法は下位の狭いファイルに置くのが基本です。

優先順位を設計に生かす考え方

優先順位を理解したうえで、ルールを書く前に「このルールは誰のどの作業に効くべきか」を決めてから置き場所を選びます。判断の分かれ目は次の通りです。

同じルールを複数の階層に書くと、片方だけ更新されたときに矛盾が生まれます。1つのルールは1か所にだけ書き、下位のファイルでは上位と異なる点だけを書き足す形にしておくと、メンテナンスの負担が小さくなります。

規模別の基本パターン｜個人開発からチーム開発まで

CLAUDE.mdは、プロジェクトの規模によって適した構成が変わります。ここでは個人開発向けの最小構成と、チーム開発向けの中規模構成を示し、どのタイミングで次の構成に移るかの判断基準をまとめます。いきなり完成形を目指すのではなく、今の規模に合う構成から始めることをおすすめします。

最小構成（個人開発・小規模プロジェクト）

個人開発やファイル数が少ないプロジェクトでは、ルートのCLAUDE.md1ファイルで十分です。

# プロジェクトルール

## 技術スタック

• Next.js / TypeScript / Supabase / Tailwind CSS

## コーディング規約

• 関数はアロー関数で統一
• コンポーネントはfunction宣言
• 型はinterface優先（typeは複合型のみ）
• エラーハンドリングはtry-catchで明示的に

## 禁止事項

• any型の使用禁止
• console.logを残さない（console.errorは可）
• .envファイルへの直接値書き込み禁止

## テスト

• テストフレームワーク: Vitest
• 新規関数にはユニットテストを作成する

この段階では、技術スタック・コーディング規約・禁止事項・テストの4つが書けていれば十分です。ルールが増えてきたら分割を検討します。

中規模構成（チーム開発）

チーム開発では、CLAUDE.mdの責務を分割して管理性を高めます。ルートには全体の地図と共通ルールだけを置き、領域ごとの詳細は.claude/rules/に分けます。

プロジェクトルート/

CLAUDE.md 全体ルール（簡潔に）

.claude/

rules/

frontend.md フロントエンド固有ルール

backend.md バックエンド固有ルール

testing.md テスト規約

security.md セキュリティルール

settings.json Hooks・権限設定

agents/ カスタムエージェント

reviewer.md

src/

app/

components/

ルートCLAUDE.mdの記述例は次の通りです。詳細を書き込まず、「どこに何があるか」と「詳細ルールの参照先」に絞っている点がポイントになります。

# プロジェクト概要

ECサイトのリニューアルプロジェクト。Next.js + Supabase構成。

## アーキテクチャ

• フロントエンド: Next.js App Router
• バックエンド: Supabase Edge Functions
• DB: Supabase PostgreSQL
• 認証: Supabase Auth

## ディレクトリ構造

• src/app/ → ページ・ルーティング
• src/components/ → UIコンポーネント
• src/lib/ → ユーティリティ・ヘルパー
• supabase/functions/ → Edge Functions
• supabase/migrations/ → DBマイグレーション

## 共通ルール

• TypeScript strict mode
• ESLint + Prettier準拠
• 詳細ルールは .claude/rules/ を参照

次の構成に移るタイミングの見極め方

構成を切り替える基準は、ファイル数よりも「ルールの効き方」で判断するほうが実態に合います。次のシグナルが出たら、1段階先の構成に移るタイミングです。

どのシグナルも出ていないうちは、分割しないほうが見通しを保てます。分割は目的ではなく、読み込む範囲を絞るための手段です。

インポートと.claude/rules/による分割設計

ルールが増えてきたときの分割には、2つの道具があります。1つはCLAUDE.mdから別ファイルを取り込むインポート、もう1つは.claude/rules/に置いたファイルをpaths指定で条件付きに適用する方法です。前者は「長いファイルを読みやすく割る」道具、後者は「関係のない場面では読み込ませない」道具と考えると使い分けやすくなります。

インポートの基本構文

CLAUDE.mdでは、@に続けてファイルパスを書くと、外部のMarkdownファイルを取り込めます。相対パスと絶対パスのどちらも使え、取り込んだファイルからさらに別のファイルを取り込むことも可能です。ただし再帰的なインポートは最大4ホップまでと公式ドキュメントに記載されており、コードブロックの中に書いた@は取り込みの対象になりません（出典：Manage Claude's memory）。

# プロジェクトルール

@.claude/rules/coding-standards.md

@.claude/rules/api-guidelines.md

@.claude/rules/deployment.md

Claude CodeがCLAUDE.mdを読み込む際に、参照されたファイルの内容がその位置に挿入されます。インポートの階層が深くなるほど、どのルールがどこから来たのかを追いにくくなります。取り込みはルートから1段までにとどめ、入れ子にしない運用をおすすめします。

インポートの分割パターン

分割の切り口は、チームの体制とルールの更新頻度で選びます。

重要度別分割を使う場合、ルートのCLAUDE.mdは次のような形になります。

# CLAUDE.md

## 最優先で守るルール

@.claude/rules/critical.md

## コーディング規約

@.claude/rules/coding-standards.md

## テスト規約

@.claude/rules/testing.md

## デプロイ手順

@.claude/rules/deployment.md

ただし、インポートしたファイルは結局すべて読み込まれます。読み込む量そのものを減らしたい場合は、次に紹介するpaths指定か、後述するスキルへの切り出しを使います。

pathsフロントマターによるスコープ制御

.claude/rules/配下のMarkdownファイルには、pathsフロントマターを指定することで、特定のファイルパスに対してのみルールを適用できます。pathsを書かないルールファイルは、条件なしでプロジェクト全体に読み込まれます（出典：Manage Claude's memory）。

paths:

• "src/components/"
• "src/app//page.tsx"

# フロントエンドコンポーネントルール

## コンポーネント命名

• PascalCase（例: UserProfile.tsx）
• ページコンポーネントは page.tsx 固定

## スタイリング

• Tailwind CSSのユーティリティクラスを使用
• カスタムCSSは components.css にまとめる
• !important 禁止

バックエンド側は、対象のディレクトリを変えて同じように書きます。

paths:

• "supabase/functions/"
• "src/lib/api/"

# バックエンドAPIルール

## Edge Functions

• レスポンスはJSON形式で統一
• エラーレスポンスは { error: string, code: number } 形式
• レートリミット: 設定ファイルから取得（ハードコード禁止）

pathsの動作原理

Claude Codeがファイルを操作（読み取り・書き込み・分析）する際、そのファイルパスがpathsの条件に一致する.claude/rules/ファイルのルールが適用されます。

ユーザー: 「src/components/Header.tsx を修正して」

Claude Codeの内部処理:

1. CLAUDE.md（全体ルール）を読み込み
2. src/components/ にマッチする rules/ をスキャン
3. frontend.md のルールが追加適用
4. 修正を実行

この仕組みにより、フロントエンド担当のルールがバックエンドのコードに誤って適用される——といった事故を防げます。globの書き方を誤ると、ルールがどのファイルにも当たらないまま気づかれずに残ります。paths付きのルールを追加したら、対象ディレクトリのファイルを1つ修正させ、そのルールに沿った出力になったかを見てからコミットする流れにしておくと、効いていないルールを早い段階で見つけられます。

モノレポの階層設計パターン

複数のプロジェクトが1つのリポジトリに同居するモノレポでは、CLAUDE.mdの階層設計が特に重要になります。全体共通のルールと、アプリやチームごとのルールが混ざると、ある領域の作法が別の領域に漏れ出すためです。ここでは階層の組み方と、実際の設計例を紹介します。

モノレポのCLAUDE.md階層

モノレポでは、ルートに全プロジェクト共通のルールを置き、各アプリ・パッケージのディレクトリにそれぞれのCLAUDE.mdを置きます。

monorepo/

CLAUDE.md 全プロジェクト共通ルール

.claude/

rules/

git-workflow.md Git運用ルール（全体共通）

security.md セキュリティルール（全体共通）

apps/

web/CLAUDE.md Webアプリ固有ルール

api/CLAUDE.md APIサーバー固有ルール

admin/CLAUDE.md 管理画面固有ルール

packages/

ui/CLAUDE.md UIライブラリ固有ルール

shared/CLAUDE.md 共有ユーティリティのルール

marketing/

blog/CLAUDE.md ブログ制作ルール

website/CLAUDE.md Webサイト管理ルール

Git運用やセキュリティのように、どのアプリでも同じ基準で守るものはルートに寄せます。反対に、UIライブラリの命名規則やブログの文体ルールのように、その領域の外では意味を持たないものは各ディレクトリに閉じ込めます。

実例: StartLink型モノレポの設計

CRMコンサルティングとブログ運営、プロダクト開発を1つのリポジトリで管理するケースを見てみます。次の図は、経営情報をディレクトリで整理した設計例です。strategyに戦略・目標、projectに顧客別の情報、.claudeにCLAUDE.mdやルール・memoryを置き、フォルダごとに役割を1行で注記しています。

ルートCLAUDE.md（共通ルール）:

# StartLink プロジェクト全体仕様書

## 会社基本情報

• 事業: CRM特化型コンサルティング、AI活用アドバイザリー

## 全体共通ルール

• 事例は実名のもののみ扱う（匿名の事例は書かない）
• 内部情報の外部公開禁止
• です/ます調で統一

## ディレクトリマップ

• 00_strategy/ → 経営戦略
• 01_marketing/ → マーケティング・ブログ
• 02_product/ → プロダクト開発

01_marketing/CLAUDE.md（マーケティング固有）:

# マーケティングルール

## ブログ記事制作

• 文字数・FAQ数の社内基準を満たす
• blog-reviewスキルでのレビューを通過してから公開する
• レビュー未実行での公開は禁止

02_product/CLAUDE.md（プロダクト固有）:

# プロダクト開発ルール

## 技術スタック

• Next.js / TypeScript / Supabase

## Git戦略

• main → feature/* → PR → main
• Vercel自動デプロイ

この設計により、Claude Codeが01_marketing/配下で作業するときはブログ制作ルールが、02_product/配下で作業するときはプロダクト開発ルールが適用されます。なお、Claude Codeを活用した経営データの可視化やコンテンツマーケティングの支援についても、具体的な取り組みをご紹介しています。

階層設計で迷いやすいポイント

モノレポで迷いやすいのは、「複数のアプリで使うが全体共通ではない」ルールの置き場所です。判断は次の順で進めると整理できます。

1. そのルールがすべてのディレクトリで成り立つかを考え、成り立つならルートに置く
2. 成り立たない場合、対象がディレクトリで区切れるなら各ディレクトリのCLAUDE.mdに置く
3. 対象がディレクトリをまたいでファイルパターンで決まる（例: すべてのテストファイル）なら、.claude/rules/にpaths付きで置く

どの形が合うかは、リポジトリの切り方やチームの体制によって変わります。汎用的な型をそのまま当てはめるより、自社のディレクトリ構成と担当範囲に沿って階層を決めることが、結構ミソになってくると考えています。

マネージドCLAUDE.mdとローカルCLAUDE.mdの使い分け

CLAUDE.mdには、自分だけに効く個人設定と、チーム全員に効くプロジェクト設定の2つのスコープがあります。両者を混ぜると、個人の好みがチームのルールとしてGitに入り込んだり、逆にチームの約束事が一部の人の手元にしか無かったりします。ここでは、それぞれに何を書くかを整理します。

2つのスコープの違い

公式ドキュメントでは、~/.claude/CLAUDE.mdはユーザー単位のメモリとして説明されており、組織の管理者がOSのシステム領域に配布する「マネージドポリシー」とは別のファイルです（出典：Manage Claude's memory）。本記事の「マネージド」は、自分の手元で管理する個人設定を指しています。

マネージドCLAUDE.mdに書く内容

個人設定には、プロジェクトをまたいで変わらない自分の好みだけを書きます。

# 個人設定

## 応答スタイル

• 日本語で応答
• コードコメントも日本語
• 省略せず正式名称で記述

## エディタ設定

• インデント: スペース2つ
• 行末: LF
• エンコーディング: UTF-8

## 好みの設定

• テスト作成時はエッジケースを多めに
• エラーメッセージは具体的に（何が・どこで・なぜ失敗したか）

インデントや行末のように、プロジェクト側でフォーマッターが決めている項目と重なる場合は、プロジェクト側を優先させます。個人設定でプロジェクトの規約を上書きしてしまうと、その人のPRだけ差分が崩れるためです。

ローカルCLAUDE.mdに書く内容

チーム共有のCLAUDE.mdには、誰が作業しても同じ結果にそろえたい事柄を書きます。

# プロジェクト固有ルール

## アーキテクチャ（チーム共有）

• ディレクトリ構造と各フォルダの責務
• 使用ライブラリとバージョン
• APIの設計方針

## コーディング規約（チーム共有）

• 命名規則
• エラーハンドリング方針
• コメント規約

## 禁止事項（チーム共有）

• 破壊的変更の禁止ファイル
• 直接変更禁止のブランチ

書くべきかどうか迷ったら、「新しく入ったメンバーが知らないと事故になるか」で判断します。事故になるならローカルに書き、好みの問題ならマネージドに回します。

CLAUDE.mdを育てる運用パターン

CLAUDE.mdは、書いて終わりの設定ファイルではありません。プロジェクトの成長とAIの振る舞いに合わせて、少しずつ育てていくものです。ここでは、段階的な拡張、ミスを起点にしたルール追加、コードレビューという3つの運用パターンを紹介します。

パターン1: 段階的に育てる

CLAUDE.mdは最初から完璧に書く必要はありません。プロジェクトの成長に合わせて段階的に拡充していくのが現実的です。

Before: プロジェクト開始時に長大なCLAUDE.mdを書こうとして挫折。

After: 短い内容からスタートし、「AIが間違えた箇所」を都度ルールとして追記。

CRMの項目設計で、使われない項目が大量に並ぶと入力する人の集中が削がれるのと同じで、CLAUDE.mdも使われないルールが増えるほど、効かせたいルールが埋もれます。最初は少なく始め、効いていることを確かめながら足していく順番をおすすめします。

パターン2: ミスドリブンでルールを追加

CLAUDE.mdにルールを追加するタイミングとして効果が出やすいのは、「AIが間違えたとき」です。

【ミス発生】

Claude Codeがconsole.logをプロダクションコードに残した

【ルール追加】

.claude/rules/coding-standards.md に以下を追記:

• console.logをプロダクションコードに残さない（console.errorのみ許可）

【再発防止の検証】

同じ種類のタスクを再実行し、ルールが適用されるかを見る

この「ミス、ルール追加、検証」のサイクルを回すことで、CLAUDE.mdが実践的なナレッジベースとして成長していきます。ここで役割を分けておくと運用が安定します。どのミスをルールにするか、そのルールがビジネス上妥当かを決めるのは人間の役割です。一方で、ミスの原因の洗い出しや、ルール文面の叩き台づくりはClaude Codeに任せられます。

ただし、ルールを足しても同じミスが繰り返される場合は、書き方ではなく仕組みで止めることを検討します。例えば、どうしても通したくない操作は、CLAUDE.mdの文章に頼るのではなくHooksや権限設定で実行そのものを止めるほうが、担当者が変わっても同じ結果になります。

パターン3: CLAUDE.mdのコードレビュー

CLAUDE.md自体もプロダクトコードと同様にコードレビューの対象とします。CLAUDE.mdをGit管理下に置き、変更はPR経由で行う流れにしておくと、ルールの変更履歴と理由がチーム全員から見えるようになります。

PR: 「CLAUDE.mdにAPI設計ガイドラインを追加」

レビュー観点:

• ルールが具体的か（「適切に」ではなく「try-catch で囲む」のように）
• 矛盾するルールがないか
• pathsのスコープが適切か
• 既存ルールとの重複がないか

この運用にしておくと、ルールが特定の人の頭の中ではなくリポジトリに残ります。新しく入ったメンバーも、CLAUDE.mdの履歴を追えば「なぜこのルールがあるのか」を自分で把握でき、担当者が交代しても同じ品質で開発を続けられます。

Skills・Agent Teams時代のCLAUDE.md設計

Claude Codeには、CLAUDE.md以外にも「指示の置き場所」が増えています。何をCLAUDE.mdに残し、何を外に出すか。この線引きが、そのまま設計の品質になります。

本記事は2026年8月時点の情報です。

カスタムコマンドはスキルに統合された

.claude/commands/deploy.mdと.claude/skills/deploy/SKILL.mdは、どちらも/deployを作り、同じように動きます。既存の.claude/commands/はそのまま動作し続けるので、急いで移行しなくても問題ありません。ただしスキル側には、補助ファイル用のディレクトリを持てること、frontmatterで呼び出し主体を制御できること、関連する場面でClaudeが自動的に読み込むこと、という3つの違いがあります（出典：Skills）（出典：Commands）。

これがCLAUDE.md設計に効いてきます。特定の作業のときだけ使う長い手順は、CLAUDE.mdに常駐させるのではなくスキルへ出すのが原則です。常時読み込まれるコンテキストが軽くなり、その手順を使わないセッションで無駄なトークンを払わずに済みます。Claudeに勝手に起動されたくない手順は、frontmatterにdisable-model-invocation: trueを書けば、ユーザーの明示呼び出しだけに限定できます。

常時ロードと必要時ロードで置き場所を分ける

ルートCLAUDE.mdは「地図」、.claude/rules/は「地域ごとのルール」、スキルは「作業手順書」と考えると迷いません。前述のインポートによる分割は「1ファイルを読みやすく割る」ための道具、スキルへの切り出しは「そもそも読み込ませない」ための道具で、目的が異なります。長い手順がCLAUDE.mdやインポート先にあるなら、まずスキルへの移し替えを検討してください。

サブエージェントにはモデルを明示的に固定する

サブエージェントは、modelを指定しないと親セッションのモデルをそのまま引き継ぎます。メインを上位モデルで動かしていると、実行役のサブエージェントまで同じ単価で回ることになり、コスト設計が静かに崩れます。CLAUDE.mdには「どの役割にどのモデルを充てるか」という方針を書き、エージェント定義側でも固定することをおすすめします。

## サブエージェント運用ルール

• 設計・レビュー・オーケストレーションはメインセッションで行う
• コーディング・ファイル操作・データ処理は原則サブエージェントに委任する
• 実行系サブエージェントは model を明示的に指定する（未指定だと親モデルを継承する）

エージェント定義ファイル側は、frontmatterで固定します。

name: bulk-editor

description: 大量のファイル編集を担当する

model: sonnet

isolation: worktree

isolation: worktreeを書くと、そのサブエージェントは常に専用のgit worktreeで動きます。変更なしで終了したworktreeは自動的に削除されるため、ファイルを大量に触る役割ほどこの1行の価値が高くなります。なお、auto mode（分類器に許可判断を任せるモード）で動かしている場合、frontmatterのpermissionModeは無視されます。権限をfrontmatterで緩める前提の設計にはしないでください（出典：Subagents）（出典：Worktrees）。

条件を満たすまで自律的に作業を続けさせる/goalを併用する場合は、CLAUDE.mdに検証コマンドを明記しておくと効果が上がります。/goalの判定役は会話に出ている内容だけで成否を判断するため、「npm testの結果を出力してから完了と宣言する」といった手順がルール化されているほど、条件成立を正しく判定できます。詳しくは/goalコマンドで条件達成まで自律実行させる方法で解説しています。

次の画面は、この節で触れたスラッシュコマンド/deploy・/goalと、検証に使うコマンドnpm testをターミナルに並べたものです。先頭の行は$ claude --versionという実行コマンドで、次の行に2.1.263 (Claude Code)というバージョン表示があります。/deploy・/goal・npm testの実行結果は表示していません。

Agent Teamsを前提にした書き方

Agent Teamsを有効にすると、複数のteammateがそれぞれ独立したコンテキストウィンドウで動きます。teammateも同じCLAUDE.mdを読むため、「誰が読んでも同じ判断になる書き方」の重要度が一段上がります。実務上は次の3点がポイントになってきます。

• 主語を「あなた」ではなく役割で書く（「実装担当は〜」「レビュー担当は〜」）
• ファイル所有権をルールとして明記する（同じファイルを2人が編集すると上書きが起きる）
• 「確認を取ってから進める」ルールは、確認先まで書く（リードなのか、人間なのか）

v2.1.178でTeamCreate/TeamDeleteツールは削除され、team_nameの指定も受理はされますが無視されるようになりました。古いCLAUDE.mdに「まずチームを作成して名前を付ける」という手順を書いている場合、その記述はもう不要です。有効化に使う設定はCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1の1つだけです（出典：Agent teams）。

Agent Teamsそのものの設定と運用はClaude Codeで複数AIエージェントを並列実行する方法で扱っています。

関連する仕組みとの組み合わせ

CLAUDE.mdは単独で完結する仕組みではなく、カスタムコマンド、Hooks、メモリと組み合わせて力を発揮します。それぞれの役割を分けておくと、「どこに書くか」で迷う時間が減ります。ここでは3つの仕組みとの分担を整理します。

カスタムコマンドとの関係

カスタムコマンド（.claude/commands/）はCLAUDE.mdを補完する仕組みです。CLAUDE.mdが「常に適用されるルール」なら、カスタムコマンドは「特定のタスクを実行するときのレシピ」です。CLAUDE.mdでプロジェクトの大方針を定め、カスタムコマンドで具体的な作業手順を定義する、という分担が効果的です。前述の通りカスタムコマンドはスキルに統合されているため、新しく作る手順はスキルとして置く形も選べます。

Hooksとの連携

Claude Code Hooksは.claude/settings.jsonで定義しますが、CLAUDE.mdにフックの概要と目的を記載しておくと、AIエージェントがフックの存在を認識したうえで作業を進められます。CLAUDE.mdは「こうしてほしい」というお願い、Hooksは「この操作の前後で処理を走らせる」という仕組みです。守られないと困るルールほど、文章ではなくHooks側で担保する設計に寄せることをおすすめします。

メモリ・コンテキストとの関係

CLAUDE.mdは「プロジェクトのルール」を定義し、メモリ・コンテキストは「セッションをまたいだ記憶」を保持します。CLAUDE.mdに書くのは「変わらないルール」、メモリに記録するのは「変化する状態や学習結果」です。進行中のタスクの状況や一時的な決定事項をCLAUDE.mdに書き足していくと、ルールと状態が混ざり、古い情報がいつまでも読み込まれ続けます。

よくある質問

Q1. CLAUDE.mdが長くなりすぎると、Claude Codeの性能に影響しますか？

CLAUDE.mdの内容はセッション開始時にコンテキストウィンドウに読み込まれるため、長くなるほどトークンを消費し、効かせたいルールも埋もれやすくなります。インポートで取り込んだファイルも読み込まれる点は変わりません。長くなってきたら、特定の領域にだけ効くルールをpaths付きの.claude/rules/に、特定の作業のときだけ使う手順をスキルに移し、常時読み込まれる量を減らしてください。

Q2. CLAUDE.mdとREADME.mdの違いは何ですか？

README.mdは人間の開発者向けのドキュメントで、セットアップ手順や使い方を記載します。CLAUDE.mdはAIエージェント向けの設定ファイルで、コーディング規約や禁止事項を記載します。両者は目的が異なるため、どちらか一方に統合するのではなく、それぞれ独立して管理するのが適切です。

Q3. .claude/rules/ のファイルに命名規則はありますか？

技術的な制約はありませんが、ファイル名から内容が推測できる命名をおすすめします。frontend.md、backend.md、testing.md、security.mdのように、ルールの対象領域をファイル名にするのが一般的です。番号プレフィックス（01-critical.md、02-standards.md）を使って優先度を明示するパターンもあります。

Q4. チームでCLAUDE.mdを共同編集する際のベストプラクティスは？

CLAUDE.mdをGit管理下に置き、変更はPR経由で行うことをおすすめします。CLAUDE.mdの変更は「プロジェクトのルール変更」に等しいため、チームメンバー全員がレビューできるフローにしておくと、変更の理由が履歴として残ります。特に禁止事項やセキュリティルールの変更は、テックリードの承認を経る運用にしておくと安全です。

まとめ

CLAUDE.mdの設計は、プロジェクト規模に応じて段階的に進化させるのが現実的なアプローチです。小規模プロジェクトではルートに1ファイル、中規模では.claude/rules/による分割とpathsスコープ制御、大規模モノレポではディレクトリごとのCLAUDE.md階層を組み合わせます。そのうえで、特定の作業のときだけ使う長い手順はスキルへ切り出し、常に読み込まれる量を小さく保ちます。

マネージドCLAUDE.md（個人設定）とローカルCLAUDE.md（プロジェクト共有）を使い分け、ミスが発生するたびにルールを追加する「ミスドリブン」の運用を回すと、CLAUDE.mdは特定の人に依存しないチームのナレッジとして育っていきます。

まずは、今あるCLAUDE.mdを「常に効かせたいルール」と「特定の場面でだけ効けばよいルール」に仕分けることから始めてみてください。

1. 現在のCLAUDE.mdの各ルールに、効かせたい範囲（全体・特定ディレクトリ・特定ファイル・特定作業）をメモする
2. 特定の範囲にだけ効くルールを1つ選び、paths付きの.claude/rules/またはスキルに移す
3. 次にClaude Codeが間違えたときに、そのミスをルールとして追記し、PRでチームに共有する

Claude Codeの全コマンド一覧はClaude Codeチートシートをご覧ください。AI活用の全体像はAI活用完全ガイドで解説しています。

CRMを活用した業務効率化やAIとの連携に関するご相談は、StartLinkまでお気軽にお問い合わせください。

あわせて読みたい

• Claude Code × Stitchでワイヤーフレーム・UIデザインを自動生成する方法
• Claude Code × Chrome DevTools連携｜WebアプリのライブデバッグをAIで効率化する
• Claude Code MCP連携の始め方｜HubSpot・freee・Slackを接続する設定手順【2026年版】