はじめに
この文書は、Claude Code 初学者が ~/.claude/CLAUDE.md の役割を理解し、汎用的で拡張性のある設定を安全に運用できるようまとめたガイドです。
ここで扱う ~/.claude/CLAUDE.md は、特定のプロジェクトだけではなく、Claude Code を利用するすべてのプロジェクトに適用する個人用の共通指示ファイルです。
最も重要な考え方は、次のとおりです。
~/.claude/CLAUDE.mdには、Claude Code がコードやリポジトリを調べても分からない、ユーザー個人の共通設定だけを書く。
公式資料:
1. CLAUDE.md とは
CLAUDE.md は、Claude Code に継続的な指示を与えるための Markdown ファイルです。
通常のチャットで毎回同じ指示を入力しなくても、Claude Code がファイルを読み込み、そこに書かれた方針を作業時の参考にします。
たとえば、次のような個人的な希望を記述できます。
- 原則として日本語で回答してほしい
- コマンドや識別子は英語のまま維持してほしい
- 簡単な質問は短く、複雑な調査は詳しく説明してほしい
- 質問する前に、既存のコードや資料を確認してほしい
- 実行していないテストを「成功した」と報告しないでほしい
~/.claude/CLAUDE.md の意味
パスの先頭にある ~ は、現在のユーザーのホームディレクトリを表します。
Windows の一般的な保存場所は次のとおりです。
%USERPROFILE%\.claude\CLAUDE.md
例:
C:\Users\your-name\.claude\CLAUDE.md
macOS または Linux では、通常は次の場所です。
~/.claude/CLAUDE.md
2. グローバルファイルとプロジェクトファイルの違い
Claude Code の指示は、目的に応じて配置場所を分けます。
| 配置場所 | 主な目的 |
|---|---|
~/.claude/CLAUDE.md |
すべてのプロジェクトに共通する個人設定 |
<project>/CLAUDE.md |
特定プロジェクトのコマンド、規約、注意点 |
<project>/CLAUDE.local.md |
特定プロジェクトだけで使う個人的な設定 |
<project>/.claude/rules/*.md |
特定パスやファイルに限定した規則 |
skills/<name>/SKILL.md |
再利用可能な複数ステップの作業手順 |
agents/<name>.md |
専門的なサブエージェントの役割 |
settings.json |
model、permissions、sandbox、Hooks などの設定 |
判断例
グローバルファイルに適する内容
原則として日本語で回答する
技術用語やコマンドは原語を維持する
未検証事項を明確に報告する
プロジェクト側に適する内容
テストは uv run pytest で実行する
パッケージ管理には pnpm を使用する
src/generated/ は直接編集しない
Unreal Engine の命名規則に従う
pytest や pnpm などの指定は、すべてのプロジェクトに共通するとは限りません。そのため、通常はプロジェクト側の CLAUDE.md に記載します。
3. なぜ短く保つ必要があるのか
~/.claude/CLAUDE.md は、多くのセッションで読み込まれます。
ファイルが長すぎると、次の問題が起こりやすくなります。
- 現在の作業と無関係な指示まで読み込まれる
- 重要な指示が大量の文章に埋もれる
- 指示同士が重複または競合する
- 古い規則が残り続ける
- Claude Code が過剰に慎重になり、簡単な作業でも停止する
- プロジェクト固有の規約が別プロジェクトへ誤適用される
したがって、行数を増やすことではなく、必要な情報だけを残すことが重要です。
短ければよいわけでもありません。必要な個人設定まで削除すると、毎回同じ指示を入力し直すことになります。
目標は、最短ではなく必要十分です。
4. 最終推奨テンプレート
以下を ~/.claude/CLAUDE.md に保存することを推奨します。
# Personal Defaults
These preferences apply across all projects. Keep project-specific knowledge,
commands, conventions, and workflows in the repository that owns them.
## Communication
- Respond in Japanese unless I request another language.
- Preserve code, commands, identifiers, paths, configuration keys, API names,
and established technical terms in their original form.
- Be concise for simple tasks and detailed when complexity or risk requires it.
- Prefer concrete evidence, findings, commands, file paths, and actionable next
steps over generic advice.
- State material assumptions, uncertainties, blockers, and unverified claims.
## Collaboration
- Inspect available context before asking questions.
- Proceed without unnecessary confirmation when the request is clear,
authorized, low risk, and reversible.
- Ask only when unresolved ambiguity could materially change the outcome.
- Preserve unrelated user changes and avoid work outside the requested scope.
## Reporting
- Distinguish completed, verified, partially verified, and unverified work.
- Never report a check as passed unless it was actually run successfully.
- Keep completion reports proportional to the task.
テンプレートを英語で記述している理由は、Claude Code が技術的な指示を安定して解釈しやすく、英語のコマンド、設定名、API 名との対応も維持しやすいためです。
これは必須ではありません。日本語で記述しても動作します。ただし、設定ファイル内では簡潔で曖昧性の少ない英語を使い、Claude Code からの回答言語を日本語に指定する構成が扱いやすいです。
5. テンプレートの詳細説明
5.1 Personal Defaults
# Personal Defaults
この見出しは、ファイルが組織規則やプロジェクト規則ではなく、ユーザー個人の既定値であることを示します。
These preferences apply across all projects. Keep project-specific knowledge,
commands, conventions, and workflows in the repository that owns them.
この文章には二つの目的があります。
- このファイルは全プロジェクト共通であると示す
- プロジェクト固有情報をグローバルファイルへ追加しないようにする
テンプレートを将来拡張するときの境界線として機能します。
5.2 Communication
原則として日本語で回答する
- Respond in Japanese unless I request another language.
通常は日本語で回答しますが、ユーザーが英語を指定した場合は英語を使用します。
技術要素を原語のまま維持する
- Preserve code, commands, identifiers, paths, configuration keys, API names,
and established technical terms in their original form.
説明文を日本語にしても、次のような要素は翻訳しません。
settings.json
permissionMode
PreToolUse
Stop hook
git status
pytest
UnrealBuildTool
CriAtomExPlayer
コマンドや設定名を翻訳すると、そのままコピーして使用できなくなるためです。
説明量をタスクに合わせる
- Be concise for simple tasks and detailed when complexity or risk requires it.
簡単な質問に長大な解説を返したり、複雑な不具合調査を一文で済ませたりすることを防ぎます。
例:
- コマンドの意味: 簡潔に回答
- 小さな設定変更: 変更内容と確認結果を短く報告
- アーキテクチャ設計: 理由とトレードオフを詳しく説明
- 不具合調査: 根拠、仮説、確認方法を詳しく説明
具体的で実行可能な情報を優先する
- Prefer concrete evidence, findings, commands, file paths, and actionable next
steps over generic advice.
「適切にテストしてください」のような抽象的な助言だけで終わらず、分かる範囲で具体的なコマンド、対象ファイル、確認方法を示すようにします。
不確実な内容を明示する
- State material assumptions, uncertainties, blockers, and unverified claims.
次の状態を区別して報告させるための指示です。
- コードから直接確認できた事実
- 合理的な推測
- 実行して確認した結果
- 未検証の想定
- 環境不足で確認できなかった内容
5.3 Collaboration
質問前に既存情報を確認する
- Inspect available context before asking questions.
答えが会話、コード、設定、テスト、ドキュメント、エラーログに存在する場合は、すぐにユーザーへ質問せず、まず既存情報を確認します。
低リスクな作業は自律的に進める
- Proceed without unnecessary confirmation when the request is clear,
authorized, low risk, and reversible.
次の条件を満たす場合は、確認を何度も挟まずに作業します。
- 依頼内容が明確
- ユーザーが実行を依頼している
- 影響が小さい
- 容易に元へ戻せる
例:
- 指定された文書の修正
- ローカルコードの小規模な変更
- 単体テストの追加
- lintやformatの実行
- 新しい出力ファイルの作成
結果を左右する曖昧性だけ質問する
- Ask only when unresolved ambiguity could materially change the outcome.
些細な不明点では作業を止めず、結果を大きく変える場合だけ質問します。
質問が必要になりやすい例:
- 対象プラットフォームによって実装が変わる
- 後方互換性を維持する必要があるか不明
- 破壊的変更を許容するか不明
- 複数の仕様解釈で成果物が大きく変わる
- 公開、課金、権限変更を伴う
ユーザーの既存変更と依頼範囲を守る
- Preserve unrelated user changes and avoid work outside the requested scope.
次のような問題を防ぎます。
- 無関係な未コミット変更の上書き
- 依頼されていないリファクタリング
- 無関係なformat変更
- 不要な依存関係更新
- 別機能のついで修正
5.4 Reporting
完了状態と検証状態を区別する
- Distinguish completed, verified, partially verified, and unverified work.
| 状態 | 意味 |
|---|---|
| Completed | 依頼された変更や作成を完了した |
| Verified | 必要な検証を実行し、成功を確認した |
| Partially verified | 一部の検証だけを実行した |
| Unverified | 作業は完了したが、動作確認は未実施 |
ファイルを変更したことと、その変更が正しく動くことは別です。
未実行チェックを成功扱いしない
- Never report a check as passed unless it was actually run successfully.
正しい報告例:
修正は完了しました。
単体テストは成功しました。
統合テストは必要な環境変数がないため未実行です。
不適切な報告例:
すべて問題ありません。
テスト、build、lint、typecheckを実行していない場合は、その事実を明示する必要があります。
報告量を作業規模に合わせる
- Keep completion reports proportional to the task.
1行の修正で長い報告書を作る必要はありません。一方、複雑な不具合調査では、原因、根拠、検証結果、残るリスクを説明する必要があります。
6. このファイルに書かない方がよい内容
固定されたテストコマンド
- Always run pytest.
- Always run pnpm test.
プロジェクトによって正しいコマンドが異なるため、対象リポジトリの CLAUDE.md に記述します。
特定技術の規則
- Use Ruff for Python.
- Follow Unreal Engine naming conventions.
- Use CRIWARE-specific error helpers.
これらも該当するプロジェクトへ配置します。
長い作業フロー
調査 → 計画 → 承認 → 実装 → レビュー → 修正 → 全テスト → 報告
複雑な作業には有効ですが、単純な修正には過剰です。再利用したい長い手順は Skill に分離します。
サブエージェントの常時使用
- Always delegate implementation to the implementer agent.
- Always delegate review to the reviewer agent.
小規模作業でも処理が重くなるため、全タスク共通にはしません。必要な条件は Agent 定義、Skill、またはプロジェクト側で指定します。
自然言語だけによる絶対禁止
- Never run git push.
- Never read .env.
- Never access production.
文章による指示は、絶対的な技術制御ではありません。例外を許さない場合は、permissions、deny rules、sandbox、Hooks、CI、branch protectionなどを使用します。
7. 拡張時の配置判断
新しい指示を追加したいときは、次の順序で判断します。
すべてのプロジェクトに共通する個人的な好みか？
├─ Yes → ~/.claude/CLAUDE.md
└─ No
├─ 特定プロジェクト全体の知識・規約か？
│ └─ Yes → <project>/CLAUDE.md
├─ 個人的だが特定プロジェクトだけの指示か？
│ └─ Yes → <project>/CLAUDE.local.md
├─ 特定パスだけに適用する規則か？
│ └─ Yes → <project>/.claude/rules/*.md
├─ 再利用可能な複数ステップの手順か？
│ └─ Yes → skills/<name>/SKILL.md
├─ 専門的な役割として委任する内容か？
│ └─ Yes → agents/<name>.md
└─ 絶対に実行または禁止する必要があるか？
└─ Yes → Hooks / permissions / deny rules / sandbox / CI
8. プロジェクト側の CLAUDE.md 記述例
グローバルファイルを短く保つ代わりに、具体的な情報は対象リポジトリへ記述します。
# Commands
- Install: `uv sync`
- Run one test: `uv run pytest tests/path/test_file.py -q`
- Lint: `uv run ruff check .`
- Typecheck: `uv run mypy src`
# Conventions
- Use the error types defined in `src/errors.py`.
- Keep network access behind `src/client/`.
- Do not copy patterns from `src/legacy/` into new code.
# Gotchas
- Integration tests require `SERVICE_API_KEY`.
- Files under `src/generated/` are generated from `schema/openapi.yaml`.
プロジェクト側では、次の情報が特に有用です。
- 正確なinstall、test、lint、typecheckコマンド
- 単一テストを実行する方法
- コードから誤解しやすい箇所
- チームで決定したがコードには現れていない判断
- 必要な環境変数
- generated filesの生成元
- 同じ誤りを何度も修正した事項
9. 新しい指示を追加するためのチェックリスト
次の5項目をすべて満たす場合だけ、~/.claude/CLAUDE.md への追加を検討します。
- 複数の異なるプロジェクトで有効である
- リポジトリを読んでも判断できない
- 個人的な好みまたは協働方針である
- ほぼすべてのセッションで有益である
- Settings、Rule、Skill、Agent、Hookの責務ではない
一つでも満たさない場合は、別の配置先を検討します。
追加候補になりやすい状況
- 異なるプロジェクトで同じ点を2回以上修正した
- 毎回同じ個人的な希望を説明している
- Claude Code が質問する前に確認してほしい情報がある
- 完了報告の方法について繰り返し修正している
10. 削除または移動の基準
次の状態になった指示は、削除または適切な場所へ移します。
- 特定のリポジトリでしか使用しない
- 特定のディレクトリでしか使用しない
- 固定コマンドを含んでいる
- 長い作業手順になった
- Agentの役割説明になった
- 例外を許可できない規則になった
- コードから簡単に判断できる
- Claude Code の標準動作と重複している
- 別の指示と重複または競合している
- 頻繁に例外が発生する
- 現在は存在しないファイルやコマンドを参照している
11. 作成手順
Windows PowerShell
-
.claudeフォルダを作成します
New-Item -ItemType Directory -Force "$HOME\.claude"
-
CLAUDE.mdを開きます
notepad "$HOME\.claude\CLAUDE.md"
- 本文書の「最終推奨テンプレート」を貼り付けて保存します
Visual Studio Code
code "$HOME\.claude\CLAUDE.md"
code コマンドが使用できない場合は、Visual Studio Code のコマンドパレットから Shell Command: Install 'code' command in PATH に相当する設定を確認するか、エクスプローラーからファイルを開きます。
macOS / Linux
mkdir -p ~/.claude
nano ~/.claude/CLAUDE.md
Visual Studio Code を使用する場合:
code ~/.claude/CLAUDE.md
12. 読み込みと監査
Claude Code 上で、利用可能な場合は次のコマンドを使って状態を確認します。
/context all
/doctor
/doctor prompt-audit
| コマンド | 主な用途 |
|---|---|
/context all |
CLAUDE.md が読み込まれているか確認する |
/doctor |
設定や指示の問題を確認する |
/doctor prompt-audit |
古い指示、矛盾、無効な参照を確認する |
Claude Code のバージョンによって利用可能な診断コマンドや表示内容が変わる可能性があります。実際の環境で /help も確認してください。
推奨する監査タイミング
-
CLAUDE.mdを追加または変更した直後 - 同じ不満や修正が2回以上発生したとき
- Rules、Skills、Agents、Hooksを追加した後
- Claude Code の大きなアップデート後
- 3か月から6か月ごと
- 指示項目が20個を超えたとき
13. 初学者が陥りやすい失敗
失敗1: すべてをグローバルファイルへ書く
プロジェクト固有のコマンドまで書くと、別のプロジェクトで誤適用されます。
対策: その情報を所有するリポジトリの CLAUDE.md へ移します。
失敗2: 長ければ詳しくて良いと考える
長いファイルは重要な指示を埋もれさせます。
対策: 個人差分だけを残し、手順はSkills、規則はRulesへ分離します。
失敗3: IMPORTANT や NEVER を大量に使用する
すべてを最重要にすると、実際の優先順位が不明になります。
対策: 絶対制御が必要なら、permissions、Hooks、deny rules、sandbox、CIを使います。
失敗4: 毎回ユーザー確認を必須にする
小さな修正でも作業が止まり、自律性が低下します。
対策: 明確、承認済み、低リスク、可逆的な作業はそのまま進めるよう指定します。
失敗5: 実行と検証を混同する
ファイルを変更できても、動作するとは限りません。
対策: Completed、Verified、Partially verified、Unverifiedを区別します。
失敗6: 一度作った設定を見直さない
コマンド、ファイル、Claude Code の機能が更新され、指示が古くなる可能性があります。
対策: 定期的に監査し、不要な行を削除します。
14. 最終チェックリスト
導入前に次を確認してください。
-
ファイルは
~/.claude/CLAUDE.mdに保存されている - 原則として日本語で回答する設定になっている
- コマンドや識別子を翻訳しない設定になっている
- プロジェクト固有のコマンドを含んでいない
- 特定技術だけに有効な規則を含んでいない
- 長い作業手順を含んでいない
- サブエージェントの常時使用を強制していない
- 実行していない検証を成功扱いしない設定がある
- unrelatedなユーザー変更を保護する設定がある
- 重大な曖昧性だけ質問する方針になっている
- 絶対禁止は自然言語だけに依存していない
- 読み込み状態を確認した
15. まとめ
~/.claude/CLAUDE.md は、Claude Code を細部まで制御する巨大な運用マニュアルではありません。
最適な役割は、次のような全プロジェクト共通の個人設定を伝えることです。
- 日本語で回答する
- 技術用語を原語のまま扱う
- タスクに応じて説明量を調整する
- 抽象論より具体的な根拠と操作を優先する
- 質問する前に既存コンテキストを確認する
- 低リスクな作業では不要な確認を挟まない
- unrelatedなユーザー変更を保護する
- 完了と検証を区別する
- 未実行のチェックを成功扱いしない
プロジェクト固有情報はプロジェクト側へ、長い作業手順はSkillsへ、専門的な役割はAgentsへ、特定パスの規則はRulesへ、絶対的な制御はHooks、permissions、sandbox、CIへ分離します。
この責務分離を守ることで、~/.claude/CLAUDE.md を短く、明確で、汎用的かつ拡張しやすい状態に維持できます。