43
31

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

CLAUDE.mdベストプラクティスを調べてみた

43
Last updated at Posted at 2026-02-22

2026-08-02 更新
2026年2月の公開後、Claude Codeのメモリまわりは大きく変わりました。以下を反映した最新版です。

  • .claude/rules/ が正式機能になった(frontmatterのキーも変更されているので注意)
  • Claudeが自分でメモを書く auto memory が登場した
  • AGENTS.md との併用方法が公式ドキュメントに明文化された
  • 引用している外部データの数値・リンクを現行版に更新した

はじめに

Claude Codeを使う際、まずCLAUDE.mdを作ると思いますが、プロジェクト共通で読み込む~/.claude/CLAUDE.md、いわばグローバルCLAUDE.mdに皆さんは何を記載しているでしょうか。特に作っていないという人も多いかもしれません。

ここに書いた内容は、どのプロジェクトで作業していても毎回読み込まれる、いわば「個人の共通設定」です。

プロジェクトごとのCLAUDE.mdについては情報が増えてきましたが、このグローバルCLAUDE.mdに何を書くべきかは、意外とまとまった情報がありません。私自身も試行錯誤していたので、Anthropic公式ドキュメントや実践者コミュニティの知見を調べて整理してみました。

この記事では、それらの知見をもとに自分なりにベストプラクティスに従った指示文と、各行を「なぜ入れたのか」「なぜ他は入れなかったのか」をソース付きで解説していきます。

前提知識:メモリ階層とトークンコスト

まず、CLAUDE.mdの仕組みを押さえておく必要があります。Claude Codeのメモリファイルは4つの場所に置くことができ、それぞれ役割が異なります。

ロード順 種別 パス 用途
1 Managed policy /Library/Application Support/ClaudeCode/CLAUDE.md(macOS) 組織全体のポリシー
2 User memory ~/.claude/CLAUDE.md 全プロジェクト共通の個人設定
3 Project memory ./CLAUDE.md or ./.claude/CLAUDE.md チーム共有のプロジェクト設定
4 Project local ./CLAUDE.local.md 個人のプロジェクト固有設定(.gitignore推奨)

Anthropic公式 - How Claude remembers your project

公開当初は「優先度」の表として紹介していましたが、現在の公式ドキュメントは「ロード順」で整理しています。スコープの広いものから順に読み込まれ、作業場所に近い指示ほど後に読まれる(=コンテキストの新しい位置に入る)構造です。

もうひとつ、当時は曖昧だったロードタイミングも明文化されました。作業ディレクトリとその上位階層のCLAUDE.mdは起動時に全文ロードされますが、サブディレクトリのCLAUDE.mdはオンデマンドで、Claudeがその配下のファイルを読んだときに初めてロードされます。

いずれにせよ、グローバルCLAUDE.mdに書いた内容は、どのプロジェクトで作業していても毎回トークンを消費することに変わりはありません。

さらに厄介なのが「指示の希釈効果」です。HumanLayerの解析によると、Claude Codeのシステムプロンプトにはもともと約50個の指示が含まれており、CLAUDE.mdに指示を追加するたびに、すべての指示の遵守率が少しずつ下がっていくそうです。

HumanLayer - Writing a good CLAUDE.md

「指示を増やすほど不安定になる」現象の正体がこれです。グローバルCLAUDE.mdをミニマルに保つべき理由は、単にトークンの節約だけではなく、書いた指示を確実に守らせるためなのです。

フォーマットの原則:なぜ箇条書き・命令形なのか

中身の話に入る前に、「どう書くか」についても触れておきます。

SFEIR Instituteがコンサルティング実績をもとにまとめた定量データが参考になります。

フォーマット 効果
箇条書き vs 散文 遵守率が35%向上
命令形(「〜する」)vs 記述形(「〜している」) 精度が25%向上
バージョン・型の明示 vs 「最新版」 互換性エラーが50%減少

SFEIR Institute - The CLAUDE.md Memory System Tips

この記事を公開した当初(2026年2月時点)では「箇条書きで遵守率60%向上」「150行以下で遵守率25%向上」という数値を紹介していましたが、出典元のSFEIRのページが更新され、現在は箇条書きは35%、行数については具体的な数値の記載がなくなっています(「80〜150行に収める」という推奨は残っています)。

行数の目安は、現在は出典に頼る必要がなくなりました。公式ドキュメントが「1ファイル200行以下」を明示したためです。200行を超えるとコンテキストの消費が増え、遵守率が下がるとはっきり書かれています。

