CLAUDE.md テンプレ3種｜Web/ライブラリ/CI

Claude Codeで迷わず使えるCLAUDE.mdを作るには、最初にテンプレートを書くより、保存場所が ./CLAUDE.md か ./.claude/CLAUDE.md か、どの順で読まれるのか、そして /init・hooks・skills・rules が何を担当するのかを整理しておくのが近道です。
この記事は、Webアプリ、ライブラリ、CI のどれに当てはまるかを先に選び、そのまま貼れる形で最小構成を整えたい人に向けています。
筆者は /init 直後の素体に技術スタックと主要コマンドだけを足す運用にすると、初日から誤解や聞き返しが目に見えて減る感覚を何度も持ってきました。
Claudeの記憶の仕組みはClaude があなたのプロジェクトを記憶する方法整理されています。
なお「root は短く保ち、80行を超えたら分割する」という表現はコミュニティの実務目安であり、ない点にご注意ください。

CLAUDE.md とは何か、まず押さえるべき前提

役割と位置づけ

CLAUDE.mdは、Claudeに対して永続的な指示を与えるための Markdown ファイルです。
各セッションの開始時に読み込まれ、会話のたびに毎回説明し直さなくてよい前提をまとめた、AI 向けのプロジェクトメモリとして機能します。
プロジェクト直下の ./CLAUDE.md または ./.claude/CLAUDE.md に置けること、上位ディレクトリの内容は起動時に読み込まれることが整理されています。

ここで入れるべき内容は、人が読む説明文ではなく、そのプロジェクトで毎回ぶれずに守ってほしい前提です。
たとえば技術スタックなら『React』『TypeScript』Node.jsExpressPostgreSQLのような採用技術を明示し、主要コマンドなら開発起動・テスト・ビルド・Lint の入り口を書く、ディレクトリ構造なら frontend/ と backend/ の責務を分けて示す、といった具合です。
さらに設計方針として「API 呼び出しは repository 層を経由する」「状態管理は TanStack Queryを優先する」などの判断軸を載せ、DO/DON'T では「既存の認証フローを飛ばして実装しない」「JWT の検証を省略しない」のような禁止事項まで書いておくと、提案の方向が揃います。
テスト方針も同じで、Jestを単体テスト、Playwrightを E2E に使うなら、その住み分けを書いておくほうが、修正提案がテスト設計と噛み合います。

逆に、入れないほうがよいものもはっきりしています。
たとえば「親切で前向きに振る舞う」「ていねいに説明する」といった人格指示は、プロジェクト固有の記憶ではありません。
インデント幅や引用符の種類のように、ESLint や Prettier、Biome などの設定で機械的に担保できる整形ルールも、ここに長々と書くと本来読ませたい規範が埋もれます。
README と同じセットアップ説明を再掲するのも同様です。
筆者自身、最初は README と重複した説明をそのままCLAUDE.mdに入れていましたが、そこを削って技術スタックと「やってはいけないこと」だけに絞ったところ、Claudeの提案が設計方針から外れにくくなりました。
情報量を増やすより、判断の芯を残すほうが効きます。

Claude があなたのプロジェクトを記憶する方法 - Claude Code Docs

CLAUDE.md ファイルで Claude に永続的な指示を与え、自動メモリで Claude が自動的に学習を蓄積できるようにします。

code.claude.com

README.md との違い

見た目はどちらも Markdown なので、README.mdの短縮版として考えたくなりますが、役割は違います。
README.mdは人間向けの入口で、プロジェクトの概要、セットアップ手順、背景説明、利用例を含めて読ませる文書です。
一方のCLAUDE.mdは AI が参照する運用メモなので、冗長な導入や背景説明よりも、広く適用される規範と設計判断を優先します。

たとえばREADME.mdには「このサービスは何を解決するのか」「初回セットアップはどう進めるか」「ローカルで必要なミドルウェアは何か」といった説明が向いています。
対してCLAUDE.mdに向いているのは、「フロントエンドは 『React』、サーバーは Express」「API のエラー形式はこの形に揃える」「DB マイグレーションなしでスキーマを直接変更しない」「テスト追加なしでロジック変更を終えない」といった、実装中の判断に効くルールです。
人には親切でも、AI にとってはノイズになる文がある、という切り分けです。

CLAUDE.mdは短く保ち、広く適用される内容だけを書く方針が示されています。
この考え方に沿うと、README にある長い背景説明や画面遷移の紹介文をコピーする必要はありません。
むしろ重複が増えると、どちらを更新すべきかが曖昧になり、AI にも人間にもメンテナンス負荷が返ってきます。

また、毎回必ず発生させたい処理はCLAUDE.mdの指示ではなく hooks に任せる、たまにしか使わない専門知識やワークフローは skills に分ける、という線引きも README との違いを考えると整理しやすくなります。
CLAUDE.mdは「読むべき規範の中核」、hooks は「必ず実行する仕組み」、skills は「必要なときに呼び出す専門手順」です。
この役割分担ができていると、1つのファイルに何でも抱え込まずに済みます。

React

React is the library for web and native user interfaces. Build user interfaces out of individual pieces called component

react.dev

プロジェクト記憶の範囲

Claudeの記憶には、少なくともプロジェクトスコープと、それより広いユーザーや組織のスコープがあります。
この記事で中心に扱うのは、ワークスペースに置くプロジェクト用のCLAUDE.mdです。
ここには、そのリポジトリで共通して使う技術スタック、主要コマンド、ディレクトリ構造、設計方針、DO/DON'T、テスト方針のような、コード変更時に毎回参照される前提を入れるのが筋です。

プロジェクトスコープの記憶は、対象リポジトリの事情に密着しています。
モノレポであれば root に全体方針を書きつつ、frontend/CLAUDE.md や backend/CLAUDE.md のようにサブディレクトリ側へ分ける運用が噛み合います。
上位のCLAUDE.mdは起動時に読み込まれ、サブディレクトリ側のファイルはその領域を読むときに追加で参照されるため、共通ルールと局所ルールを分離できます。
たとえば root には「全体で 『TypeScript』を使う」「公開 API は後方互換を崩さない」「CI では非対話モード前提」と書き、frontend/ には 『React』と Playwright中心の指針、backend/ には Expressと PostgreSQL中心の制約を書く形です。

一方で、ユーザーや組織スコープの記憶には、複数プロジェクトにまたがる共通の作法が入ります。
たとえば「コミットメッセージの基本方針」や「社内で共通のレビュー観点」のような内容は、個別プロジェクトより上の層に置くほうが自然です。
ただし、この記事でテンプレート化したいのは、あくまでリポジトリ単位で効果が出る記述です。
毎回の実装判断に直結する情報をプロジェクト側へ寄せ、どの案件にも当てはまる一般論は上位スコープや別の仕組みに逃がすほうが、ファイル全体の密度を保てます。

この範囲感を押さえておくと、「何を入れて何を外すか」の判断がぶれません。
プロジェクトのCLAUDE.mdは、そのコードベースでClaudeが迷わないための地図です。
人格設定や整形ルールの再掲ではなく、その地図にないと実装が逸れる項目だけを残す、という発想で見ると、テンプレートも過不足なく組み立てられます。

置き場所・読み込み順・分割ルール

保存場所と優先順位

CLAUDE.md を置く場所は、まず プロジェクトルートの ./CLAUDE.md または ./.claude/CLAUDE.md のどちらかです。
運用上の違いは「どちらが強いか」ではなく、リポジトリ直下に見せるか、設定ファイル群として .claude 配下にまとめるかの整理軸だと考えると把握しやすくなります。

