Claude Codeで最初に作るべきCLAUDE.mdの書き方：最小テンプレートとプロジェクトルールの置き方

結論：CLAUDE.mdは「プロジェクトの前提と禁止事項」を書く最小のメモから始める

CLAUDE.mdは、Claude Codeがプロジェクトごとに自動で読み込む指示ファイルです。2026年4月20日時点の公式メモリドキュメントによれば、Claude Codeはセッション開始時にいくつかの場所からCLAUDE.md系のファイルを読み込み、その内容を「プロジェクトの前提」として常に考慮してくれます。

最初から完璧なものを書く必要はありません。むしろ長すぎるCLAUDE.mdは逆効果です。公式も「200行を目安に、長くなりすぎないこと」を推奨しており、必要最小限の前提と禁止事項から始めて、実際の会話で伝えたことが繰り返し出てきたら追記していく、という運用が現実的です。

本記事では、公式のスコープ区分・最小テンプレート・.claude/rules/での分割・運用のコツを、そのままコピペして使える粒度で整理します。プロジェクトの立ち上げ前に読む記事としては、Claude Codeとは？できること・向いている人・他のAIコーディングツールとの違いやClaude Codeの認証方法もセットでどうぞ。

CLAUDE.mdの4つのスコープを理解する

Claude Codeは、セッション開始時に複数の場所からCLAUDE.md相当のファイルを読み込みます。上から順に優先度が高く、下の階層ほどローカル寄りです（公式ドキュメント参照）。

チーム開発でまず用意すべきなのはプロジェクトスコープ（./CLAUDE.md）です。リポジトリにコミットして共有することで、メンバーがclaudeを起動するだけで同じ前提が伝わるようになります。

個人の好み（「日本語で説明して」「TypeScriptのanyは使わないで」など）はユーザースコープ（~/.claude/CLAUDE.md）に書いたほうが、プロジェクト横断で効くうえ、チーム共有のルールと混ざりません。

CLAUDE.local.mdは個人の実験用メモ枠です。.gitignoreにCLAUDE.local.mdを必ず含めてください。

最小テンプレート：まずはこれをコピペする

テンプレートの目的は「Claude Codeがプロジェクトを初見で理解するためのショートカット」を提供することです。以下は一般的な日本語プロジェクト向けの最小テンプレートです。プロジェクトルート直下のCLAUDE.mdにそのまま置けます。

# プロジェクト概要

- 名称: <プロジェクト名>
- 目的: <1〜2文で要約>
- 主要技術: <例: Node.js 20, TypeScript, Astro, PostgreSQL>
- 対象ユーザー: <誰が使うか>

# ディレクトリ構成のメモ

- `src/`: アプリ本体
- `tests/`: テストコード
- `docs/`: 設計ドキュメント
- `scripts/`: 補助スクリプト

# 共通ルール

- コメントと変数名は英語で書く
- ログ出力は日本語可
- フォーマッターは `pnpm lint:fix` を使う
- テストは `pnpm test` を使う（CI上で実行する）
- 破壊的な変更を加える場合は先に計画を提示してから進める

# 禁止事項

- `.env` やAPIキーをコードやログに出さない
- `git push --force` を既定のブランチに対して実行しない
- 不明な依存関係を勝手に追加しない（理由とともに提案する）
- 商用サービスのスクレイピング目的のコードを書かない

# よく使うコマンド

- 開発起動: `pnpm dev`
- 型チェック: `pnpm typecheck`
- テスト: `pnpm test`
- ビルド: `pnpm build`

# 会話スタイル

- 回答は日本語、コードは英語
- 大きな変更は計画→実装→テストの順に進める
- 失敗したときは再試行より先に原因を説明する

初回はこの程度で十分です。実際にClaude Codeに依頼して「そう言ったのに直さない」「毎回同じ前提を書き直している」と感じたときに、該当する項目をCLAUDE.mdに追記していくと、過剰にならずに育てられます。

/initで雛形を自動生成する

プロジェクトにCLAUDE.mdがまだない状態で/initを実行すると、Claude Codeがリポジトリの内容を走査してCLAUDE.mdの雛形を生成してくれます。

生成直後のCLAUDE.mdは「見つけたファイル・ディレクトリ・パッケージ情報」を並べただけの状態なので、そこに意図（なぜそうしているか）と禁止事項を書き足すとバランスよく仕上がります。

雛形をそのまま使うより、「ファイルから読み取れる事実」は削って、「読み取れない意図や運用ルール」を厚くするのが、効きやすいCLAUDE.mdのコツです。

/memoryでその場で追記する

対話の途中で「これも覚えさせたい」と思ったときは、/memoryスラッシュコマンドで任意のメモリファイルを開いて編集できます。

どのスコープに書くか（プロジェクト／ユーザー／ローカル）を選ぶプロンプトが出るので、目的に合わせて選びます。ユーザー個人の嗜好はユーザースコープ、チームで共有したいならプロジェクトスコープに、と使い分けます。

会話中に「今後はXXXしないで」と言ったら、Claude Code側で該当スコープのCLAUDE.mdへ自動追記する提案がされるケースもあります。提案内容に違和感があれば、/memoryで手動で整えてください。

長くなってきたら.claude/rules/に分割する

プロジェクトが育つと、CLAUDE.mdにAPI設計ルール・コンポーネント命名ルール・レビュー観点などが混ざってきます。そうなってきたら、.claude/rules/配下に分割するのがおすすめです。

ルールファイルの先頭にfrontmatterでpathsを書くと、そのパスで作業しているときだけルールを読み込ませられます。