Size: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.
Anthropic公式 - How Claude remembers your project

CLAUDE.mdという文書の性質上、読み手は人間ではなくAIです。ブログ記事のように丁寧に書く必要はなく、むしろ箇条書きで端的に命令するほうが効くというのは、考えてみれば自然な話かもしれません。

また、特に重要な指示に「IMPORTANT」や「YOU MUST」といった強調表現を使うテクニックは、現在は公式ベストプラクティスにも明記されています。ただし全部の指示を強調してしまうと効果が薄れるので、本当に大事なものだけに絞るべきです。

Anthropic公式 - Best practices for Claude Code

グローバルCLAUDE.mdの具体例

以上を踏まえて作成した、グローバルCLAUDE.mdがこちらです。

# コミュニケーション
- 日本語で応答する(コード・変数名は英語)
- 簡潔に回答し、自明な説明は省略する
- 複雑なタスクでは実装前に計画を提示し、承認後に着手する

# コードスタイル
- 関数型アプローチを優先し、副作用を最小化する
- 厳密な型付け(anyは使わずunknownを使う)
- エラーは握りつぶさず、意味のあるメッセージ付きで処理する

# Git規約
- Conventional Commits形式、本文は日本語(例: `feat: ユーザー認証にOAuth2を追加`)
- 確認なしに自動コミット・自動pushしない

# 禁止事項
- README・ドキュメントを勝手に生成・変更しない
- テストコードを確認なしに削除・コメントアウトしない
- 既存の動作するコードを理由なくリファクタリングしない

ここからは、各行がなぜこの指示文に入っているのかを解説していきます。

各セクション解説

1. コミュニケーション

日本語で応答する(コード・変数名は英語)

Claude Codeのデフォルトの応答言語は英語です。日本語環境で使うなら、この指示がないと毎回セッションの冒頭で「日本語でお願いします」と伝えることになります。グローバルCLAUDE.mdに書く理由が最も明確な項目のひとつです。

「コード・変数名は英語」という但し書きも地味に大事で、これがないとClaudeが変数名やコメントまで日本語にしてしまうことがあります。

Anthropic社内のProduct Designチームは、応答のパーソナライズ情報(スキルレベルやペルソナなど)をメモリに含めることで応答品質が劇的に改善したと報告しています。応答言語の指定は、その最も基本的な要素にあたります。

Anthropic - How Anthropic teams use Claude Code(PDF)

簡潔に回答し、自明な説明は省略する

Claudeは親切なので、デフォルトではかなり丁寧に、そして長く応答してくれます。「このコードは〜を行います」「この変更により〜が改善されます」といった説明が続くのですが、慣れた開発者にとってはコードを見ればわかる内容であることがほとんどです。

Shrivu Shankarは大規模なモノレポでの運用記事で、冗長な応答がコンテキストウィンドウを圧迫し、長いセッションになるとパフォーマンスが目に見えて落ちる問題を指摘しています。簡潔さの指示は、読みやすさだけでなくトークンの節約にもつながります。

Shrivu Shankar - How I Use Every Claude Code Feature

複雑なタスクでは実装前に計画を提示し、承認後に着手する

これは個人的にも一番効果を実感している指示です。

Anthropic公式のベストプラクティスでは、「いきなりコーディングに入る」ことを明確にアンチパターンとして挙げています。現在のドキュメントでは、プランモードを使った探索→計画→実装→コミットという4フェーズのワークフローが推奨されています。

Anthropic公式 - Best practices for Claude Code

計画を先に見せてもらうことで、「それ、方向性が違うよ」と早い段階で軌道修正できます。この指示がないと、見当違いの方向に大量のコードを書かれてから手戻りが発生する、という事態が起こりがちです。Teresa Torresも、計画の事前提示をグローバル設定に含めるべき項目として推奨しています。

Mine includes things like:

  • Always create a plan for me to review before you start any work
  • Give me direct feedback (no hedging, no gentle suggestions)
  • Use bullet points for summaries
  • Ask clarifying questions one at a time so I can give complete answers
  • No emojis unless I explicitly ask for them
    Teresa Torres - Give Claude Code a Memory

2. コードスタイル

コードスタイルの指示には、ひとつ重要な線引きがあります。HumanLayerが提唱している原則で、「リンターやフォーマッターで強制できるルールはCLAUDE.mdに書くな」というものです。

HumanLayer - Writing a good CLAUDE.md

