「Claude Code を使っているけど、CLAUDE.md をちゃんと書いていない」 という人、かなり多いのではないでしょうか。
実はこのファイル1つで、Claude Code の出力品質は驚くほど変わります。僕は Mac mini M4 Pro 上で24時間稼働する AI エージェントシステムを運用していて、CLAUDE.md と .claude/rules/ の設計には相当こだわってきました。この記事では、実際に本番運用しているプロジェクトの設定をそのまま公開しながら、書き方のコツを解説します。
筆者は福祉事業の IT 全般を担当する CTO と個人事業（開発受託・コンサル）を兼業しているエンジニアです。Claude MAX を契約し、Ghostty + tmux + Claude Code で日々の開発を回しています。
この記事を読むと、以下のことがわかります。
- CLAUDE.md の役割と配置場所の使い分け
- 実プロジェクトの設定を見ながら「何を書くべきか」が具体的にわかる
.claude/rules/でルールを分割管理する方法- セキュリティ設定や MCP サーバー連携の実例
- やりがちな失敗パターンとその回避策
CLAUDE.md とは何か
CLAUDE.md は、Claude Code がセッション開始時に自動で読み込むプロジェクト固有の指示書です。.gitignore がファイル管理のルールなら、CLAUDE.md は AI との協業ルール を定義するファイルだと考えるとわかりやすいでしょう。
このファイルに書いた内容は、そのセッション中ずっと Claude のコンテキストに含まれます。つまり「毎回プロンプトで説明していたこと」を1回書くだけで済むようになります。
CLAUDE.md がない場合:
「TypeScript で書いて」「ESModules で」「テストは vitest で」
「コミットメッセージは日本語で」... 毎回指示が必要
CLAUDE.md がある場合:
すべて自動で反映。指示は「この機能を実装して」だけでOK
Claude Code の生産性をさらに上げる方法も合わせて読むと、全体像が掴めます。
ファイル階層と読み込みの仕組み
CLAUDE.md は1箇所に置くだけでなく、複数の階層に配置して使い分けるのが実践的です。
ユーザーレベル（全プロジェクト共通）"] --> D[Claude Code セッション] B["./CLAUDE.md
プロジェクトルート（チーム共有）"] --> D C["./src/auth/CLAUDE.md
サブディレクトリ（モジュール固有）"] --> D E[".claude/rules/*.md
トピック別ルール（自動読み込み）"] --> D F["CLAUDE.local.md
個人設定（.gitignore対象）"] --> D style A fill:#e8f4f8,stroke:#39b7ff style B fill:#d4edda,stroke:#28a745 style C fill:#fff3cd,stroke:#ffc107 style E fill:#f0e6ff,stroke:#6f42c1 style F fill:#f8d7da,stroke:#dc3545
| 配置場所 | 用途 | 読み込みタイミング |
|---|---|---|
~/.claude/CLAUDE.md |
全プロジェクト共通の個人設定 | セッション開始時 |
./CLAUDE.md |
プロジェクトのメイン設定 | セッション開始時 |
./CLAUDE.local.md |
個人の好み（.gitignore 対象） |
セッション開始時 |
.claude/rules/*.md |
トピック別の詳細ルール | セッション開始時（全ファイル自動） |
./src/*/CLAUDE.md |
サブディレクトリ固有の指示 | そのディレクトリで作業時 |
ポイントは 「より具体的な設定が優先される」 こと。プロジェクトルートの設定よりも、サブディレクトリの設定が優先されます。
実際のCLAUDE.mdを公開して解説
僕が運用している AI エージェントシステム（masu-agent）の CLAUDE.md を、セクションごとに解説します。
1. プロジェクト概要
# Masu Agent System
## プロジェクト概要
個人事業（開発受託・コンサルティング・コンテンツ制作）の業務を
効率化するAIエージェントシステム。
Mac mini M4 Pro (24GB) 上で24時間稼働。
なぜ書くのか: Claude に「このプロジェクトが何なのか」を理解させるため。概要がないと、Claude はコードの断片だけから推測することになり、的外れな提案をしがちです。
2. アーキテクチャ概要
## アーキテクチャ概要
インターフェース層 → Agent Core → データベース → ナレッジベース
(Discord) (Claude SDK) (SQLite)
なぜ書くのか: 全体構成を示すことで、新しいファイルをどこに置くか、どのレイヤーに手を入れるべきかを Claude が正しく判断できます。
3. テクノロジースタック
## テクノロジースタック
- **言語**: TypeScript (Node.js)
- **モジュール**: ESModules (import/export)
- **パッケージ管理**: npm workspaces（モノレポ）
- **データベース**: SQLite
- **エージェント基盤**: Claude Agent SDK (@anthropic-ai/claude-code)
なぜ書くのか: これがないと Claude は「CommonJS か ESModules か」「yarn か npm か」を毎回推測します。明示しておけば、生成コードの import/require の書き分けや package.json の構成が一発で正確になります。
TypeScript 開発環境の構築と組み合わせると、さらに快適になります。
4. コーディング規約
## コーディング規約
- TypeScript strict mode使用
- 日本語コメント推奨（コード自体は英語）
- エラーハンドリングは必ず実装（try/catch + ログ出力）
- 関数には必ずJSDocコメントを記載
- テストは `*.test.ts` ファイルで記述
実際に運用して気づいたのは、「日本語コメント推奨」の一行があるだけで、Claude が自然に日本語でコメントを書いてくれるようになること。逆にこの指示がないと、英語コメントと日本語コメントが混在して読みづらくなります。
5. Git 規約
## Git 規約
- コミットメッセージは**日本語**で記述する
- 1行目: 変更内容の要約（50文字以内目安）
- 2行目: 空行
- 3行目以降: 詳細（箇条書き推奨）
地味に重要なセクション。コミットメッセージの言語を指定しないと、Claude はデフォルトで英語で書きます。日本語のプロジェクトなら明示的に指定しましょう。
6. 作業ディレクトリのルール
## 作業ディレクトリ
- `agent-workspace/`: 一時作業領域。自由に読み書き可能
- `agent-output/{YYYYMMDD}-{filename}/`: 成果物の永続保存先
## 成果物の保存ルール
1. 成果物は必ず `agent-output/` 以下に保存
2. 一時ファイルは `agent-workspace/` で作業し、完了したら削除
masu-agent では、Claude が成果物を保存する場所を厳密に定義しています。これがないと、プロジェクトルートに output.txt みたいなファイルが散らばります。
7. サブエージェント権限マトリクス
## サブエージェント権限マトリクス
| エージェント | Read | Edit | Bash | WebSearch |
|---------------|------|------|------|-----------|
| research-agent | YES | NO | NO | YES |
| content-agent | YES | YES | NO | YES |
| dev-agent | YES | YES | YES | YES |
複数のサブエージェントを使い分ける設計の場合、権限マトリクスを CLAUDE.md に書いておくと、「このエージェントは Bash を使えない」といった制約を Claude が理解したうえでコードを書いてくれます。
.claude/rules/ でルールを分割管理する
CLAUDE.md が長くなりすぎると、逆効果です。目安は50〜100行。それを超える詳細ルールは .claude/rules/ に分割します。
masu-agent では以下の3ファイルに分けています。
.claude/rules/
├── security.md # セキュリティポリシー
├── output-rules.md # 成果物の保存・命名規則
└── mcp-masu-db.md # 自作MCP サーバーの操作ガイド
.claude/rules/ 内の .md ファイルはすべて自動で読み込まれます。設定ファイルへの登録は不要です。
分割の判断基準
| CLAUDE.md に残す | rules/ に分離する |
|---|---|
| プロジェクト概要 | セキュリティの詳細ルール |
| 技術スタック | 特定ツール（MCP等）の操作手順 |
| コーディング規約 | 成果物フォーマットの詳細仕様 |
| Git 規約 | エンティティごとの CRUD ガイド |
判断基準はシンプルです: 「この情報を削除したら、Claude が間違いを起こすか?」。起こすなら CLAUDE.md に残す。起こさないなら rules/ に移す。
path スコープで条件付きルールを作る
rules ファイルには YAML フロントマターで paths を指定できます。
---
paths:
- "packages/mcp-db-server/**"
---
# MCP DB Server のルール
（このルールは packages/mcp-db-server/ 以下で作業しているときだけ適用される）
大きなモノレポでは、パッケージごとにルールを切り替えられるので便利です。
セキュリティルールは必ず書く
これは最も重要なセクションです。CLAUDE.md にセキュリティルールを書かないのは、ファイアウォールなしでサーバーを公開するようなものです。
masu-agent のセキュリティルールから抜粋します。
## セキュリティルール
### 絶対禁止事項
- `~/.ssh/` ディレクトリへのアクセス
- 環境変数からAPIキーを直接読み取り・表示
- `rm -rf` や大量削除コマンドの実行
- 外部サーバーへの機密データ送信
- `--dangerously-skip-permissions` フラグの使用
### 承認が必要な操作
- `npm install`（新パッケージ追加時）
- `git push`
- 外部APIへのPOSTリクエスト
- データベースのDELETE/DROP操作
特に --dangerously-skip-permissions の禁止は明示的に書いておくべきです。2026年初頭にオープンソースの AI エージェントフレームワークでセキュリティインシデント（CVE-2026-25253）が発生し、パーミッションバイパスの危険性が改めて認識されました。
実際に運用して気づいたこと: セキュリティルールは CLAUDE.md 本体と .claude/rules/security.md の両方に書くのがベストです。CLAUDE.md には要点だけ、rules にはチェックリスト付きの詳細版を置きます。これにより、Claude が常に最低限のセキュリティ意識を持ちつつ、詳細な判断が必要な場面では rules を参照できます。
MCP サーバー連携の設定例
Claude Code は MCP（Model Context Protocol）サーバーと連携して、外部ツールやデータベースにアクセスできます。設定は .mcp.json に記述します。
{
"mcpServers": {
"masu_db": {
"type": "stdio",
"command": "node",
"args": [
"packages/mcp-db-server/dist/index.js",
"masu-agent.db"
]
}
}
}
masu-agent では自作の MCP サーバーで SQLite データベースの CRUD 操作を Claude に公開しています。これにより、Claude が「タスクを作成して」「ナレッジを検索して」といった操作を自然言語で実行できます。
MCP サーバーの操作ガイドは .claude/rules/mcp-masu-db.md に約200行のドキュメントとして分離しています。ツールの一覧、追加手順、Zod スキーマの変換ルールまで網羅することで、「MCP に新しいエンティティを追加して」と指示するだけで Claude が正しい手順を踏んでくれます。
バイブコーディングの実践例でも触れていますが、こうした「Claude が自律的に正しい手順を踏める環境」を作ることが、生産性の大きな差になります。
CLAUDE.md 設計の5つの原則
実際に数ヶ月運用して見えてきた原則をまとめます。
原則1: What, Why, How で構成する
What: このプロジェクトは何か（概要・スタック）
Why: なぜこのルールがあるか（背景・判断基準）
How: 具体的にどうするか（コマンド・手順）
原則2: 50〜100行を死守する
CLAUDE.md が150行を超えると、コンテキストウィンドウを圧迫し始めます。詳細は rules/ に分離して、CLAUDE.md は「地図」の役割に徹します。
原則3: 「削除しても困らない行」は消す
各行について「これを消したら Claude が間違うか?」を自問します。答えが No なら消す。ドキュメントは短いほど強力です。
原則4: コマンド例を書く
## テスト
npm test # 全テスト実行
npm test -- --watch # ウォッチモード
npm run test:e2e # E2Eテスト
Claude は自然言語の説明よりも、具体的なコマンド例のほうが正確に理解します。
原則5: 定期的にメンテナンスする
CLAUDE.md は書いて終わりではありません。月に1回は見直して、古くなったルールの削除・新しいルールの追加を行います。僕は /init コマンドで生成した初期版をベースに、3ヶ月かけて現在の形に育てました。
やらないと損する最悪の未来
CLAUDE.md を書かない、あるいは雑に書いたまま放置すると、以下のような状況に陥ります。
- 毎回同じ指示を繰り返す: 「TypeScript で」「ESModules で」「テストも書いて」…セッションのたびに同じプロンプトを打つ。1日5回セッションを開くなら、週に25回の無駄な入力
- コードスタイルがバラバラ: あるファイルは CommonJS、別のファイルは ESModules。コメントは英語と日本語が混在。レビューで指摘する時間が積み重なる
- 危険な操作を止められない: セキュリティルールがないと、Claude が
rm -rfを実行したり、.envの中身をログに出力する可能性がある。本番環境で起きたら取り返しがつかない - 属人化が進む: チームメンバーが Claude Code を使っても、ルールが共有されていないので人によって出力品質が違う。結局「Claude 使えない」という評価になる
逆に言えば、CLAUDE.md を1時間かけてしっかり書くだけで、これらすべてが解決する。投資対効果として、これほど高いものはなかなかありません。
この記事を書いている理由
僕が CLAUDE.md の重要性に気づいたのは、正直かなり遅かったです。
Claude Code を使い始めた当初は、「毎回プロンプトで指示すればいいでしょ」と思っていました。でも AI エージェントシステムを24時間稼働させるようになって、状況が変わりました。自動実行されるセッションでは、人間がプロンプトを打つ機会がないんです。
Discord Bot 経由で Claude が起動し、タスクを処理し、結果を返す。そのすべてのステップで「どのディレクトリに保存するか」「どの言語でコミットメッセージを書くか」「どのコマンドは実行してはいけないか」を事前に定義しておく必要がありました。
CLAUDE.md と .claude/rules/ を整備してからは、夜中に自動実行されたタスクの結果を朝確認しても、期待通りの品質で仕上がっている。まるで優秀なチームメイトに引き継ぎ書を渡したような感覚です。
この体験を、同じように Claude Code を使っているエンジニアに共有したいと思って書きました。「なんか Claude の出力がイマイチ…」と感じている人は、コードを疑う前に CLAUDE.md を見直してみてください。驚くほど変わるはずです。
まとめ
CLAUDE.md の書き方を、実際のプロジェクト設定を公開しながら解説しました。
押さえるべきポイント:
- プロジェクト概要・スタック・規約をまず書く。Claude が「推測」する余地を減らす
- 50〜100行に収める。詳細は
.claude/rules/に分離 - セキュリティルールは絶対に書く。禁止操作と承認が必要な操作を明示
- MCP 連携のガイドは rules/ に分離して詳細に記述
- 月1回メンテナンスする。プロジェクトの成長に合わせて CLAUDE.md も育てる
Claude Code を使いこなすためのツール解説は、以下の記事もあわせてどうぞ。
