ファイル群が放射状に並び中央に折りたたまれたドキュメントアイコンが置かれた抽象イラスト

記事

CLAUDE.mdテンプレート完全版：開発ルール・禁止事項・確認コマンドをコピペで揃える

Claude Code向けのCLAUDE.mdをそのままコピペで使える完全版テンプレートとして整理しました。プロジェクト概要・触ってよい場所・壊してはいけないUX・確認コマンド・禁止事項・PR運用までを200行以内に収める指針と、`.claude/rules/`への分割タイミングまで実務目線でまとめます。

結論：「最小版」を超えるなら7ブロック構成のCLAUDE.mdに揃える

Claude Codeで本格的に開発を回し始めると、最小版のCLAUDE.mdでは指示が足りなくなります。「依頼のたびに同じ前提を書いている」「触ってほしくない場所を毎回指摘している」状態に気付いたら、本記事のテンプレート完全版に置き換えてください。

完全版は次の7ブロックで構成します。

プロジェクト概要：何のプロジェクトか、技術スタック、主要ディレクトリ
触ってよい場所／触らない場所：ディレクトリ単位の権限境界
コーディングルール：命名・スタイル・依存追加の方針
壊してはいけないUX／挙動：ユーザー影響の出る固定要件
確認コマンド：lint・型・テスト・ビルドの実行方法
Git／PRルール：ブランチ・コミット粒度・PR説明
禁止事項：絶対にやってはいけないこと

この順序は、公式のHow Claude remembers your projectが推奨する**「具体的・検証可能・全セッションで必要なものだけ」という3条件に沿って組み立てています。最小版や/initの使い分けはClaude Codeで最初に作るべきCLAUDE.mdの書き方で扱っているので、本記事は完全版テンプレート本体**に集中します。

大前提：200行以内・具体的・矛盾なし

公式はCLAUDE.mdに**「200行未満を目安」と明記しています。理由は単純で、CLAUDE.mdは毎セッション全文がコンテキストに読み込まれ、長くなるほど他の指示と混ざって遵守率が下がる**からです。

完全版テンプレートを使うときも、次の3条件は崩さないでください。

具体的：「コードを綺麗に」ではなく「ESLintルールに従う」「2スペース」と書く
検証可能：npm testが通れば守れたと判定できる粒度にする
矛盾なし：別の場所と重複・対立する指示は片方を消す

特定ディレクトリだけのルール（API層の規約、UIだけのルールなど）は、後述する.claude/rules/へ移したほうが、ルートのCLAUDE.mdを200行以内に収めやすくなります。

CLAUDE.md完全版テンプレート

以下をプロジェクトルートのCLAUDE.mdにコピペし、{{}}の中身だけ埋めて運用を始めてください。コメント（）はClaudeに渡る前に除去されるため、人間用メモとして残しても安全です。

<!-- =========================================
  Project Instructions for Claude Code
  最終更新: {{YYYY-MM-DD}}
  メンテナ: {{name}}
========================================= -->

# {{プロジェクト名}}

## 1. プロジェクト概要
- 種別: {{Webアプリ / CLI / ライブラリ / モバイル ほか}}
- 技術スタック: {{言語・主要フレームワーク・主要ライブラリ}}
- ランタイム: {{Node 20 / Python 3.12 / Go 1.22 ほか}}
- パッケージマネージャ: {{npm / pnpm / yarn / uv / poetry ほか}}
- デプロイ先: {{Vercel / Cloudflare / AWS / 自前 ほか}}

主要ディレクトリは @docs/architecture.md を参照。

## 2. 触ってよい場所 / 触らない場所
- 触ってよい: src/, tests/, docs/
- 既存仕様を変える前に確認が必要: src/domain/, src/api/contracts/
- **触らない**:
  - vendor/ — 外部由来。修正禁止
  - public/legacy/ — 旧UIアセット
  - migrations/ — DBスキーマ変更は専用フローで（後述）
  - .github/workflows/ — CIは管理者承認が必要