セミコロンの有無、引用符の種類、インデント幅。これらはESLintやPrettierで機械的に強制できます。

では何を書くべきか。答えは、リンターでは表現できない設計方針レベルの判断です。

関数型アプローチを優先し、副作用を最小化する

classで書くかfunctionで書くか、状態をミュータブルに扱うかイミュータブルに扱うか。こうした設計思想の選択は、リンターのルールでは強制できません。Claudeはどちらのスタイルでも書けるので、好みがあるなら明示しておく価値があります。

厳密な型付け(anyは使わずunknownを使う)

TypeScriptにおけるanyとunknownの使い分けは、コードの安全性に直結する設計判断です。noImplicitAnyのようなtsconfig設定でもカバーしきれません(開発者が明示的にanyと書くケースは防げないため)。

SFEIRのデータでは、型やバージョンの明示的な指定により互換性エラーが50%減少したとのことです。

SFEIR Institute - The CLAUDE.md Memory System Tips

エラーは握りつぶさず、意味のあるメッセージ付きで処理する

Claudeはタスクを素早く完了しようとする傾向があり、その過程でエラーハンドリングが甘くなることがあります。空のcatchブロックや、console.error(e)だけで済ませるパターンは頻繁に目にします。この指示はプロジェクトの種類によらず、普遍的に当てはまるものです。


3. Git規約

Conventional Commits形式、本文は日本語(例: feat: ユーザー認証にOAuth2を追加)

Anthropic公式のベストプラクティスでも、ブランチ命名やPR規約を含む「リポジトリエチケット」はCLAUDE.mdに書くべき推奨カテゴリとして挙げられています。

Anthropic公式 - Best practices for Claude Code

プレフィックス(feat:, fix:, chore:, docs:)は英語のまま、本文は日本語で書く。この組み合わせにすると、git logの視認性と日本語チームでの扱いやすさを両立できます。

コミットメッセージの形式は全プロジェクトで統一したい典型的な個人設定なので、グローバルCLAUDE.mdに置く正当性が高い項目です。

確認なしに自動コミット・自動pushしない

Claude Codeはタスクの完了時に、こちらが頼んでいないのにコミットやpushを行うことがあります。意図しないコミットがヒストリーに混ざるのは困りますし、まだレビュー前のコードがpushされるのはもっと困ります。

Anthropic社内のRL Engineeringチームも、テストの実行方法やコミットの手順といった具体的なワークフローをCLAUDE.mdに明記することで、一貫性を確保していると報告しています。

Anthropic - How Anthropic teams use Claude Code(PDF)


4. 禁止事項

禁止事項を書くときに意識しておきたいのが、Shrivu Shankarの指摘する「Neverだけ言うのではなく、代替案も示す」という原則です。禁止だけだとClaudeが行き詰まってしまうことがあるためです。

Shrivu Shankar - How I Use Every Claude Code Feature

今回のテンプレートでは、代替行動が自明なもの(「勝手にしない」→「確認してからする」)に限定しているので、明示的な代替案の記述は省略して行数を節約しています。代替行動がわかりにくい禁止事項を入れる場合は、必ずセットで書くようにしてください。

README・ドキュメントを勝手に生成・変更しない

Claudeはタスクを完了したあと、「ついでに」READMEを更新したり、新しいドキュメントファイルを生成したりすることがあります。READMEの内容やフォーマットは人間が管理したいことがほとんどです。勝手に書き換えられると、プルリクエストのレビューで余計な差分が増えてしまいます。

Anthropic公式も、Claudeが「やりすぎる」パターンをCLAUDE.mdで抑制することを推奨しています。

Anthropic公式 - Best practices for Claude Code

テストコードを確認なしに削除・コメントアウトしない

これは実際に遭遇するとかなりヒヤッとする問題です。実装を変更した結果テストが通らなくなったとき、Claudeが「テストのほうを直す」のではなく「テストを消す」ことで対処するケースがあります。

Anthropic社内のRL Engineeringチームも、テスト実行に関する具体的なアンチパターンをCLAUDE.mdに追加し、一貫性が大幅に改善したと報告しています。

Anthropic - How Anthropic teams use Claude Code(PDF)

既存の動作するコードを理由なくリファクタリングしない

「ついでにリファクタリングしておきました」は、Claudeの最もよくある「やりすぎ」のひとつです。頼んでいない箇所をリファクタリングされると、レビューの差分が膨らむだけでなく、意図せずバグを混入するリスクもあります。

