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

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

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

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

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

この順序は、公式の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に書くべきこととプロンプトに書くべきことの分担