実際の設計では、ルートに1枚だけ置いて全体方針を書くところから始めると混乱が少ないです。
たとえば ./CLAUDE.md には、React と Node.js を採用していること、主要コマンド、レビュー時に避けたい変更、テストの基本方針だけを書きます。
そのうえで、ルート直下に見せたくない場合や .claude 配下に関連ファイルをまとめたい場合は ./.claude/CLAUDE.md に寄せる、という順で考えると設計がぶれません。

優先順位の考え方で押さえたいのは、上位ディレクトリの CLAUDE.md が土台になり、必要に応じて下位ディレクトリの CLAUDE.md がその文脈を補うということです。
つまり、ルートには全体共通のルールだけを書き、frontend や backend のような配下には、その領域でだけ効く差分を書くのが基本形です。
ここで Web 固有の規約を root に詰め込みすぎると、API 修正の場面でもフロント前提の提案が混ざります。
筆者は frontend/CLAUDE.md と backend/CLAUDE.md を分けてから、Web 依存の規約がバックエンドに干渉しなくなり、誤提案が目に見えて減りました。

なお、条件付き適用の仕組みとして rules の paths frontmatter や、subagent ごとのメモリも使えます。
そのあたりの詳細も整理されています。
ただ、この段階ではまず「root は共通、下位は差分」という基本設計を固めたほうが運用が安定します。
最初から条件分岐を増やすより、ディレクトリ単位で責務を切り分けたほうが、どこに何を書くべきか判断しやすくなります。

読み込みタイミングの仕様

読み込み順は、置き場所の設計とセットで理解しておく必要があります。
ワーキングディレクトリより上位にある CLAUDE.md は、Claude Code の起動時にまとめて読み込まれます。
一方で、下位ディレクトリにある CLAUDE.md は、その配下のファイルを読むときにオンデマンドで読み込まれます。
この挙動を知らないまま分割すると、「書いたのに効いていない」と感じる場面が出やすいんですよね。

たとえばリポジトリルートで Claude Code を起動し、最初に backend/src/routes/user.ts を開いた場合は、ルートの CLAUDE.md に加えて backend/CLAUDE.md が必要になった時点で参照されます。
逆に、フロントエンドだけを見ているセッションでは frontend/CLAUDE.md が読み込まれても、backend/CLAUDE.md の内容まで常に抱えるわけではありません。
この仕組みのおかげで、モノレポでも全ルールを毎回最初から押し込まずに済みます。

この挙動に合わせると、ルートには「どこでも効く判断」だけを置くのが筋が通ります。
たとえば pnpm test や docker compose up のような共通コマンド、ディレクトリ構成、共通の禁止事項は root に置きます。
API レイヤーのエラー設計や PostgreSQL のマイグレーション原則は backend/CLAUDE.md、React Query や Sentry の扱いは frontend/CLAUDE.md に分けると、実際の読み込みタイミングとも一致します。

もう1つ見落としやすいのが、オンデマンド読み込みは便利ですが、何を書いても後から都合よく効くわけではないという点です。
対象ディレクトリに入る前提が曖昧だと、Claude の初動は root の情報だけで決まります。
だからこそ、最初の判断に影響する内容は root に置き、詳細ルールは下位に寄せる、という線引きが必要です。
設計の境界と読み込みタイミングが一致していると、Claude の提案も階層ごとに自然に切り替わります。

モノレポ/大規模の分割例

モノレポや大規模プロジェクトでは、1枚の CLAUDE.md に全部書くより、ルートで共通方針を定義し、各サブディレクトリで専門ルールを持つ形がまとまりやすいのが利点です。
具体例としては、root の CLAUDE.md には共通設計方針と主要コマンドだけを書きます。
ここには「パッケージ管理は pnpm」「変更後は関連テストを回す」「破壊的変更は避ける」といった全体方針を置きます。

そのうえで、frontend/CLAUDE.md には React、TypeScript、Sentry、Playwright まわりの規約を書きます。
たとえば状態管理の方針、UI コンポーネントの責務、E2E テストの置き場、監視イベントの扱いなどです。
backend/CLAUDE.md には Express、PostgreSQL、JWT、Jest まわりのルールをまとめます。
API の命名規則、DB マイグレーション時の原則、認証ミドルウェアの扱い、テスト粒度などがここに入ります。
この分け方だと、フロントの JSX 規約やブラウザ前提の話が API 実装に混ざりにくくなります。

さらにファイル種別ごとの細分化が必要なら、.claude/rules/ を併用する構成もあります。
たとえば .test.ts にはテストの書き方、.sql には migration の制約、*.tsx には UI 実装の注意点を当てる、といった分割です。
rules は条件付き適用に向いていますが、ここでも先に root とディレクトリ単位の責務分離を作っておくと、rules が補助線として機能します。
逆に土台が曖昧なまま rules を増やすと、どのルールが本体なのか見えにくくなります。

実際に組んでみると、root は「全員共通の交通ルール」、frontend/CLAUDE.md と backend/CLAUDE.md は「専門エリアの運転ルール」という関係にすると整理しやすいのが利点です。
そこへ .claude/rules/ でファイル種別別の注意点を足すと、モノレポでも情報の置き場がぶれません。
大規模になるほど、1つの長文ファイルで統制するより、読み込まれる範囲に合わせて小さく分けたほうが Claude の判断も安定します。

まずは /init で作り、足りない部分だけ手で直す

/init の役割

CLAUDE.md を最初から手で書こうとすると、何をどこまで入れるべきかで止まりがちです。
そこで出発点にしたいのが /init です。
触れられている通り、/init はコードベースを分析して、スターターの CLAUDE.md を生成できます。
まず土台を自動で作り、足りないところだけ人間が補う、という順番にすると、ゼロからの空白に向き合わずに済みます。

この流れに変えてから、私の中では導入のハードルが一気に下がりました。
とくに効果があったのは、/init の生成物を5分だけ整える運用に固定したということです。
最初にスタック名と主要コマンドの穴だけ埋める、と決めたら迷いが消えて、その日のうちに PR に載せられました。
最初から完成版を目指すより、Claude が最低限踏み外さない状態を先に作るほうが、チームへの導入は前に進みます。

/init が便利なのは、リポジトリを読んだうえで雛形を出してくれる点です。
たとえば React と TypeScript のフロントエンド、Express と PostgreSQL のバックエンド、Jest や Playwright のテスト構成があるプロジェクトなら、その存在を踏まえたたたき台が手に入ります。
空の Markdown に向かって「技術スタック」「コマンド」「注意点」と見出しを並べる作業から始める必要はありません。

Claude Code のベストプラクティス - Claude Code Docs

環境設定から並列セッションでのスケーリングまで、Claude Code を最大限に活用するためのヒントとパターン。

code.claude.com

生成後に足す項目

自動生成のあとで追記する内容は、広げすぎないほうが安定します。
足すのは、Claude が毎回判断に使う情報だけで十分です。
具体的には、このプロジェクトの技術スタック、日常的に使う主要コマンド、ディレクトリ構造の要点、設計上の DO / DON’T までに留めるのが収まりどころです。

たとえば Web アプリなら、「フロントエンドは React と TypeScript、バックエンドは Node.js と Express、DB は PostgreSQL」といった基本情報を載せます。
開発は pnpm dev、テストは pnpm test、E2E は Playwright、frontend/ と backend/ で責務を分ける、API 変更時は互換性を崩さないといった運用ルールも欠かせません。
ライブラリなら公開 API と SemVer の扱い、CI 用途なら非対話で実行するコマンドや失敗条件のほうが前に出ます。
ここで長い API 仕様書や formatter の細則まで入れると、Claude に毎回渡す情報としては重くなります。

Claude があなたのプロジェクトを記憶する方法にある考え方とも一致しますが、CLAUDE.md はプロジェクトの記憶の中核であって、あらゆる資料置き場ではありません。
毎回は使わない業務知識や、特定の作業でだけ参照する長い説明は skills 側に逃がしたほうが整理できます。
ルートの CLAUDE.md には、開いた瞬間の判断を決める骨格だけを残す。
この切り分けができると、生成物に少し手を入れるだけで実戦投入できます。

