メインコンテンツへスキップ
見出し画像

【テンプレ5選】CLAUDE.mdの書き方ガイド——200行超えで破綻した私の設計ルール

    CLAUDE.mdを「とりあえず箇条書き」で始めて、3プロジェクト目で破綻しました。200行を超えた頃にはClaude Codeがルールを無視し始め、何を書いたか自分でもわからなくなっていた。整理し直して気づいたのは、「書く内容」より「書く場所と粒度」の設計が重要だということでした。

    この記事でわかること: Claude CodeのCLAUDE.mdに「何を書くべきか」「何を書いてはいけないか」の判断基準と、プロジェクト規模別にそのまま使える5つのテンプレートを紹介します。

    Claude Codeを導入したけどCLAUDE.mdに何を書けばいいかわからない方、書いたのにClaude Codeが指示を守ってくれない方向けの記事です。エンジニアでなくても「AIへの指示書をどう設計するか」という観点で参考になります。

    このnoteでは、非エンジニア向けにAI活用を実務ベースで解説しています。

    CLAUDE.mdの設計テンプレートで解決できること

    CLAUDE.mdはClaude Codeに対する「永続的な指示書」です。セッションを開始するたびに自動で読み込まれ、Claude Codeの動作を制御します。

    しかし、多くの人がつまずくポイントがあります。

    • CLAUDE.mdに何を書けばいいかわからず、空のまま使っている

    • 逆に全部書きすぎて200行超え、Claude Codeが重要なルールを無視する

    • 複数プロジェクトで同じ内容をコピペし、メンテナンスが崩壊する

    私は5つのプロジェクトを並行運用する中で、「書くべきことと書いてはいけないことの線引き」を試行錯誤してきました。この記事では、その結果を5つのテンプレートとして整理しています。

    前提条件

    • Claude Code がインストール済み

    • 何らかのプロジェクト(コードベース)が手元にある

    筆者の実行環境

    • OS: macOS Sequoia 15.x

    • ツール: Claude Code

    • 利用プラン: Claude Code Max $100/月

    CLAUDE.md設計テンプレートの構築手順

    Step 1: CLAUDE.mdの配置場所を理解する

    CLAUDE.mdは配置する場所によって適用範囲が変わります。この仕組みを知らないまま書き始めると、後から構造を直すことになります。

    3つの配置場所:

    • `~/.claude/CLAUDE.md`(グローバル) — 全プロジェクトに適用。Gitのコミット規約、セキュリティルール、コードスタイルなど、どのプロジェクトでも共通のルールを書く

    • `プロジェクトルート/CLAUDE.md`(プロジェクト) — そのプロジェクトだけに適用。プロジェクト概要、ディレクトリ構成、固有のルールを書く。Gitにコミットしてチームで共有できる

    • `CLAUDE.local.md`(個人ローカル) — 個人だけに適用。自分だけの設定やメモを書く。`.gitignore` に含めてチームには共有しない

    読み込み順序:

    グローバル → プロジェクト → ローカルの順で読み込まれ、すべてが連結されます。上書きではなく追加(連結)です。後に読み込まれた内容が優先されますが、先に読み込まれた内容も残ります。

    私が最初にやった失敗: プロジェクトの `CLAUDE.md` にGitのコミット規約を書いていました。5つのプロジェクトすべてに同じ内容をコピペしていたため、ルールを1つ変えるたびに5ファイルを編集する羽目に。グローバルに移動してからメンテナンスコストがゼロになりました。

    判断基準は「2つ以上のプロジェクトで使うか」です。 Yesならグローバル、Noならプロジェクトに書きます。

    Step 2: 書くべきこと・書いてはいけないことを区別する

    CLAUDE.mdに書く内容は「毎セッション、Claude Codeが必ず知っていなければならない情報」に限定します。

    書くべきこと(毎回参照が必要):

    • プロジェクトの概要(1-2行の説明)

    • ビルド・テスト・実行コマンド

    • ディレクトリ構成と各フォルダの役割

    • コード規約(命名規則、インデント、言語固有のルール)

    • プロジェクト固有の制約(例: 「Markdownテーブル禁止」「このAPIは非推奨」)

    • よくあるハマりポイント

    • ファイル命名規則

    書いてはいけないこと(別の場所に移動):

    • 長い手順書(10行以上の手順) → Skills(`.claude/skills/`)に移動。`/コマンド名` で必要な時だけ呼び出せる

    • ファイルの詳細な説明 → READMEやdocsに書き、CLAUDE.mdからリンクする

    • 頻繁に変わる情報 → `docs/` のMarkdownに書き、CLAUDE.mdでは参照先だけ記載

    • 言語の基本構文や一般的なベストプラクティス → Claude Codeは既に知っている。書く必要がない

    • settings.jsonで強制できるルール → permissions(allow/deny)や環境変数は `settings.json` に書く。CLAUDE.mdの指示は「推奨」であり「強制」ではない

    私の実例: 最初は記事生成の手順(テンプレートの読み込み→リサーチ→本文生成→保存)をCLAUDE.mdに書いていました。30行以上あり、他のルールが埋もれていました。これをSkillの `/draft` コマンドに移動したところ、CLAUDE.mdは3行の説明だけになり、Claude Codeが他のルール(タイトル規約やファイル命名規則など)を守るようになりました。

    目安: CLAUDE.mdは200行以内に収める。 超えたら整理のサインです。手順はSkillsに、詳細はdocsに、強制ルールはsettings.jsonに移動してください。

    Step 3: テンプレート1——個人開発プロジェクト用(最小構成)

    Claude Codeを使い始めたばかりの個人プロジェクト向けのテンプレートです。

    # プロジェクト名
    
    プロジェクトの1行説明。
    
    ## コマンド
    
    - ビルド: `npm run build`
    - テスト: `npm test`
    - 開発サーバー: `npm run dev`
    - Lint: `npm run lint`
    
    ## ディレクトリ
    
    - `src/` — アプリケーションコード
    - `tests/` — テストファイル
    - `docs/` — ドキュメント
    
    ## コード規約
    
    - TypeScript strict mode
    - 2スペースインデント
    - 関数名はキャメルケース、ファイル名はケバブケース
    
    ## Git
    
    - コミットメッセージ: `type: summary`(type: feat/fix/docs/chore)
    - ブランチ: `feat/xxx`, `fix/xxx`

    このテンプレートのポイント:

    • 30行以内。Claude Codeが確実に全体を把握できるサイズ

    • コマンドセクションを最上部に配置。Claude Codeが最も頻繁に参照する情報

    • 「何をどう書くか」ではなく「何をどう実行するか」に集中

    私の体感では、この最小構成だけでClaude Codeの精度が明らかに変わります。 特にビルドコマンドとテストコマンドを書いておくだけで、「これでビルドしていいですか?」という確認の精度が上がります。

    Step 4: テンプレート2——チーム開発プロジェクト用

    チームで共有するプロジェクトの `CLAUDE.md` テンプレートです。

    # プロジェクト名
    
    > このファイルはチーム全員で共有します。個人設定は CLAUDE.local.md に書いてください。
    
    ## プロジェクト概要
    
    何のためのアプリケーションか、1-2行の説明。
    
    ## セットアップ
    
    npm install
    cp .env.example .env
    npm run migrate
    npm run dev
    
    ## コマンド
    
    - ビルド: `npm run build`
    - テスト全体: `npm test`
    - 単一テスト: `npm test -- src/foo.test.ts`
    - Lint: `npm run lint`
    - デプロイ: mainブランチへのマージで自動デプロイ
    
    ## ディレクトリ
    
    - `src/features/` — 機能ごとのディレクトリ
    - `src/shared/` — 共通ユーティリティ
    - `src/types/` — 型定義
    - `tests/` — テストファイル
    
    ## コード規約
    
    ### TypeScript
    
    - strict mode 有効
    - すべての関数にパラメータと戻り値の型を指定
    - `any` は禁止、`unknown` + 型ガードを使う
    
    ### テスト
    
    - ユーザーアクション単位でテストを書く
    - モックは `__mocks__/` に集中管理
    - DBテストはトランザクションロールバックで独立性を保つ
    
    ### Git
    
    - mainブランチは常にデプロイ可能な状態を維持
    - コミットメッセージ: `type: summary`(50字以内)
    - PRに複数機能を混ぜない
    
    ## よくあるエラーと対処
    
    - `MODULE_NOT_FOUND` → `npm install` を再実行
    - マイグレーション失敗 → DBが起動しているか確認、`npm run migrate:reset`
    - 型エラーが大量に出る → `npm run tsc` で全体の型チェック
    
    ## 参考資料
    
    詳細なAPI設計は `docs/api-design.md` を参照。

    チーム用テンプレートの設計判断:

    • 冒頭に「個人設定は CLAUDE.local.md へ」と明記。チームメンバーが CLAUDE.md を個人設定で汚すのを防ぐ

    • セットアップセクションを追加。新メンバーがClaude Codeで「セットアップして」と言うだけで環境構築できる

    • 「よくあるエラー」セクション。Claude Codeがエラーに遭遇した時、ここを参照して自力で解決できる

    Step 5: テンプレート3——ドメイン特化型(コンテンツ制作・データ処理等)

    通常のWebアプリ開発とは異なるドメイン(記事制作、データ処理、ドキュメント管理など)のテンプレートです。私が実際に運用している記事制作パイプラインの構造を例にします。

    # プロジェクト名
    
    プロジェクトの1行説明。
    
    ## スキル
    
    - `/draft` — 記事の下書き生成
    - `/polish` — 校正・SEO最適化
    - `/tweet` — X告知投稿の生成
    
    ## CLIコマンド
    
    - `project-name format` — 整形+クリップボードコピー
    - `project-name publish` — 公開実行
    
    ## ディレクトリ
    
    - `articles/` — 成果物(Markdown)
    - `templates/` — テンプレート
    - `prompts/` — LLMプロンプト
    - `docs/` — 戦略ドキュメント
    
    ## ファイル命名規則
    
    - 形式: `YYYY-MM-DD-{スラッグ}.md`
    - 日付は `date +%Y-%m-%d` コマンドで取得する
    - 関連ファイル(X投稿、校正結果)は同じ日付プレフィックスで統一
    
    ## 絶対ルール
    
    ### 禁止パターン
    
    - Markdownテーブル(`| xxx |` 形式)禁止 — プラットフォームでレンダリングされない
    - Before/After は「値A → 値B」で表現
    - 比較は箇条書きで表現
    
    ### 品質チェックリスト
    
    - [ ] 固有名詞を1つ以上含める
    - [ ] 具体的な数字を1つ以上含める
    - [ ] 冒頭で「誰向けか」を明示する
    
    ## 外部APIのルール
    
    - URLは必ずAPIから取得する。推測で作らない
    - 未公開のデータを含めない
    
    ## 詳細設定
    
    コンテンツ戦略の詳細は `docs/strategy.md` を参照。

    このテンプレートの特徴:

    • スキルセクション(`/コマンド`)を最上部に配置。ドメイン特化プロジェクトでは、コマンドがワークフローの中心

    • 「絶対ルール」セクションでプラットフォーム固有の制約を明示。Claude Codeが「やってはいけないこと」を理解する

    • チェックリストは `- [ ]` 形式で書く。Claude Codeはチェックリストを見ると「確認して進めなければ」と認識する

    なぜチェックリスト形式が効くか: 私が最初に「固有名詞を含めてください」と文章で書いていた時は守られないことがありました。`- [ ]` 形式にしたところ、Claude Codeが「チェックリストの項目を確認します」と明示的に各項目を検証するようになりました。

    Step 6: テンプレート4——グローバルCLAUDE.md用

    `~/.claude/CLAUDE.md` に書くグローバル設定のテンプレートです。全プロジェクトに適用されるため、プロジェクト固有の内容は入れません。

    # グローバル開発ルール
    
    ## Git規約
    
    - コミットメッセージ: `type: summary`
    - type: feat / fix / docs / chore / refactor / test
    - pushは必ずユーザーの許可を得てから実行
    - force pushは禁止
    
    ## セキュリティ
    
    - 認証情報をコードに含めない
    - .env, credentials.json 等はコミットしない
    - APIキーは環境変数で管理
    
    ## コードスタイル
    
    - 関数名はキャメルケース
    - ファイル名はケバブケース
    - インデントは2スペース
    
    ## 開発ログ
    
    gitコミット後、開発ログを所定の場所に書き出す:
    - 保存先: `/path/to/dev-log/{プロジェクト名}/YYYY-MM-DD.md`
    - 形式: コミットメッセージ + 変更概要の1行サマリー

    私の場合はこれに加えて、 「plan modeの実装完了後に設計ドキュメントを `docs/` に自動保存する」「gitコミット後にObsidianの開発ログに自動追記する」の2つのルールを書いています。いずれも全プロジェクトで共通の動作であり、グローバルに置くべきルールです。

    グローバルCLAUDE.mdの設計原則:

    • 短く保つ(50行以内が理想)。 グローバルは全セッションで読み込まれるため、長いとコンテキストウィンドウを圧迫します

    • プロジェクト固有の内容を入れない。 「Pythonの場合は〜」「このプロジェクトでは〜」のような条件分岐が入り始めたら、プロジェクトの `CLAUDE.md` に移動するサインです

    • 強制したいルールは settings.json にも書く。 CLAUDE.mdの指示はあくまで「推奨」。Claude Codeが守らないことがある。`settings.json` の `permissions.deny` に `"Bash(git push --force *)"` を設定すれば、force pushは技術的にブロックされる

    私の失敗事例: グローバルCLAUDE.mdに「plan modeで計画を作成したら設計ドキュメントをdocs/に保存する」と書いていました。しかし保存先のパスがプロジェクトごとに違い、Claude Codeが混乱して間違ったパスに保存するケースがありました。グローバルにはトリガーとフォーマットだけを書き、保存先はプロジェクトのCLAUDE.mdで上書きする構造に変えて解決しました。

    Step 7: テンプレート5——モノレポ・大規模プロジェクト用

    複数パッケージが同居するモノレポや、大規模プロジェクトのテンプレートです。

    # プロジェクト名(ルート)
    
    複数パッケージで構成されたアプリケーション。
    
    ## パッケージ構成
    
    - `packages/api/` — バックエンドAPI(Node.js + Express)
    - `packages/web/` — フロントエンド(Next.js)
    - `packages/shared/` — 共通ライブラリ
    
    ## 全体コマンド
    
    - 全テスト: `npm run test:all`
    - 全ビルド: `npm run build:all`
    - 開発: `npm run dev`(全パッケージ同時起動)
    
    ## 全体ルール
    
    - パッケージ間の依存は `packages/shared/` 経由のみ
    - `api/` と `web/` が直接 import し合うことは禁止
    
    ## パッケージ固有のルールについて
    
    各パッケージのディレクトリに個別の `CLAUDE.md` があります。
    該当パッケージのファイルを扱う時に自動で読み込まれます。

    モノレポの場合、ネストされたCLAUDE.mdが鍵です。 各パッケージのディレクトリに `CLAUDE.md` を置くと、Claude Codeがそのパッケージのファイルを読む時だけ追加で読み込まれます。

    monorepo/
    ├── CLAUDE.md                 ← 全体ルール(常に読み込まれる)
    ├── packages/
    │   ├── api/
    │   │   └── CLAUDE.md         ← API固有ルール(api/のファイル操作時のみ)
    │   ├── web/
    │   │   └── CLAUDE.md         ← Web固有ルール(web/のファイル操作時のみ)
    │   └── shared/
    │       └── CLAUDE.md         ← 共通ライブラリルール

    ネスト CLAUDE.md のメリット: ルートの `CLAUDE.md` が短く保てます。API固有のルール(エンドポイントの命名規則、バリデーション方式など)は `packages/api/CLAUDE.md` に書き、フロントエンド固有のルール(コンポーネント設計パターン、スタイリング規約など)は `packages/web/CLAUDE.md` に書く。Claude Codeは必要な時だけ必要なルールを読みます。

    注意: ネストCLAUDE.mdはオンデマンド読み込みです。 セッション開始時には読み込まれず、該当ディレクトリのファイルをClaude Codeが初めて操作する時に読み込まれます。そのため、コンパクション(会話圧縮)後にネストCLAUDE.mdの内容が失われることがあります。重要なルールはルートの `CLAUDE.md` に書いてください。

    CLAUDE.md設計でよくあるトラブルと対処法

    Claude Codeがルールを無視する

    • 原因1: CLAUDE.mdが長すぎる。200行を超えると、重要なルールが埋もれる

    • 対処法: 手順をSkillsに移動し、CLAUDE.mdは「何をするか」だけを書く。「どうやるか」はSkillsに任せる

    • 原因2: 指示が抽象的。「きれいなコードを書いてください」は意味がない

    • 対処法: 「2スペースインデント」「関数名はキャメルケース」のように具体的に書く

    複数のCLAUDE.mdで内容が矛盾する

    • 原因: グローバルで「4スペースインデント」、プロジェクトで「2スペースインデント」のように矛盾する指示がある

    • 対処法: Claude Codeは複数のCLAUDE.mdを連結して読みますが、矛盾する指示がある場合は後に読み込まれたものを優先する傾向があります。プロジェクトのCLAUDE.mdはグローバルの後に読み込まれるため、プロジェクト固有の規約をプロジェクトに書けば優先されます

    CLAUDE.mdを編集したのに反映されない

    • 原因: ルートのCLAUDE.mdはセッション開始時に1回だけ読み込まれ、セッション中に編集しても反映されない。ただしネストされたCLAUDE.md(サブディレクトリ内)はオンデマンド読み込みのため、該当ファイルを初めて操作する前に編集すれば反映される

    • 対処法: ルートのCLAUDE.mdを編集した場合は、新しいセッションを開始する(Claude Codeを再起動する)

    CLAUDE.md設計の注意点

    CLAUDE.mdとsettings.jsonの使い分け

    混同しやすいですが、役割が明確に異なります。

    • CLAUDE.md — 「推奨」ルール。自然言語で書く。Claude Codeの判断に影響を与えるが、技術的に強制はされない

    • settings.json — 「強制」ルール。JSONで書く。permissions(許可/拒否)、Hooks(自動実行)、環境変数など

    例えば「force pushしない」は両方に書きます。CLAUDE.mdには理由とともに「force push禁止」と書き、settings.jsonには `"deny": ["Bash(git push --force *)"]` と書く。CLAUDE.mdだけだとClaude Codeが無視する可能性がありますが、settings.jsonのdenyは技術的にブロックされます。

    `@` インポートで外部ファイルを取り込む

    CLAUDE.md内で `@ファイルパス` と書くと、そのファイルの内容がCLAUDE.mdに展開されます。

    # プロジェクト名
    
    ## コード規約
    
    @docs/coding-standards.md
    
    ## API設計
    
    @docs/api-design.md

    活用場面: ドキュメントを `docs/` に管理しつつ、CLAUDE.mdから参照したい場合。CLAUDE.md本体を短く保ちながら、必要な情報を取り込めます。

    注意点: インポートされたファイルはすべてコンテキストウィンドウに読み込まれます。大きなファイルを `@` で取り込むと、コンテキストを圧迫します。取り込むのは要約や規約など短いファイルに限定してください。

    「3回同じ指示を書いたらルールにする」の法則

    セッション中にClaude Codeに同じことを3回伝えていると気づいたら、ルール化のタイミングです。書き先は内容によって3つに分かれます。

    • 「テストはjestで実行して」→ 3回言った → CLAUDE.md に `テスト: npm test` を追加(毎セッション必要な情報)

    • 「この手順でデプロイして」→ 3回言った → Skills に `/deploy` コマンドとして移動(長い手順書)

    • 「このディレクトリは触らないで」→ 3回言った → settings.json の `deny` に追加(技術的に強制したいルール)

    逆に、1回しか伝えていない指示はどこにも書く必要はありません。セッション中の会話で十分です。

    次にやるべきこと

    1. まずテンプレート1(最小構成)を自分のプロジェクトに適用する。 ビルドコマンドとディレクトリ構成を書くだけで効果を実感できます

    2. 1週間使ったら、セッション中に繰り返し伝えた内容をCLAUDE.mdに追記する。 「3回ルール」に従い、必要な情報だけを追加してください

    3. 100行を超えたら、Step 2の「書いてはいけないこと」リストに照らして整理する。 手順はSkillsへ、詳細はdocsへ、強制ルールはsettings.jsonへ移動してください

    Claude Code活用の実践ノウハウを引き続き発信しています。この記事が参考になったら、スキとフォローで応援お願いします。

    参考リソース

    関連記事

     
     
    「AI、実際どこまで仕事で使えるの?」を非エンジニア目線で検証しています。ChatGPT・Claude・Geminiを実務で試して、使えた/ダメだったを実測と失敗談つきで正直に書きます。

    あなたへのおすすめ