## 3. コーディングルール
- 命名: 関数 camelCase / 型 PascalCase / ファイル kebab-case
- インデント: スペース2
- import: 名前付きimportを優先。`import * as`は禁止
- 例外処理: 例外を握りつぶさない（最低でもログ）
- 依存追加:
  - 新しいライブラリを追加する前に必ず確認を取る
  - 既存で代替できないかを先に検討する
  - 追加した場合はpackage.jsonとロックファイルを同じコミットに含める
- コメント: 「なぜ」を書く。「何を」は書かない（コードで自明）

## 4. 壊してはいけないUX / 挙動
- {{例: ログイン後の遷移先は /dashboard で固定}}
- {{例: 公開URLの構造（/posts/<slug>/）は変更しない}}
- {{例: i18nキー名は外部翻訳ツールが参照しているので変更禁止}}
- {{例: APIレスポンスのキー名（snake_case）は外部依存があるので維持}}

破壊的変更が必要な場合は、Plan Modeで計画を出してから着手すること。

## 5. 確認コマンド（コミット前に必ず）
- 型チェック: `{{npm run typecheck / pnpm typecheck / mypy}}`
- Lint: `{{npm run lint}}`
- ユニットテスト: `{{npm test}}`
- E2E（必要な変更のみ）: `{{npm run e2e}}`
- ビルド: `{{npm run build}}`

> 一連の修正が終わったら、最低でも型チェックとLintを通してから報告すること。

## 6. Git / PRルール
- ブランチ名: `feat/<short-name>` / `fix/<issue-id>` / `chore/<short-name>`
- コミット: 1コミット=1意図。リファクタと機能追加を混ぜない
- コミットメッセージ: 命令形・1行目72文字以内
- PR説明テンプレ:
  - 変更概要
  - 影響範囲
  - 確認手順
  - スクリーンショット（UI変更時）
- 秘密情報（APIキー・トークン・個人情報）はコミットしない

## 7. 禁止事項
- ❌ `git push --force` を main / develop に対して行う
- ❌ `npm install <package>` を許可なく実行する
- ❌ テストの`skip` / `only` を残してコミットする
- ❌ コメントアウトしたコードを残す（消すか別ブランチへ）
- ❌ `.env` をコミットする
- ❌ 確認コマンドが落ちている状態で「完了」と報告する

ブロックごとの書き方のコツ

1. プロジェクト概要は「読まなくても外形が分かる」3行で

ここで多くを語ると残りのブロックが圧迫されます。ClaudeがREADME.mdを読めば分かることは書かないのが原則です。代わりに、

詳細は @README.md を参照。

と@参照を1行入れる方が、コンテキスト効率が良くなります。@参照は最大5階層まで再帰的にimportでき、起動時に全文ロードされます。

2. 触る場所／触らない場所は「ディレクトリ単位」で書く

src/utils/format-date.tsのようなファイル単位の禁止は書かないでください。ディレクトリ単位の境界だけにすると、新規ファイルが増えても破綻しません。「触らない場所」を3〜5項目に抑えるのがちょうどいい量です。

3. コーディングルールは「自動チェックで守れないもの」だけ

ESLint・Prettier・型チェックで自動的に守られるルール（インデント幅、quote種別など）は、書いても書かなくてもClaudeは設定ファイルを見て従います。CLAUDE.mdに書くべきは、

機械的に判定できないが守ってほしい命名・設計の方針
プロジェクト固有のアンチパターン
自動化されていない依存追加の承認フロー

の3つに絞るとスッキリします。

4. 壊してはいけないUXは「再発防止」の場所

過去に1回でも壊して怒られたUX・契約は、必ずここに書きます。Claudeが同じ失敗を二度しないための場所であり、ここを充実させるほど依頼の質が上がります。

公式もCLAUDE.mdの更新タイミングとして**「コードレビューでClaudeが指摘されたこと」「同じ訂正を二度入れたとき」**を挙げています。怒られた瞬間にここへ追記する運用にすると、文書が育ちます。

5. 確認コマンドは「Claudeがそのまま叩けるコマンド」を書く