短文化の見直し基準

追記したあとに必ずやりたいのが、各行を「これを削除すると Claude は間違うか」で見直すということです。
答えが「別になくても困らない」なら、その行はたいてい削れます。
この基準で読むと、親切心で足した背景説明や、毎回は使わない運用メモが見えてきます。
短く保つ目的は見た目の美しさではなく、Claude に渡す判断材料を濁らせないということです。

実務では、ルートの CLAUDE.md が80行前後に収まっていると扱いやすい、というコミュニティの目安があります。
テンプレート集では60行未満を良いベンチマークとする例もあり、80行を超えたら分割を検討する運用も見かけます。
一方で、公式が強調しているのは行数の固定値より、「短く、広く適用される内容だけを書く」という方針です。
ここは分けて理解したほうがぶれません。
80行前後は現場の運用目安、公式の軸は内容の選別基準です。

この基準で見ると、たとえば「React Query の細かなキャッシュ戦略」や「Sentry のノイズ除去パターン」は、フロントエンド作業でだけ必要なら frontend/CLAUDE.md や skills に寄せるほうが筋が通ります。
Jest の CI 並列数のような一部の文脈でしか使わない調整も同じです。
逆に、「Node.js は LTS 系を使う」「破壊的変更は避ける」「主要コマンドはこれ」という情報は、削ると初動の提案がぶれやすくなります。
短文化は情報を減らす作業というより、Claude が誤る分岐だけを残す編集だと考えると運用しやすくなります。

含めるべき情報

良いCLAUDE.mdは、Claude が最初の数ターンで判断を外さないための骨格だけを置いた文書です。
ここで先に決めたいのは、何でも書くことではなく、毎回参照される情報だけを残すということです。
具体的には、技術スタック、主要コマンド、ディレクトリ構造、設計方針、DO / DON’T、テスト方針の6点が中心になります。
これらが揃うと、Claude は「どのランタイムで動くのか」「どのコマンドが正なのか」「どこを触ると責務をまたぐのか」を初手で判断できます。

技術スタックは、単に『React』『TypeScript』Node.jsと名前を並べるだけでは足りません。
Web アプリなら、フロントエンドは『React』と『TypeScript』、API はExpress、DB はPostgreSQL、E2E はPlaywright、単体テストはJestといった具合に、役割とセットで書くと効きます。
Claude は同じ JavaScript 系でも、ブラウザ側とサーバ側で前提を切り替える必要があるので、「何をどこで使っているか」が見えているだけで提案の精度が変わります。

主要コマンドも、日常的に叩くものに絞って明記したほうが安定します。
dev、test、build、lint、format、deploy のように、開発から検証、出荷までの流れが一通りわかると、Claude が存在しない npm script を捏造しにくくなります。
前のセクションでも触れた通り、/init の生成物にこの部分だけでも埋めると初動が締まります。
実際、不要な口調や整形ルールを削って、設計判断の根拠だけを残した形に寄せてからは、Claude がどこで迷っているのかが見えやすくなり、無関係な提案が混ざる頻度も目に見えて減りました。

ディレクトリ構造は、全階層の目録ではなく、責務の切れ目がわかる粒度で十分です。
たとえば frontend/ は UI、backend/ は API、shared/ は共通型、docs/ は人間向け資料、scripts/ は運用用スクリプト、といった整理です。
ここがないと、Claude は src/ の中を広く探し回ったり、共通コードとアプリ固有コードを混ぜたりしがちです。

設計方針は、抽象論よりも判断規則として書くのが向いています。
層分離を守る、命名規則を揃える、例外は握りつぶさず明示的に返す、API 呼び出しは特定の client 層を通す、といった内容です。
短く保ちながら広く適用できるルールを置く考え方が一貫しています。
つまり、「このリポジトリでは何を正解とするか」を短文で揃えることが、長い説明文より効きます。

DO / DON’T は、その設計方針を実装判断に落としたものです。
たとえば「新規 API は既存のエラーレスポンス形式に合わせる」「Sentryへの通知は共通ラッパー経由で送る」「DB に直接アクセスする処理を React コンポーネントへ書かない」といった具合です。
テスト方針も同様で、単体テストはJest、主要フローの E2E はPlaywright、API 変更時は後方互換を壊さないケースを先に追加する、のように役割分担まで示すと実務で使えるルールになります。
Playwrightは Chromium、Firefox、WebKit の3エンジンをカバーできるので、ブラウザ差分をまたぐ確認は E2E 側に寄せる、と書いておくとテストの置き場所までぶれません。

避けるべき情報

逆に削ったほうがよいのは、Claude の判断を良くしない情報です。
代表的なのが人格や口調の指示です。
「丁寧に話す」「フレンドリーに説明する」といった文面は、記事や対話のトーンには効いても、コード変更の正しさには結びつきません。
ルートのCLAUDE.mdに置くと、毎回読む情報としては重いわりに、設計判断の助けになりません。

整形ルールも、フォーマッタやリンタで代替できるものは外して構いません。
インデント幅、クォートの種類、末尾セミコロン、import 順といったルールは、PrettierやESLint、言語ごとの formatter が担う領域です。
CLAUDE.mdに同じ内容を書くと、設定ファイルと二重管理になります。
ズレが出ると、Claude はどちらを優先すべきか迷います。

長文の仕様書をそのまま写すのも避けたいところです。
API 仕様全文、認証フローの背景説明、業務ドメインの長い手順書を貼り込むと、文書は厚くなりますが、初動の判断材料としてはむしろ濁ります。
必要な場合は要点だけ残し、詳細は skills や docs/ に逃がすほうが構造としてきれいです。
メモリは置き場所ごとに役割を分けて扱う前提になっています。
この仕組みに合わせるなら、ルートには横断ルール、詳細は下位ディレクトリや補助機能へ、という分担が自然です。

重複情報も削除対象です。
package.json にある scripts をそのまま全列挙し、さらに README の説明も書き、同じ注意点を別の段落でも繰り返すと、読むコストだけ増えます。
私が見直しで真っ先に消すのはこの重複です。
不要な口調や整形ルールを落として、設計判断の根拠だけを残す形にすると、Claude が「何を守るべきか」を拾いやすくなります。
読み物としての親切さより、判断の分岐点が見えることのほうが効きます。

時々しか使わないワークフローも、ルートからは外したほうが収まりが良いです。
半年に一度のリリース手順、障害対応時だけ使う復旧スクリプト、特定の CI ジョブ向けの詳細な JSON スキーマなどは、普段の編集タスクとは距離があります。
こうした情報を常設すると、普段の開発タスクでも余計な文脈が流れ込んできます。
必要なときだけ呼び出せる skills や、対象ディレクトリに置く個別のCLAUDE.mdへ分けるほうが、全体の見通しを保てます。

実務では、ルートの CLAUDE.md が80行前後に収まっていると扱いやすい、というのはコミュニティで共有されている目安です（公式が行数を固定しているわけではありません）。
テンプレート集では60行未満を良いベンチマークとする例もあり、80行を超えたら分割を検討する運用が多く見られます。
ここでは「短く、広く適用される内容だけを書く」という原則を優先してください。

3種テンプレの比較要点

テンプレート選びで見たいのは、見た目の違いより、何を最優先で固定する設計かです。
Web アプリ向け、ライブラリ向け、CI 向けでは、同じCLAUDE.mdでも中心に置く情報が変わります。