なぜこれ以上書かないのか:削った項目とその理由

テンプレートに「何を書いたか」と同じくらい大事なのが、「何を書かなかったか」です。他のテンプレートではよく見かけるのに、あえて入れなかった項目について説明します。

console.logをデバッグ後に残さない

ESLintのno-consoleルールで検出できます。HumanLayerの「リンターで強制できるルールはCLAUDE.mdに書くな」という原則そのものです。

HumanLayer - Writing a good CLAUDE.md

1関数20行以内 / named importを使う

どちらもリンターの設定で制御可能です(max-lines-per-function、no-default-export等)。プロジェクトの.eslintrcで管理すべき領域であり、グローバルCLAUDE.mdに書くとトークンの無駄になります。

ultrathinkで計画を立てる → 削除

特定のthinkingモードの指定は、セッションごとの判断で決めればよいことです。すべてのセッションに強制するほどではなく、必要なときにプロンプトで指示すれば十分です。

1コミット1論理変更 → 削除

Claudeはデフォルトでこれを概ね守ってくれます。わざわざ書く必要性が低く、Anthropic公式のベストプラクティスも「Claudeが元から知っている慣習や自明なプラクティスは書かない」ことを推奨しています(1行ごとに「これを消したらClaudeはミスするか?」と自問し、Noなら削れ、とまで書かれています)。

Anthropic公式 - Best practices for Claude Code

よく使うビルドコマンド → auto memoryに任せる(2026年8月追記)

かつては「ビルドコマンドやテストの実行方法はCLAUDE.mdに書け」が定石でした。ところがこの半年で状況が変わり、この種の「Claudeが作業しながら自分で学べる事実」は、次に紹介するauto memoryが自動で蓄積してくれるようになりました。

※ただし、上記は好みの問題や実際に使ってみてうまくいかないこともあると思うので、プロジェクト横断をして守らせたい制約事項が見つかったら、臨機応変に追記しCLAUDE.mdを育てていくことをおすすめします。

【2026年新機能】Claudeが自分でメモを取る:auto memory

この記事を公開した当初、Claude Codeのメモリは「人間が書くCLAUDE.md」だけでした。現在はもうひとつ、Claudeが自分で書くauto memoryが加わり、デフォルトで有効になっています。

Claudeが作業中に「これは次のセッションでも役立ちそうだ」と判断した情報(ビルドコマンド、デバッグの気づき、コードの癖など)を、自動で~/.claude/projects/<project>/memory/配下に書き溜めていく仕組みです。索引となるMEMORY.mdの冒頭200行(または25KB)が毎セッション自動ロードされ、詳細なメモはトピック別ファイルとして必要なときだけ読まれます。

公式ドキュメントは両者の分担をこう整理しています。

CLAUDE.md auto memory
書くのは 人間 Claude
中身 指示・ルール 学び・パターン
向いている内容 コーディング規約、ワークフロー、禁止事項 ビルドコマンド、デバッグの知見、発見された好み

Anthropic公式 - How Claude remembers your project

この記事のテーマにとって重要なのは、グローバルCLAUDE.mdに書くべきものがまたひとつ減ったという点です。「Claudeに学ばせれば済む事実」は書かず、人間が書くのは「Claudeが自力では判断できない方針・禁止事項」だけ。本記事のテンプレートが指示とルールに絞っているのは、結果的にこの分担とも整合しています。

なお、何が保存されているかは/memoryコマンドでいつでも確認・編集できます。中身はただのMarkdownです。

Progressive Disclosureが正式機能になった:.claude/rules/

公開当初の本記事では、グローバルCLAUDE.mdを索引化して詳細を~/.claude/rules/に分離する方法を「さらに最適化したい場合」の応用テクとして紹介しました。この半年で、この仕組みは正式機能としてドキュメント化され、仕様も固まりました。

仕様確定に伴い、frontmatterのキーが変わっています。公開当初の版で紹介していたglobsは現在の仕様では機能しません。正しくはpathsです。

<!-- ~/.claude/rules/typescript.md -->
---
paths:
  - "**/*.ts"
  - "**/*.tsx"
---
# TypeScriptルール
- satisfiesをasより優先する
- anyは使わずunknownを使う

現在の仕様のポイントは3つです。

  • pathsなしのルールは起動時に無条件ロードされる(CLAUDE.md本体と同じ扱い)
  • pathsありのルールは、マッチするファイルをClaudeが読んだときに初めてロードされる。毎セッションのトークンを消費しない
  • ユーザー版~/.claude/rules/に加えて、プロジェクト版.claude/rules/もある。チームでルールをトピック別ファイルに分割管理できる

