「Claude Code」
今回は知っているようで知らない、Claude Codeの
CLAUDE.mdとは記憶である
前提としてClaude Codeは、立ち上げた際、つまりセッション間で、そのコードベースやユーザーとの過去のやり取りを基本的に覚えていません。しかしセッションを立ち上げるたびに、膨大なコードベースを毎回走査して理解していくのも現実的ではありません。
そのため、コードやルールなどを理解する起点として存在しているのがCLAUDE.
これはエンジニアにとってのREADMEに近いイメージで、Claudeにとって外部記憶領域として存在しているファイルがCLAUDE.
CLAUDE.mdの中身
CLAUDE.
- CLAUDE.
MDに記載する内容の例 -
- コードベースの概要
- 使用技術やライブラリ
- インフラ構成
- コード規約やルール
- テスト規約
これらを人力で記述していくこともできますが、基本的には対話モードで用意された/initコマンドを実行してClaudeに一旦作ってもらうのが一般的かつ網羅的なやり方です。
/init
このコマンドを実行すると、Claudeがプロジェクトの構造を分析し、CLAUDE.
もちろん、生成されたテンプレートはあくまで出発点です。プロジェクトは成長・
何もしないままだとClaudeにうっかり古い情報を渡し続けてしまうことになりますので注意が必要です。
CLAUDE.mdの読み込まれるタイミング
CLAUDE.
つまりclaudeコマンドで対話モードを立ち上げたり/clearコマンドで新たにセッションを立ち上げた時にClaudeのコンテキストに保持されます。
ですので、コードの大きな変更の都度、ユーザーがCLAUDE.
特に重大な変更の場合は/clearでセッションを新たにロードするか
階層的な配置
巨大なコードベースになればなるほど、CLAUDE.
そこでClaude Codeでは、サブディレクトリにもCLAUDE.
project/
├── CLAUDE.md # プロジェクト全体の設定
├── frontend/
│ └── CLAUDE.md # フロントエンド固有の設定
└── backend/
└── CLAUDE.md # バックエンド固有の設定
Claude Codeは再帰的にこれらのファイルを読み込み、コンテキストとして解釈に含めます。これにより、フロントエンドの作業中はフロントエンド固有のルールが、バックエンドの作業中はバックエンド固有のルールが適用されるようになります。
また、ユーザー自身が動かすすべてのClaude Codeにルールを適用したい場合は、ホームディレクトリ配下の以下のパスにCLAUDE.
~/.claude/CLAUDE.md
このグローバルなCLAUDE.
階層ファイルの読み込みタイミングとLazyLoad
先ほどプロジェクトルートのCLAUDE.
しかし、この階層構造において、CLAUDE.
/
├── ~/.claude/CLAUDE.md ← グローバル設定（読み込まれる）
└── ~/project/
├── CLAUDE.md ← プロジェクトルート（読み込まれる）
└── src/
└── CLAUDE.md ← サブディレクトリ（まだ読み込まれない）
現在のワーキングディレクトリから上位方向
~/project/
├── CLAUDE.md ## ← 起動時に読み込み済み
├── frontend/
│ └── CLAUDE.md ## ← frontend/内のファイルを触った時に読み込み
└── backend/
└── CLAUDE.md ## ← backend/内のファイルを触った時に読み込み
一方、下位方向
この遅延読み込みの仕組みにより、巨大なモノレポ[1]でも必要な時に必要な情報だけがコンテキストに追加され、コンテキストウィンドウを効率的に活用できます。
現在どのCLAUDE./memoryコマンドで確認できます。
/memoryコマンドの実行結果│ Select memory to edit: │ │ │ │ ❯ 1. User memory Saved in ~/.claude/CLAUDE.md │ │ 2. Project memory Checked in at ./CLAUDE.md │ │ 3. L doc/ER_DIAGRAM.md @-imported │ │ 4. L doc/SCREEN_DESIGN.md @-imported │ │ 5. L doc/API_SCHEME.md @-imported
CLAUDE.local.mdによる個人用設定の分離
チーム開発において、CLAUDE.
この問題を解決するために、Claude CodeではCLAUDE.という仕組みが用意されています。
settings.設定ファイルにもチーム共有のためのGit管理されるsettings.と、個人設定のためのsettings.が両方存在しているので、お馴染みな方も多いでしょう。
project/
├── CLAUDE.md # チーム共有（Git管理）
├── CLAUDE.local.md # 個人用（.gitignoreに自動追加）
└── .claude/
├── settings.json # チーム共有
└── settings.local.json # 個人用（.gitignoreに自動追加）
CLAUDE.はプロジェクトルートに配置でき、個人の環境固有の設定を保存できます。重要なのは、このファイルは.gitignoreに自動的に追加されるため、Gitにコミットされる心配がありません。
例えば、以下のような内容をCLAUDE.に記載できます。
CLAUDE.local.mdの記載例# 個人環境設定
- ローカルの開発サーバーは http://localhost:3000 で動作している
- テスト用のDBはDockerで localhost:5432 に起動している
- APIのモックサーバーは ./mocks/server.js を使用
# 個人的な設定
- コードの説明は日本語でお願いします
- コミットメッセージも日本語で書いてください
ただしGit管理されないことで履歴を追いづらかったり、うっかり変更や削除してしまうと後追いができません。
また共有のCLAUDE.
ファイル参照機能
CLAUDE.@記法を使って他のファイルをインポートできます。
@記法の例詳細な仕様はこちら @docs/SPECIFICATION.md
DBのスキーマはこちら @schema/DB.md
これにより、複数の情報を分散管理しながら、必要に応じて参照させることができます。例えば、詳細なAPI仕様書やデータベーススキーマなど、それ自体が独立したドキュメントとして管理されているファイルを、CLAUDE.
インポートには相対パスと絶対パスの両方が使えます。
@docs/api-spec.md # 相対パス
@~/.claude/common-rules.md # ホームディレクトリからの絶対パス
また、インポートされたファイルの中からさらに別のファイルをインポートすることも可能です。これにより、ドキュメントをモジュール化して管理できます。
ただし注意点があります。`@docs/のようにコードスパン
これは、@anthropic-ai/のようなnpmパッケージ名や、Pythonのデコレータ記法との衝突を避けるための仕様です。
個人的な経験ではClaude Code自身にCLAUDE.
またファイル参照が便利だからといって、特にプロジェクトルートに全ての仕様を詰め込むと肥大化してしまいがちです。
CLAUDE.⚠ Large CLAUDE.という警告が出るようになります。
そういった時は上述したディレクトリ分けによる遅延読み込みや、これからお伝えするrulesで分割することにしてください。
.claude/rulesディレクトリ
2025年12月のアップデートで、CLAUDE..claude/ディレクトリという新しい仕組みが導入されました。
your-project/
├── .claude/
│ ├── CLAUDE.md # メインのプロジェクト設定
│ └── rules/
│ ├── code-style.md # コーディングスタイルのルール
│ ├── testing.md # テストに関する規約
│ └── security.md # セキュリティ要件
これまでは一つのCLAUDE..claude/ディレクトリを使うことで、上記のようにユーザーが任意の名前をつけることで、関心ごとにルールファイルを分割して管理できるようになりました。
さらに強力なのが、pathsディレクティブです。各ルールファイルのフロントマターにpathsフィールドを記載することで、Globパターンに基づいた、特定のファイルパターンにのみルールを適用できます。
以下はその例です。
pathsディレクティブの記載例---
paths: src/**/*.{ts,tsx}
---
# TypeScript/Reactのコーディングルール
- コンポーネントは関数コンポーネントで記述すること
- PropsにはTypeScript型定義を必ず付けること
またPathsはカンマ区切りで複数のパスパターンを指定することも可能です。
---
paths: {src,lib}/**/*.ts, tests/**/*.test.ts
---
これにより、ディレクトリ構造に依存せず、ファイルの種類や用途に応じてきめ細かくルールを適用できるようになりました。
さらに.rules配下のメモリーファイルの特徴として、シンボリックリンクがサポートされています。
# 共有のルールファイルからシンボリックリンクを貼ってプロジェクトに適応させる ln -s ~/shared-rules .claude/rules/shared # 組織で統一したルールをプロジェクトに適応させる ln -s ~/company-rule/security.md .claude/rules/security.md
シンボリックリンクでの管理は上手に使わないと逆に煩雑になる事もありますが、特定のルールなどを統一しておきたい、再利用したい場合などに便利です。
なお、CLAUDE.
CLAUDE.mdの指示が無視される理由
ここまでCLAUDE.
おそらくコミュニティで調査されている内容から総括すると、Claude CodeはCLAUDE.
これは公式ドキュメントに記載されている一次情報ではありませんが、HumanLayerというAIスタートアップの技術ブログや、データサイエンティストのJannes Klaas氏のブログで、それぞれClaude Codeの通信をプロキシで解析して発見したと報告されています。GitHubのIssue#7571にも同様の報告が上がっています。
具体的に言うと、CLAUDE.
<system-reminder>
IMPORTANT: this context may or may not be relevant to your tasks.
You should not respond to this context unless it is highly relevant to your task.
</system-reminder>
日本語訳：
つまり、Claudeは
関連性が低いと判断した指示は無視してしまう事があると考えられるのです。
この意図ははっきり明言されていませんが、おそらくコンテキストの効率化や精度向上のためのチューニングのためであろうとは言われています。
必要な関連情報だけを優先して理解できるようにした方がClaude Codeの動作にとって都合が良かったのだろうと思います。
Cursorのrules[2]のようにメモリーファイル自体にその適応度を指示できる機能が付く日を心待ちにしています。
指示を確実に守らせるには
しかし例えばLintチェックや、重要な規約チェックなどは守ってくれないと困ることがあります。
では、どうすれば指示を確実に守らせることができるでしょうか。
まずCLAUDE.
例えば下記のような記述です。
# テストコード作成時の厳守事項
テストを書く際は以下を必ず守ってください：
- テストは必ず実際の機能を検証すること
- `expect(true).toBe(true)` のような意味のないアサーションは書かない
「テストコード作成時の」
settings.jsonのinstructionsの活用
それでも無視される場合は、.claude/のinstructionsフィールドに記載する方法があります。
{
"instructions": "TypeScript/JavaScriptファイルを作成・編集した後は、必ずlintチェックを実行すること",
"permissions": {
"allow": [
"Bash(npm run lint:*)"
]
}
}
CLAUDE.settings.に記載された指示は、CLAUDE.
遅延読み込みによるコンテキスト効率化（非公式）
最後に、公式ドキュメントには記載されていない内容ですが、 段階的開示
前述したHumanLayerのブログで紹介されていた手法です。あえて@によるインポートを使わず、Claudeに必要な時にファイルを読ませることでコンテキストを節約しながら効率的に活用します。
例えば下記のようなものです。
# テスト規約
テストを書く際は ./docs/test_define.md を参照してください
このように書くことで、Claudeがテストを書こうとした時に自発的にファイルを読みに行くことが期待出来ます。
前述のrulesの仕組みではファイルの拡張子やディレクトリベースのみですが、
まとめ
CLAUDE.
次回は、セキュリティ対策とエンタープライズ企業への導入について、筆者が実際に取り組んでいることをお話しできればと思います。お楽しみに！
イベント：AIツール導入時のポイントを抑え、安心して取り組むAI駆動開発
平川さんが登壇するFindy様主催のオンラインイベントが
平川さんが執筆した
なお、参加には事前にconnpassでの登録が必要です。皆様、ぜひご参加ください。