Web アプリ向けテンプレートは、横断設計を一箇所にまとめる役割が強めです。
フロントエンドが『React』、API がExpress、DB がPostgreSQL、レイヤーが分かれていると、Claude は部分最適の提案をしがちです。
そこで、ルートには「どの層が何を持つか」「命名はどう揃えるか」「エラー処理をどこで統一するか」「API 呼び出しはどの client を通すか」を置きます。
各レイヤーの細部は frontend/CLAUDE.md や backend/CLAUDE.md に分ける構成と相性が良く、ルートは横断ルールのハブとして機能します。

ライブラリ向けテンプレートでは、公開 API と互換性維持が中心です。
ここでは「内部実装をどう書くか」より、「外に見える契約をどう守るか」が前に出ます。
公開関数、エクスポート面、examples、ドキュメント、テスト、リリース方針が主役です。
SemVerの定義に沿って、破壊的変更は MAJOR、下位互換を保った機能追加は MINOR、互換を保った修正は PATCH という線引きを明文化しておくと、Claude が安易に API シグネチャを変える提案を出しにくくなります。
ライブラリでは「最小依存を守る」「公開型を無断で変えない」「examples とテストを一緒に更新する」といった DON’T が効きます。

CI 向けテンプレートは、さらに性格が違います。
対話で相談しながら進める前提ではなく、非対話で、再現可能で、安全な範囲だけを操作させる文書です。
実行コマンド、失敗条件、出力形式、権限制限を明記し、JSON 出力が必要ならその形式も固定します。
GitHub Actions で流すなら、何を実行してよくて、どこを書き換えてよくて、何に触れてはいけないかまで書いたほうが事故を防げます。
ここでは「allowedTools の範囲」「非対話モード前提」「標準出力は JSON」「危険な変更は禁止」といったルールが、Web やライブラリ以上に重要になります。

この違いを一目で掴むなら、次の整理が実務で使えます。

3種類に共通しているのは、情報量の多さではなく、判断基準の明確さです。
どのテンプレートでも、Claude が迷う分岐にだけ印を付けるように設計すると、文書は短くても機能します。
反対に、人格、整形、長文仕様、重複メモが前に出ると、テンプレートの違い以前にノイズが勝ってしまいます。
ここが整理できていると、次にテンプレートを選ぶ段階でも、どこをそのまま使い、どこを自分のリポジトリ向けに削るべきかが見えてきます。

テンプレート1: Webアプリ向け CLAUDE.md

こういう人におすすめ

このテンプレートは、小規模から中規模の SPA と API を同じリポジトリで運用していて、まずは最小限の分割で整えたい人に向いています。
フロントエンドが『React』、API がNode.jsとExpress、DB がPostgreSQL、認証に JWT か Session を使い、テストはJestとPlaywright、配備はDocker経由でクラウドへ、という構成なら、そのまま土台として使えます。

向いているのは、情報を増やしたい人ではなく、Claude が迷う判断だけを先に固定したい人です。
『Claude があなたのプロジェクトを記憶する方法』でも、プロジェクトメモリは短く保ち、階層ごとに分けていく前提が見えます。
Web アプリではとくに、画面実装、API 実装、DB 変更、認証、運用の境界が同時に出てくるので、個別の知識より「どこまでをルートに書くか」の判断がそのまま提案品質に出ます。

私自身、Web 向けのテンプレートに API 通信は『React Query』、エラーハンドリングは Toast、ログ収集はSentryまで書いたところ、フロントエンド側の提案が急に揃いました。
以前は fetch を直接書く案と独自 hook を増やす案が混ざり、失敗時の UI も console.error 止まりになりがちでしたが、通信と障害対応の通り道を明文化すると、修正提案の粒度が安定します。
逆に、人格指示や細かい整形ルールまで抱え込むと、Web アプリ向けテンプレートの芯がぼやけます。

テンプレ全文

以下は、React / Node / Express / PostgreSQL を前提にした、コピーしてそのまま起点にできる最小構成のテンプレートです。

# CLAUDE.md

## 目的
このリポジトリは Web アプリケーションです。
Claude は実装時に、見た目だけでなくフロントエンド、API、DB、認証、テスト、デプロイまで含めた整合性を優先してください。
新規コードは既存方針に合わせ、層をまたぐ変更では影響範囲を明示してください。

## 技術スタック

- Frontend: React + TypeScript
- API: Node.js + Express
- Database: PostgreSQL
- Auth: JWT または Session
- Unit/Integration Test: Jest
- E2E Test: Playwright
- Deploy: Docker + Cloud environment
- Error tracking / logging: Sentry
- Server state fetching: React Query（TanStack Query / @tanstack/react-query）

## ディレクトリ

- `frontend/`: React アプリケーション
- `backend/`: Express API、認証、DB アクセス
- `backend/db/` または `backend/migrations/`: スキーマ・マイグレーション
- `shared/`: フロント/バックで共有する型やユーティリティ
- `docs/`: ADR、設計メモ、運用ドキュメント
- `infra/` または `docker/`: Docker / deployment 関連定義
- `e2e/`: Playwright テスト

## 主要コマンド

> [!WARNING]
> 以下は典型的な命名例です。実際のリポジトリでは `pnpm` や `yarn` を使っていたり、`package.json` の `scripts` 名が異なることが頻出します。必ず実際の `package.json` を確認してコマンド名を合わせてください。

- 依存インストール: `npm install`
- 開発起動: `npm run dev`
- フロント起動: `npm run dev:frontend`
- API 起動: `npm run dev:backend`
- テスト: `npm test`
- 単体/結合テスト: `npm run test:jest`
- E2E テスト: `npm run test:e2e`
- Lint: `npm run lint`
- Typecheck: `npm run typecheck`
- Build: `npm run build`
- DB migration: `npm run db:migrate`
- Docker build: `docker build -t app .`

## アーキテクチャ設計方針

### Frontend

- UI コンポーネントは表示責務に寄せ、データ取得や副作用を過度に持たせない
- API 通信は React Query（TanStack Query / @tanstack/react-query）を標準とし、直接 `fetch` を各コンポーネントに書かない
- Server state と local UI state を分離する
- フォーム、一覧、詳細、モーダルで責務を分ける
- 再利用前提の UI は `components/`、画面単位の実装は `features/` や `pages/` に分ける
- エラー表示はユーザー通知（Toast 等）と開発者向けログを分ける

### Backend

- Express の route / controller / service / repository の責務を分離する
- route は入力受付、controller は HTTP 入出力、service は業務ロジック、repository は DB アクセスを担当する
- DB アクセスを controller に直接書かない
- 認証・認可・監査ログは middleware または専用層で扱う
- 非同期エラーは握りつぶさず、共通エラーハンドラへ渡す

### API

- JSON API を基本とする
- リクエスト/レスポンスの型を明示する
- エラー形式は統一する
- 破壊的な API 変更では既存クライアント影響を確認する
- 一覧系 API は filter / sort / pagination の仕様を明確に保つ
- フロントが必要とするデータ整形を API 側で過不足なく提供する

### DB

- PostgreSQL を正とする
- スキーマ変更は手作業で本番反映せず migration 経由で管理する
- 外部キー、ユニーク制約、インデックスを前提に設計する
- JSONB の利用は柔軟性が必要な箇所に限定し、基幹データは正規化を優先する
- N+1 クエリを避ける
- 命名規約はテーブル名・カラム名・インデックス名で統一する

### 認証

- JWT 採用時は署名方式を固定し、検証を厳密に行う
- Access token は短命、長期セッションは refresh 戦略または安全な session 管理で扱う
- Session 採用時は Cookie 属性、失効、CSRF 対策を前提にする
- 認証と認可を混同しない
- ユーザー ID、権限、監査対象操作を追跡できる形で実装する

## エラー・ロギング

- ユーザーに見せるメッセージと内部ログを分離する
- 例外は握りつぶさず、API では共通エラーレスポンスへ変換する
- フロントの失敗通知は Toast 等で一貫させる
- 障害調査用のログ・例外収集は Sentry に集約する
- 個人情報や秘密情報をログに出力しない