「テストを通すこと」ではなく、pnpm test:unit -- --reporter=verboseのように丸ごと貼り付けて動く形で書きます。Claudeはここを読んでBashツールを呼び出すため、曖昧だと「テスト走らせ方が分からない」状態になります。

6. Git／PRルールは「コミット粒度」と「秘密情報」が最重要

ghコマンドを使ってPRを作る運用にしているなら、PRテンプレもここに書いてしまうと、Claudeに「PR作って」と言うだけで体裁が揃います。詳細はClaude Codeで安全にコミットとPRを作るワークフローを参照してください。

7. 禁止事項は「強い言い回し」で書く

公式も**「IMPORTANT」「YOU MUST」のような強調語で遵守率が上がる**と明記しています。本テンプレでは❌絵文字を使ってはっきり示しています。曖昧な「なるべく〜しない」は使わないでください。

200行を超えそうになったら：`.claude/rules/`への分割

完全版テンプレを埋めても200行を超える場合は、特定ファイル群にだけ効くルールを.claude/rules/に移します。pathsフロントマターで対象を限定すると、Claudeが該当ファイルを読んだときだけそのルールが追加でロードされます。

---
paths:
  - "src/api/**/*.ts"
---

# API Layer Rules
- すべてのエンドポイントは入力検証をzodで行う
- レスポンスは標準のエラー形式に揃える
- OpenAPIコメントを必ず書く

ディレクトリは次のように整理できます。

your-project/
├── CLAUDE.md              # 全体ルール（200行以内）
└── .claude/
    └── rules/
        ├── api.md          # paths: src/api/**
        ├── ui.md           # paths: src/components/**
        ├── testing.md      # 全体に適用
        └── security.md     # 全体に適用

詳しい配置の指針はClaude Codeに読ませる前に整えるプロジェクト構成で扱っています。

個人専用設定は`CLAUDE.local.md`に分ける

「自分のサンドボックスURL」「自分専用のテストユーザー」など、チームに共有しないがClaudeには伝えたい情報は、CLAUDE.local.mdに書きます。/initで個人用オプションを選ぶか、自分で作って.gitignoreへ登録してください。

# .gitignore
CLAUDE.local.md

CLAUDE.local.mdはCLAUDE.mdと同じディレクトリに置けば自動でロードされ、チーム共有のCLAUDE.mdと矛盾しても自分のローカル指示の方が後勝ちで読み込まれます。

AGENTS.mdが既にあるなら：1行importで両立

OpenAI Codexなど他のコーディングエージェント向けにAGENTS.mdを運用しているプロジェクトでは、CLAUDE.mdの冒頭で@AGENTS.mdを1行importすれば、両ツールで同じルールを参照できます。

@AGENTS.md

## Claude Code固有
- リファクタはPlan Modeで計画してから実行

二重管理を避けつつ、Claude Code固有の指示だけ末尾に追記する形がメンテしやすいです。

完全版運用の最終チェックリスト

ファイルが200行以内に収まっている
7ブロック（概要／触る場所／コーディング／UX／確認コマンド／Git／禁止）が揃っている
依存追加・破壊的変更・秘密情報の3点が禁止事項に明記されている
確認コマンドがそのまま叩ける形で書かれている
自動チェックで守れるルールは書いていない（ESLint・型チェック任せ）
ディレクトリ別ルールは.claude/rules/へ切り出してある
CLAUDE.local.mdを.gitignoreに入れてある
過去に怒られた仕様は「壊してはいけないUX」に追記してある
チーム共有版はgitで管理し、PRレビュー対象になっている

ここまで揃ったら、依頼のたびに同じ前提を書く必要はなくなります。あとは運用しながら磨くだけです。Claudeが同じ失敗を二度したら、その瞬間に追記してください。

次に読む

Claude Codeで最初に作るべきCLAUDE.mdの書き方 — 最小版テンプレートと/initの使い分け
Claude Codeに読ませる前に整えるプロジェクト構成 — 完全版CLAUDE.mdが効きやすい3層構造の作り方
Claude Codeに伝わるプロンプトの基本構造 — CLAUDE.mdに書くべきこととプロンプトに書くべきことの分担

管理人

編集者 / オーナー