---
description: APIハンドラ共通ルール
paths:
  - "src/api/**"
---

- 入力は `zod` でバリデーションする
- エラーは `throw new ApiError(...)` に統一する
- レスポンスは `{ data, meta }` 形式にする

こうすることで、フロントエンド作業中にバックエンド専用ルールを読み込ませて、コンテキストを肥大化させる無駄が避けられます。Claude Codeのコンテキストは広いとはいえ有限で、関係ないルールを全員に毎回読ませるのは精度にも速度にも悪影響です。

CLAUDE.md側からルールファイルを参照したい場合は、@記法でインポートできます。

# プロジェクト前提

- 詳細な実装ルールは以下を参照
  - @.claude/rules/api.md
  - @.claude/rules/frontend.md

CLAUDE.mdに書くべきこと・書かないほうがいいこと

書くべきこと

• プロジェクトの目的と主要技術: 初見でフレームワークや言語を間違えさせないため
• ディレクトリ構成の要点: 読むファイルの優先度を伝えるため
• コマンド: 開発起動・テスト・ビルドを書くと、Claude Codeがテスト実行などを自発的に選びやすくなる
• 禁止事項: .env・APIキーの扱い、本番環境への直接デプロイ、破壊的なGitコマンド
• 会話スタイル: 日本語／英語の使い分け、説明の粒度、計画先行の指示
• プロジェクト固有の癖: 例外的なディレクトリ構造、独自命名、慣習

書かないほうがいいこと

• コードから自明な事実: package.jsonに書いてある依存関係の列挙や、ファイル一覧の丸写し
• TODOや進捗メモ: 古くなるとむしろ誤解を生むので、Issue／PRに寄せる
• 機密情報: APIキー、接続先URLの直書き、個人情報
• 頻繁に変わる数値: バージョン番号や日次の作業状況
• 冗長な敬語・装飾: 箇条書きで短く、指示は命令形でよい

公式も「長すぎるCLAUDE.mdは読みにくさから情報が埋もれる」と示唆しており、迷ったら削るほうを選んでください。

ユーザースコープで好みを一括設定する

個人の好みは~/.claude/CLAUDE.mdにまとめると、複数プロジェクトで同じ指示を書かずに済みます。

# 個人の作業スタイル

- 回答は日本語、コードは英語
- 箇条書き中心、長文回答を避ける
- 大きな変更は計画→実装→テストの順に進める
- Gitの既定操作（`commit`、`push`）は確認してから実行

# 言語別の好み

- TypeScript: `any` は使わず `unknown` + 型ガード
- Python: 型ヒント必須
- Shell: `set -euo pipefail` を既定に

# 好きな依頼の受け取り方

- まず何をしようとしているか1〜2文で要約する
- 不明点があれば実装前に質問する

この程度でも「Claude Codeが最初から自分の好みで動く」体感は大きく変わります。ユーザースコープは個人マシン依存なので、チーム内にルールを強制したいならプロジェクトスコープに書き戻す、という切り分けを意識すると混乱しません。

更新タイミングと運用のコツ

更新するタイミング

• Claude Codeに同じ指摘を2回以上したとき（対話ではなくCLAUDE.mdに書く）
• 新しい禁止事項が出てきたとき（セキュリティ事故のヒヤリ・ハット含む）
• ディレクトリ構成を変えたとき
• 主要コマンドが変わったとき（npm → pnpm など）

運用のコツ

• 1ファイルを長くするより、.claude/rules/でスコープを絞る
• 定期的に「使われていないルール」を削る（古いルールは誤情報になりやすい）
• プロジェクトスコープとユーザースコープで矛盾したことを書かない
• チームではCLAUDE.mdの変更をPRレビュー対象にする（勝手に増殖させない）
• .gitignoreにCLAUDE.local.mdを含めておく

アンチパターン

• 箇条書きで100項目: 読み切れず重要な項目が埋もれる
• 冗長な敬語: 「〜してください」を繰り返すよりも命令形で揃える
• コピペの実装例を大量に貼る: 実装例はサンプルリポジトリに置き、CLAUDE.mdは方針だけにする
• 機密のベタ書き: APIキー、接続先URL、個人情報

チェックリスト

• ./CLAUDE.md または ./.claude/CLAUDE.md にプロジェクト前提が書かれている
• 禁止事項（.env、機密、破壊的Git操作）が明記されている
• よく使うコマンド（dev／test／build）が書かれている
• 200行を大きく超えていない
• ~/.claude/CLAUDE.md に個人の好み（言語、説明スタイル）が書かれている
• .gitignore に CLAUDE.local.md が含まれている
• .claude/rules/ に分割するほど膨らんでいたら移行済み
• 古くなったルールを定期的に見直している

まとめ

CLAUDE.mdは、Claude Codeに「このプロジェクトはこう動かしてほしい」を一度書いておくための仕組みです。最初から完璧を目指さず、最小テンプレート＋禁止事項から始めて、実際の会話で繰り返し伝えたことを追記していくのが現実的な育て方です。

プロジェクト・ユーザー・ローカルの3スコープを使い分け、膨らんできたら.claude/rules/でパス単位に分割する、というのが長期運用の型です。書きすぎず・古くしないためのチェックリストだけでも、別タブに残して使ってください。

次に読むべき同シリーズ記事

• Claude Codeとは？できること・向いている人・他のAIコーディングツールとの違い
• Claude Codeの認証方法とログインできないときの確認ポイント
• macOSでClaude Codeをインストールする手順と初期設定