## テスト方針

- Jest で unit / integration テストを実施する
- Playwright で主要ユーザーフローの E2E をカバーする
- バグ修正時は再発防止テストを追加する
- UI の見た目だけでなく、権限、認証、例外系、API エラー時の挙動を確認する
- DB を伴うテストは seed / migration 前提で再現可能にする
- 不安定な時間依存・外部依存テストは固定化またはモック化する

## デプロイ

- Docker build が通る状態を保つ
- 環境差分は環境変数で管理し、コードに埋め込まない
- 開発・ステージング・本番で設定を分ける
- DB migration の適用順序をデプロイ手順に含める
- 障害時にロールバックまたは切り戻し可能な構成を優先する

## DO & DON'T

### DO

- 既存の層構造に合わせて実装する
- 変更理由と影響範囲を短く添える
- API 変更時は frontend / backend / DB の整合性を確認する
- 新規エンドポイントには正常系と異常系を用意する
- 認証まわりの変更ではセキュリティ影響を明示する
- テスト追加を実装とセットで考える

### DON'T

- コンポーネント内に API 通信・状態管理・表示ロジックを詰め込まない
- controller に業務ロジックや SQL を直接書かない
- migration なしで DB 前提を変えない
- 認証ロジックを複数箇所に重複実装しない
- console 出力だけで障害対応を完結させない
- 既存の命名・責務分割・エラー形式を無視して新流儀を持ち込まない

このテンプレートで残しているのは、Claude の判断が揺れやすい部分だけです。
技術スタック、主要コマンド、ディレクトリ構造、設計方針、DO / DON'T、テスト方針まで入れておけば、実装タスクの大半で必要な分岐は先回りできます。
反対に、文体指定、コミットメッセージの人格、空白や改行の細かい整形ルールのように、ESLintやPrettierで置き換えられるものは外したほうが効きます。
重複情報も同じで、README に書いてある内容をそのまま再掲すると、どちらを信じるべきかが曖昧になります。

運用と分割のコツ

運用では、ルートに何でも書かないことがいちばん効きます。
モノレポでフロントとバックが並ぶ構成なら、root のCLAUDE.mdには横断ポリシーだけを置き、画面実装の詳細は frontend/CLAUDE.md、API と DB の詳細は backend/CLAUDE.md に寄せる形が安定します。
『Claude Code のベストプラクティス』でも、短く保ち、必要に応じて補助機能や分割を使う考え方が一貫しています。

frontend/CLAUDE.md には、『React』のコンポーネント分割、React Query（TanStack Query / @tanstack/react-query）の queryKey 設計、Toast の出し方、フォームの責務分離のようなフロント専用ルールを書きます。

分割の基準は「担当者」ではなく「変更の文脈」で切るとうまくいきます。
フロントの UI 修正で毎回 DB 命名規約まで読ませる必要はありませんし、バックエンドの migration 作成で Toast の表示方針を読む意味もありません。
Claude がそのディレクトリで必要な指示だけ拾える状態にすると、提案が横道にそれにくくなります。
Web アプリ向けテンプレートは情報量が増えがちですが、実務では詳細を書くことより、どの階層に置くかのほうが結果を左右します。

テンプレート2: ライブラリ向け CLAUDE.md

こういう人におすすめ

このテンプレートは、OSS や社内共通ライブラリのように、既存利用者がすでにいて、公開 API の互換が最優先のリポジトリに向いています。
『TypeScript』の npm パッケージでも、Javaの SDK でも、Pythonの社内配布モジュールでも、利用側が依存しているのは実装詳細ではなく公開面です。
だから CLAUDE.md でも、アプリ向けとは別の軸で判断基準を固定したほうが安定します。

とくに効くのは、戻り値の型、例外の投げ方、引数の必須・任意、エクスポート名、設定オブジェクトのデフォルト値のような「利用者が触れる面」を変更禁止リストとして明文化するということです。
実際にこのリストを入れてから、型や例外仕様のブレが減り、レビューでも「この変更は公開 API に触れていないか」を先に見ればよくなりました。
実装の巧拙より、互換性を壊していないかの確認に集中できるので、議論が短くまとまります。

examples と docs の整備を進めたいチームにも相性があります。
ライブラリは src/ を読まなくても価値が伝わる状態が理想なので、CLAUDE.md にも examples 優先、契約テスト優先、README と API ドキュメント更新を同時に行う原則を書いておくと、実装だけ先に進んで説明が置き去りになる事故を減らせます。
『Claude があなたのプロジェクトを記憶する方法』でも、プロジェクト固有の判断基準をメモリとして置く前提が説明されていますが、ライブラリではその中心が「互換性の扱い」になります。

テンプレ全文

ライブラリ向けでは、人格指示や文体指定より、互換方針と公開 API の境界を先に置くほうが機能します。
整形ルールはPrettierや各言語の formatter、静的解析はESLintやRuff、Checkstyleのような既存ツールに任せ、README にすでにある導入説明の再掲も削ります。
ここで残すのは、Claude が変更提案のたびに判断しなければならない項目です。

# 目的
このリポジトリは公開ライブラリとして保守する。
最優先は公開 API の安定性、後方互換性、SemVer に沿ったリリース判断である。
実装の局所最適より、既存利用者への影響を小さく保つことを優先する。

# 対応環境と互換方針

- 対応言語・ランタイム・ツールチェーンは README / package metadata / build config の定義を正とする
- 互換対象は公開済みの API、公開ドキュメント、examples で案内している使い方を含む
- 互換性に疑義がある変更は安全側に倒し、破壊的変更として扱う
- バージョニングは SemVer に従う

# 技術スタック

- 実装言語: TypeScript / Java / Python など当該リポジトリの構成に従う
- パッケージ管理: リポジトリ既存のツールを使う
- テスト: unit test に加えて契約テストを重視する
- ドキュメント: README, API docs, examples を主要な利用者向け導線とする

# 主要コマンド

- install: 依存関係を導入する既存コマンド
- build: 配布物を生成する既存コマンド
- test: unit / integration / contract test を実行する既存コマンド
- lint: 静的解析を実行する既存コマンド
- docs: ドキュメント生成または確認に使う既存コマンド
- release: バージョン更新と公開に使う既存コマンド

# ディレクトリ構造

- src/: 公開実装と内部実装
- tests/: unit / integration / contract test
- examples/: 推奨利用例。公開 API の実利用サンプルを置く

> ルートの `CLAUDE.md` は判断基準だけに絞ると効きます。

### 運用と分割のコツ

ライブラリでは、ルートに全部書くと「何が公開契約で、何が補足資料なのか」がぼやけます。運用では root に互換方針、SemVer、公開 API 設計原則、テスト方針、DO / DON'T だけを置き、コードの近くに個別ルールを寄せる構成が安定します。『Claude Code のベストプラクティス』が勧める短く保つ設計とも噛み合います。

たとえば `src/**` には、公開面と内部面の区別、`internal` 扱いの命名、例外設計、依存追加基準のような実装判断を置きます。`docs/**` には利用者視点で書くこと、移行ガイドの粒度、破壊的変更時の説明順序のような文書方針を分けます。`examples/**` はさらに独立させて、最小コードで動作すること、実験用 API を混ぜないこと、README と同じ呼び出しを優先することを明文化すると、サンプルがテストも兼ねる状態を保てます。

長くなりがちな互換性ノートや過去バージョンからの移行事情は、`CLAUDE.md` に抱え込まないほうが整理しやすくなります。長文の互換性判断、非推奨化の背景、言語別の設計差分は skills 側に逃がし、Claude が必要なときだけ参照する形にすると、ルートの役割がぶれません。公開 API の安定性を守るライブラリほど、「何でもここに書く」より「判断基準だけをここに残す」ほうが、提案の質が揃います。