symlinkにも対応しているので、共有ルールセットを作って複数プロジェクトにリンクする運用もできます。

SFEIRは、モノリシックな1枚のCLAUDE.mdと比べて.claude/rules/によるモジュール分割はコンテキストノイズを45%削減するとしています。

Anthropic公式 - How Claude remembers your project
SFEIR Institute - The CLAUDE.md Memory System Tips

「毎セッション読み込まれるものを最小にして、条件付きの指示は必要なときだけロードする」という方向性は、公開当初の想定どおりでした。公式機能になったことで、安心して寄りかかれるようになったといえます。

AGENTS.mdとの関係

もうひとつ、この半年で明文化されたのがAGENTS.mdの扱いです。CodexなどClaude Code以外のコーディングエージェントが読むAGENTS.mdを指示の正本にするリポジトリが増えてきましたが、Claude CodeがネイティブにロードするのはあくまでCLAUDE.mdです。

公式ドキュメントが推奨する併用方法は2つあります。

1つめは、CLAUDE.mdから@AGENTS.mdをimportする方法です。共通指示はAGENTS.mdに置き、Claude固有の補足だけをCLAUDE.md側に追記できます。

@AGENTS.md

## Claude Code固有の補足
- (Claude Codeだけに効かせたい指示をここに書く)

2つめはsymlinkです。Claude固有の追記が不要なら、これだけで済みます。

ln -s AGENTS.md CLAUDE.md

@によるimportは起動時に展開されてロードされます(最大4段までネスト可能)。CLAUDE.mdの中でファイルパスに言及したいだけのときは、バッククォートで囲めばimportされません。

Anthropic公式 - How Claude remembers your project

ちなみに、CLAUDE.mdやAGENTS.mdが「いつ読まれるのか」(セッション開始時だけか、途中の変更が反映されるのか)は、以前実験して記事にしました。CodexとClaude Codeで挙動が違ったので、併用している方は合わせてどうぞ。

おわりに

グローバルCLAUDE.mdのベストプラクティスを調べてみて分かったのは、「書くべきこと」よりも「書かなくてよいこと」を見極める方が難しいということです。

そしてこの半年の進化は、その「書かなくてよい領域」をさらに広げる方向に進みました。条件付きの指示はrules/が必要なときだけロードしてくれるようになり、作業から学べる事実はauto memoryがClaude自身の手で蓄積するようになりました。実際、僕自身のグローバルCLAUDE.mdもこの半年でどんどん薄くなり、コードスタイル系の指示はプロジェクト側のrulesへ、環境の細かい気づきはauto memoryへと移っていきました。

いろいろな指示や条件を足していくのは簡単ですが、1つ指示を追加するたびにトークンの使用量が増えたり、他の指示の効きが薄くなってしまう可能性があります。CLAUDE.mdに指示を入れる際は、グローバル、プロジェクト関わらず「リンターでも代替できないか?」「rulesやauto memoryに任せられないか?」など本当にその指示が必要かを吟味するようにしましょう。

内容は、使っている言語やフレームワーク、チームの文化によって最適解は変わりますし、Claude Code自体もアップデートで挙動が変わっていきます(現にこの記事も半年で改訂が必要になりました)。大事なのは、「毎セッション読み込まれるコストに見合う指示か?」という判断基準を持っておくことだと思います。

この記事が、CLAUDE.mdを見直すきっかけになれば嬉しいです。

参考記事

一次情報(Anthropic公式)

情報源 URL
公式メモリドキュメント https://code.claude.com/docs/en/memory
公式ベストプラクティス https://code.claude.com/docs/en/best-practices
社内利用レポート(PDF) https://www-cdn.anthropic.com/58284b19e702b49db9302d5b6f135ad8871e7658.pdf

二次情報

情報源 URL
HumanLayer執筆ガイド https://www.humanlayer.dev/blog/writing-a-good-claude-md
Shrivu Shankar詳細解説 https://blog.sshh.io/p/how-i-use-every-claude-code-feature
SFEIR Institute Tips https://institute.sfeir.com/en/claude-code/claude-code-memory-system-claude-md/tips/
SFEIR Institute Tutorial https://institute.sfeir.com/en/claude-code/claude-code-memory-system-claude-md/tutorial/
43
31
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
43
31

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?