## テンプレート3: CI・自動化向け `CLAUDE.md`

### こういう人におすすめ

このテンプレートは、対話しながら実装を進める場面ではなく、『GitHub Actions』や pre-commit、任意の CI でClaude Codeを非対話実行する前提のチーム向けです。用途としては、PR 上で差分を解析してコメント案を返す、定型的な修正候補を提案する、限定範囲の自動修正を走らせる、といった運用が中心になります。Web アプリ向けやライブラリ向けの `CLAUDE.md` が設計判断の一貫性を主題にしていたのに対して、CI 向けは**何をしてよくて、どこから先はしてはいけないか**を先に固定するのが肝です。

入れるべき情報は絞れています。技術スタック、主要コマンド、ディレクトリ構造、設計方針、DO / DON'T、テスト方針は残します。一方で、人格指示、敬語や語尾のような文体指定、リンタや formatter で代替できる整形ルール、README や workflow ファイルにすでにある説明の転載は削ったほうが安定します。CI では毎回同じ条件で走ることが価値なので、判断基準の再現性に直結しない情報はノイズになりやすいからです。

実際、CI 用の `CLAUDE.md` を作るときに「丁寧に返答する」「読みやすく整形する」といった人向けの指示まで入れていた時期は、ログを読んでも何が実行条件で何が出力上の飾りなのかが混ざっていました。JSON 出力を明示してからは、CI 側のパーサ実装が単純になり、失敗の切り分けも早くなりました。人間が読む文章としてのきれいさより、機械が受け取れる構造のほうが効く場面です。

> [!NOTE]
> CI 向けの root `CLAUDE.md` は、役割を「安全な自動実行の前提共有」に限定するとまとまります。

{{ogp:https://docs.github.com/ja/actions|GitHub Actions ドキュメント - GitHub ドキュメント||https://docs.github.com/assets/cb-345/images/social-cards/actions.png}}

### テンプレ全文

以下は、非対話モードでの解析・修正・レビューに寄せた最小構成のテンプレートです。コピーしてそのまま土台に使えます。

# 目的 この CLAUDE.md は、CI / pre-commit / 自動実行環境で Claude を非対話モードで動かすための共通前提を定義する。
目的は、解析、レビュー、限定的な自動修正を安全かつ再現可能な形で行うこと。
人間向けの長文説明や背景知識ではなく、実行時の判断基準を優先する。

# 非対話モード前提

• 実行は常に非対話モードを前提とする
• 追加質問を前提にせず、与えられた入力、差分、設定ファイルから完結に判断する
• 不明点がある場合は推測で広く変更せず、失敗または提案に留める
• 出力は人間向け自由文ではなく、機械処理しやすい構造を優先する

# 技術スタック

• Runtime: Node.js（本番・CI ともに LTS 系を利用）
• Frontend: React
• Backend: Express
• Database: PostgreSQL
• Language: TypeScript
• Test: Jest, Playwright
• Container: Docker
• CI: GitHub Actions

# 主要コマンド

• install: npm ci
• lint: npm run lint
• typecheck: npm run typecheck
• unit test: npm run test
• e2e test: npm run test:e2e
• build: npm run build

コマンド名が実リポジトリと異なる場合は、この節だけを実態に合わせて更新する。

# ディレクトリ構造

• src/: アプリケーション本体
• tests/: unit / integration テスト
• e2e/: Playwright による E2E テスト
• .github/: GitHub Actions と CI 設定
• scripts/: CI 補助スクリプト
• docker/ または Dockerfile*: コンテナ関連定義

サブディレクトリに別の CLAUDE.md がある場合は、そのディレクトリ配下ではそちらを優先する。

# 設計方針

• 変更は既存アーキテクチャに沿って最小範囲で行う
• React は UI と副作用を分離し、データ取得や状態管理の責務を混在させない
• Express は route / service / data access の責務を分ける
• PostgreSQL のスキーマ変更を伴う場合は、アプリコード、マイグレーション、テストを整合させる
• TypeScript では any の追加より型の明確化を優先する
• 例外やエラー応答の形式を変更する場合は、既存契約への影響を確認する

# DO

• 変更理由が説明できる最小差分を優先する
• 既存テストがある領域では、修正に対応するテスト追加または更新を行う
• 失敗時は、失敗箇所と原因候補を構造化して返す
• 既存コマンドで検証できる範囲を優先し、独自手順を増やさない
• レビュー用途では、修正案とリスクを分けて示す

# DON'T

• リポジトリ外のファイルを変更しない
• シークレット、認証情報、トークン値を読み取ろうとしない
• 外部 API 呼び出し、ネットワーク越しの書き込み、任意の外部 I/O を暗黙に行わない
• formatter や lint 設定で自動検出できる整形ルールを重複して書かない
• README、CI 設定、既存ルールの全文をここへ転載しない
• 指示が曖昧なまま大きなリファクタリングを始めない

# テスト方針

• 修正対象に近い粒度のテストを優先する
• unit test を基本とし、契約影響がある変更では integration test を検討する
• UI フローやブラウザ差異に関わる変更では Playwright の E2E を対象に含める
• バグ修正では再発防止テストを追加する
• テスト失敗が既知の別要因である場合は、その切り分けを出力に含める
• テスト未実行で完了扱いにしない

# JSON出力の期待形式 出力は JSON のみとし、説明文を前置きしない。 期待する最小形式は以下。

{
  "status": "success | partial | failure",
  "summary": "1行要約",
  "findings": [
    {
      "severity": "info | warning | error",
      "path": "relative/path/to/file",
      "message": "内容",
      "suggested_fix": "任意"
    }
  ],
  "changes": [
    {
      "path": "relative/path/to/file",
      "type": "modified | created | deleted",
      "summary": "変更概要"
    }
  ],
  "tests": [
    {
      "command": "npm run test",
      "status": "passed | failed | skipped",
      "details": "任意"
    }
  ]
}

JSON として解釈できない出力は失敗扱いとする。

# 安全な操作範囲

• 変更対象は現在の作業ツリーまたは対象 PR 内のファイルに限定する
• git history の書き換え、強制 push、branch 作成、tag 操作は行わない
• 破壊的操作は明示指示がない限り禁止する

# 失敗時の扱い

• 成功時は exit code 0 を返す
• 修正不能または検証不能な場合は非 0 の exit code を返す
• 一部だけ成功した場合は status: "partial" を使い、未完了項目を JSON に残す
• 失敗理由は、入力不足、権限不足、テスト失敗、想定外エラーのどれかに寄せて記述する

• 利用ツールは必要最小限とする
• 基本はリポジトリ読取、対象ファイル編集、既存コマンド実行に必要な範囲に限定する
• 外部サービス接続、追加パッケージ導入、任意スクリプト実行は明示許可がある場合のみ行う

このテンプレートでは、あえて削っている項目があります。
たとえば「親切に説明する」「読みやすい文章で返す」といった人格寄りの指示は外しています。
CI が必要としているのは会話品質ではなく、終了条件、失敗条件、修正範囲、検証結果の構造です。
同じ理由で、Prettier や ESLint、Biome などで機械的に担保できる整形ルールも入れていません。
そこを CLAUDE.md に書き足すと、直すべきコードと直さなくてよい表記揺れが混線します。

CIでの実行要点

CI に組み込むときは、非対話モードと JSON 出力を前提にするのが基本です。
方向性が揃っていて、公式準拠の運用に寄せるほどワークフローの説明も短く保てます。
とくに GitHub Actions では、自由文の標準出力を後段で解析するより、JSON をそのままパースして annotations や PR コメントへ変換する構成のほうが、失敗時の分岐が明快です。

運用モードは、提案モードと自動修正モードを分けておくと事故が減ります。
提案モードでは読み取り専用のリポジトリアクセスを前提にし、コード変更は行わず、findings と suggested_fix だけを返します。
これは人手レビュー前の下調べに向いています。
自動修正モードでは、変更対象を作業ツリーまたは PR 内ファイルに限定し、実行コマンドも lint、typecheck、対象テスト程度に絞ります。
レビュー前提の段階で status: partial を許容し、自動反映の段階では変更可能ディレクトリをさらに狭める、という切り替え方が安定します。

セキュリティ面では、CI 向けテンプレートに書くべきことがはっきりしています。
読み取り専用で成立するジョブには書き込み権限を与えない、シークレットは参照禁止にする、外部 I/O を伴う操作は無効化するか明示許可のみにする、この3点を徹底してください。
『GitHub Actions』は GITHUB_TOKEN や secrets を実行時に扱えるので便利ですが、便利な経路をそのまま開けておくと「読めるなら読む」「書けるなら書く」という判断が混ざります。
CI 用 CLAUDE.md は、できることを増やす文書ではなく、やらないことを先に狭める文書として設計するのが望ましいです。
Node.js ベースのプロジェクトなら、テスト実行の粒度も明文化しておくと挙動が揃います。
Jestはデフォルトで利用可能コア数から 1 を引いたワーカー数を使うので、CI マシンによっては並列度が上がりすぎて I/O 待ちのほうが目立つことがあります。
そういう環境では npm run test -- --runInBand や worker 数の固定を CI 設定側で調整し、CLAUDE.md には「既存コマンドで再現できる形で検証する」とだけ書くほうが整理されています。
Playwrightも Chromium、Firefox、WebKit の 3 エンジンをカバーできるぶん、全部を毎回回すのか、差分条件で絞るのかを CI 設計で分けておくと、テンプレートの責務がぶれません。

CI 向け CLAUDE.md では、実際の処理そのものを書き込みすぎないことにも注目したいところです。
ジョブ定義、matrix、キャッシュ戦略、workflow の依存関係は .github/workflows/ に置き、CLAUDE.md にはそのジョブが守るべき判断基準だけを残します。
そうすると、workflow が増えても root の説明は膨らまず、どのジョブでも同じ安全境界を共有できます。

長くなりすぎたときの逃がし先: hooks / skills / rules

役割分担の原則

CLAUDE.md が長くなってきたときは、追記する前に「その情報は毎回必要か」を先に切り分けると崩れません。
ここで基準になるのが、hooks、skills、rules、そしてサブディレクトリごとの CLAUDE.md です。
役割を混ぜると root の文書が膨らみ、読ませたい前提より細部の運用メモが前に出てきます。

hooks に置くのは、毎回必須の自動処理です。
たとえば保存前に必ず整形を走らせる、特定の検証を常に挟む、危険な操作を機械的に止める、といった「毎回発火してほしいもの」がここに入ります。
人が思い出して実行する前提の説明文を書くより、hooks に寄せたほうが実行漏れが起きません。

skills は、たまに使う手順やドメイン知識の逃がし先です。
生成タスク、移行手順、特定スタックだけで使う実装パターン、運用時の判断基準など、毎回の読込では不要でも、呼び出したときにはまとまっていてほしい知識が向いています。
私も一度、root の CLAUDE.md が長文化しかけた段階で「生成タスク」の説明を skills に移したことがあります。
その結果、root を 60 行台に抑えたまま維持できて、読み込みの挙動が落ち着きました。
一部のコミュニティでも root は 60 行未満をひとつの目安にする運用が見られ、80 行を超えたあたりで分割を検討する考え方とも相性がいいです。

rules は、ファイル種別や領域ごとに条件付きで適用したい規約を切り出す場所です。
たとえば *.test.ts ではテスト命名規約を効かせる、src/api/ ではエラーレスポンス形式を固定する、docs/ では文体ルールを変える、といったパス依存の指示は root にベタ書きしないほうが整理できます。
サブディレクトリの CLAUDE.md も同じ発想で、frontend/ と backend/ のように責務が分かれているなら、その層だけに必要な文脈をそこで閉じたほうが素直です。

この分担で迷ったときは、ひとつだけ問いを置くと判断が速くなります。
その一文を root から削除すると、Claudeが毎回の作業で間違うかという基準です。
削っても通常作業が崩れないなら、skills か rules、あるいは下位ディレクトリへ移す余地があります。
逆に、消した瞬間に毎回の判断がぶれるなら root に残す意味があります。
何でも毎回インポートする構成は安心感がありますが、実際にはコンテキストを圧迫し、必要な前提が埋もれます。

分割判断のパターン

分割の実務パターンとしてまず扱いやすいのが、レイヤ別にサブディレクトリ CLAUDE.md を置く方法です。
『React』とNode.jsが同居する Web アプリでは、UI コンポーネントの責務、API 層、DB アクセス、認証、テスト観点が一枚に集まりがちです。
ここで root には全体方針だけを残し、frontend/CLAUDE.md と backend/CLAUDE.md に判断基準を分けると、読むべき文脈が自然に狭まります。
ライブラリなら examples/ や docs/、CI 中心なら .github/ や scripts/ 単位で分けるとぶれません。

次に効くのが、ドメイン知識や操作手順を skills 化するやり方です。
たとえばPostgreSQLの実行計画の見方、JWTの署名方式を変えるときの注意点、Sentryのノイズ除去の進め方のように、必要になる場面は限られるのに説明は長くなりやすい知識があります。
これを root に持ち込むと、普段の実装で不要な文脈まで毎回読ませることになります。
skills に逃がしておけば、必要なときだけ呼び出せて、主文書は設計原則に集中できます。

三つ目は、ファイル種別やパスで分岐する規約を .claude/rules/ に切り出すパターンです。
『TypeScript』の本体コードとJestのテストコードでは、命名も許容するパターンも違います。
Playwrightの E2E は待機戦略や selector の方針が別になることもあります。
こうした差分を root に並べると「どの条件でどのルールが効くか」が読みにくくなるので、paths 条件を持つ rules のほうが合っています。
条件付き規約は、条件付きの器に入れるのが筋です。

もうひとつ見落としにくいのが、大きなガイドを @path インポートで抱え込まないということです。
長い設計書、運用手順、API 仕様全文のような資料は、root にぶら下げて常時読み込ませるより、外部 docs として独立させたほうが保守が楽です。
『GitHub Actions』の workflow 方針やDockerのイメージ作成規約のように更新頻度が高い内容も、主文書から分けておくと差分管理が追いやすくなります。
root は「入口」、詳細は外部 docs に分けておくとよいでしょう。

ミニサンプル

最小構成だけでも、分割先の役割が見えると設計しやすくなります。
まずは rules の paths 指定です。
ファイル種別や場所で効かせたい内容は、こうした形に切り出すと root の説明が減ります。

description: API 実装時の規約
paths:
  - "backend/src/api/**/*.ts"

- エラーレスポンスは既存の共通形式に合わせる
- 例外は握りつぶさず、呼び出し元へ伝播させる
- DB 直接アクセスは service 層を経由する

skills は、長い手順をそのまま移すのではなく、呼び出し条件と成果物を先に書くと扱いやすくなります。
生成タスクや移行タスクを逃がす場所としては、この骨子だけでも十分機能します。

# skill: 記事生成タスク

## 使う場面

- 新規記事の下書きを作るとき
- 既存アウトラインに沿ってセクション執筆するとき

## 入力

- タイトル
- 想定読者
- 見出し構成
- 必須で含める要素

## 手順
1. アウトラインから重複説明を除く
2. 根拠が弱い表現を具体化する
3. 文体を既存記事に合わせる

## 出力

- そのまま本文に貼れる Markdown

サブディレクトリ CLAUDE.md は、層ごとの前提だけを書けば十分です。
root に全層の細則を書くより、対象ディレクトリに入ったときだけ追加文脈を読む構成のほうが自然です。

# frontend/CLAUDE.md

- UI は『React』の関数コンポーネントを前提にする
- データ取得は既存の query 層（React Query / TanStack Query / @tanstack/react-query）を経由する
- 画面側で認証トークンの生成や更新をしない
- Story とテストがある変更では、表示差分と失敗ケースを先に確認する
- データ取得は既存の query 層を経由する
- 画面側で認証トークンの生成や更新をしない
- Story とテストがある変更では、表示差分と失敗ケースを先に確認する

このくらいの粒度で分け始めると、root には「全体方針だけが残る」状態を保てます。
文量の問題に見えて、実際は責務分離の問題です。
CLAUDE.md を削るというより、毎回必要な情報だけを前面に出して、残りを正しい逃がし先へ移す感覚で組み替えると、読み込みも更新も安定します。

よくある失敗と見直しチェックリスト

失敗あるある

CLAUDE.md は足せば良くなるように見えますが、実際には「何を書かないか」の判断で品質が決まります。
導入直後につまずくパターンは似通っていて、まず多いのが長すぎる文書です。
要点より補足のほうが増えると、Claude が毎回読む入口で焦点がぼけます。
以前、root の CLAUDE.md が100行を超えたことがありました。
そのときに効いたのは、行ごとに「これを削除すると Claude は実際に間違うか」を見直すやり方です。
説明として親切でも、削っても判断が変わらない行は落としていくと、62行まで縮みました。
そこから先は、追記より整理のほうが先に立つようになり、改善の回転も軽くなりました。

次に多いのが、曖昧なのに書いた気になってしまうケースです。
たとえば「既存方針に従う」「適切に実装する」「必要ならテストを書く」といった文は、一見もっともらしくても判断基準がありません。
『React』ならどの層でデータ取得するのか、Expressなら例外をどこで拾うのか、PostgreSQLなら直接 SQL を許す場所はどこかまで書いてはじめて、選択のブレが減ります。
抽象語だけが並ぶ文書は、制約ではなく感想に近づきます。

古い情報が残るのも典型的な失敗です。
技術スタックやコマンドは、放置した瞬間からズレ始めます。
Node.jsは。
『React』も現行ドキュメントは 18 系列ベースで進んでおり、『react.dev』の案内と手元の README や package.json の前提が食い違うと、生成される提案まで古くなります。
npm run dev と書いてあるのに実際は pnpm dev、『Create React App』前提の説明が残っているのに実体はVite、というズレは珍しくありません。

重複管理もじわじわ効いてきます。
README にも CLAUDE.md にも同じセットアップ手順、同じディレクトリ説明、同じコマンド一覧を書くと、更新のたびに二重修正が発生します。
その結果、片方だけ直ってもう片方が古いまま残ります。
とくにDockerの起動手順や『GitHub Actions』の運用ルールのように更新頻度が高い内容は、この二重管理で崩れがちです。
CLAUDE.md 側には「判断に必要な要約」だけを置き、詳細な手順そのものは元の責務を持つファイルに寄せたほうが、差分の追跡がまっすぐになります。

逆に、コードから見れば分かる情報を書きすぎる失敗もあります。
ディレクトリ名、型定義、公開 API、テストファイルの配置など、リポジトリを読めば即座に把握できる事実を長文で説明しても、判断支援にはなりません。
CLAUDE.md 側でその周辺を言い換えて増やすと、差分が出たときに文書だけ先に古くなります。
書く価値があるのは「コードだけでは見えない制約」です。
たとえばSemVerのどの変更を MAJOR 扱いにするのか、JWT の署名方式変更をどの範囲で禁じるのか、といった運用判断のほうです。

見落とされやすいのが、セッション途中で CLAUDE.md を更新したのに、その変更を再読込させないまま作業を続けるパターンです。
人間は「さっき直したからもう反映されたはず」と感じますが、実際にはその時点の文脈で走り続けます。
規約を追記したのに同じミスが続くときは、文書の質より読み込みの切り替えが原因になっていることがあります。
とくに途中で DO/DON'T を追加したり、allowed tools 相当の扱いを狭めたりした場面では、この差がそのまま出力のズレになります。

CI 用の CLAUDE.md では、安全範囲が不明確な書き方も危険です。
『GitHub Actions』や自動修正ジョブでは、どこまで変更してよくて、どこから先は失敗として止めるのかを曖昧にすると、非対話実行に向いた文書になりません。
Jestの実行、JSON 出力の形式、失敗条件、変更可能なパス、ネットワークや権限の制限が書かれていないと、Claude は「直してよい範囲」を推定で埋めます。
CI 向けの文書で推定に頼る余地を残すと、局所修正のつもりが広い変更提案に伸びやすくなります。

7点セルフチェック

見直しでは、読みやすさより「削っても判断が壊れないか」を先に見たほうが精度が上がります。次の7項目で眺めると、長文化、陳腐化、責務の混線が見えやすくなります。

1. 各行について、削除すると Claude が本当に間違うか。

削っても出力の質が変わらない説明は、入口文書には重すぎます。背景説明、言い換え、例外の少ない常識はまず候補になります。

1. 技術スタック名とコマンドが現状と一致しているか。

『React』なのかNext.jsなのか、Jestなのか別ランナーなのか、npm なのか pnpm なのかがズレていると、以後の提案全体が古い前提で組み上がります。

1. DO/DON'T が具体的な判断基準になっているか。

「適切に」「必要に応じて」ではなく、どの層を経由するか、どの変更を避けるか、何を失敗とみなすかまで落ちているかを見ます。

1. 80行を超えたら、分割の候補を検討したか。

ここでいう行数は絶対基準ではなく、責務分離の警報として使います。root に全体方針だけを残し、ディレクトリ別文書や補助機能に逃がせるかを確認します。

1. skills、hooks、rules に逃がす設計が先に決まっているか。

長い手順は skills、条件付き規約は rules、自動実行の強制や監視は hooks というように、置き場所の役割が決まっていないと root へ何でも流れ込みます。

1. コードから読める情報を書きすぎていないか。

フォルダ構成の再説明、公開 API の写経、設定ファイルの要約だけで行を使っていないかを見ます。コードにない意思決定だけを残すほうが密度が上がります。

1. 途中で更新した内容を、次のやり取りで前提として扱わせているか。

規約を直した直後に同じタスクを続ける場面ほど、この確認が効きます。文書更新と実行文脈の切り替えを分けて考えると、原因の切り分けが早くなります。

このチェックを通すと、CLAUDE.md は「たくさん書いた説明書」から「迷ったときの判断装置」に変わります。
とくに root 文書は、知識の倉庫ではなく分岐点の集合として見ると、何を残すべきかがはっきりします。

まとめと次のアクション

要点を3行で総括

CLAUDE.md に残すのは、短くても効く設計判断だけです。
置き場所と読み込み順を守るだけで、同じ内容でも Claude の振る舞いは安定します。
テンプレートは完成を待たず今日から貼り、運用の中で誤りやすい点だけを足す形で十分回ります。

まず自分のリポジトリでClaude Codeを開き、/init を実行してください。
次に本記事の3テンプレートから最も近いものを選び、『React』Node.jsPostgreSQLのような技術スタック名と、日常的に打つコマンドだけ先に埋めます。

私はこのやり方にしてから、テンプレを貼った当日から PR レビューの初動が軽くなり、その後は Claude が繰り返し外す点だけを追記する運用で回りました。

そのまま1週間使い、同じ誤りが出た項目だけを CLAUDE.md に追加すると、文書が説明書ではなく判断装置として育ちます。
行数がふくらんできたら、root の CLAUDE.md は短く保つのが定石です。
一定量を超えたら、サブディレクトリの CLAUDE.md や skills、hooks へ責務ごとに分ける流れに移してください。