Claude Codeのrules管理 CLAUDE.mdとAGENTS.mdの使い分け

「Claudeに毎回同じ説明をしている気がする」「メンバーごとに出力のフォーマットがバラつく」 — この相談、本当に多いです。チームでClaude Codeを使い始めて1ヶ月くらいで必ず誰かが言い出します。

原因は、作業ルールの置き場所が決まっていないこと。Claude Codeは複数のファイルからルールを読み込む仕組みを持っていて、どこに何を書くかが定まると応答が一気に安定します。

この記事では、Claude Codeで作業ルールを管理する3つの仕組みと、使い分けを整理します。

3つのルール管理の仕組み

Claude Codeが起動時に読むルールファイルは、主に次の3種類です。

1. CLAUDE.md — プロジェクト全体の規約。リポジトリ直下に置く。Claude Codeが自動で読む 2. AGENTS.md — 「コードを書く前にこれを読め」レベルの注意事項。CLAUDE.mdから@AGENTS.mdで参照する形が多い 3. サブエージェント定義 (.claude/agents/{name}.md) — 特定タスク専用の小さなAI役割

順番に役割が違います。混ぜて使うと、それぞれの責務がぼやけて応答精度が落ちる。

How Claude remembers your project - Claude Code Docs

Give Claude persistent instructions with CLAUDE.md files, and let Claude accumulate learnings automa

docs.anthropic.com

CLAUDE.md に書くこと

CLAUDE.mdは「Claude Codeにとっての新人オリエンテーション資料」。プロジェクトに初めて触る人が知るべき情報を網羅します。

書くべき内容は次のとおり。

プロジェクトの目的と全体像(1〜3段落)
ディレクトリ構成(src/ には何が入る、tests/ には何が入る、等の表)
よく使うコマンド(npm run dev npm run build の正確な書き方)
命名規約(snake_case か camelCase か、コンポーネントは PascalCase 等)
コミットメッセージのスタイル(prefix を feat: fix: 等で揃える等)
触ってはいけないファイル(migrations/、自動生成ファイル等)

逆に書くべきでない内容もある。

「コードを書く前に必ず読む」レベルの注意事項 → AGENTS.mdへ
特定タスク専用のフォーマット指示(議事録の体裁等) → サブエージェントへ

長さは1,000〜3,000字程度が運用しやすい目安。短すぎると情報不足、長すぎるとセッション開始時のトークン消費が増えます。

私の運用では、/init でClaudeに初版を作らせて、1ヶ月かけて足りない部分を追記する流れに落ち着いています。

AGENTS.md に書くこと

AGENTS.mdは「コード変更を提案する前に必ず読むべき注意事項」。CLAUDE.mdの中から @AGENTS.md という記法で参照すると、関連ファイルとして自動で読み込まれます。

実例として media/AGENTS.md をそのまま引用する。

# This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code.

これだけ書いておくと、Claudeが Next.js 16 のコードを学習データ通りに書こうとして壊す事故が激減します。

AGENTS.mdに書くべきものは次のとおり。

学習データと現実がズレている技術スタック(Next.js 16 / React 19 のような破壊的変更)
特定のセキュリティ要件(個人情報・APIキーの取扱)
過去の事故からのルール(「migration中は本番DBを触らない」等)
参照すべき公式ドキュメントの場所(node_modules/.../docs/ 等)

「Why」と「How to apply」をセットで書くのがコツです。理由なしのルールは Claude が状況を見て無視することがある。

私のリポジトリでは、過去にClaudeが空ディレクトリを削除して開発環境が壊れた事故から「空ディレクトリでも .gitkeep がある場合は触らない」というルールをAGENTS.mdに追加しています。事故から学んだルールは AGENTS.md が居場所。

サブエージェント定義に書くこと

サブエージェントは「特定タスク専用のAIスタッフ」。.claude/agents/{name}.md というファイルに役割を書いておくと、/agents で呼び出して特定の仕事だけを任せられます。

書く内容のテンプレは下記。

---
name: meeting-minutes-formatter
description: 議事録の文字起こしを構造化する。録音された生テキストを、決定事項・アクション・宿題に分類する。
tools: Read, Write
---

# 役割

会議の録音から起こされた生テキストを、社内標準の議事録フォーマットに整形する。

# 入力
- recording/{date}.txt の生テキスト

# 出力
- minutes/{date}.md
- 構成: 日付/参加者/決定事項(箇条書き)/アクション(担当者と期日)/次回宿題

# 規約
- 「えー」「あの」などのフィラーを除去
- 個人名は社内Wikiの表記に揃える
- 数値は半角に統一

description の書き方が肝です。「いつ呼び出すべきか」を明確に書く。あいまいだと Claude が呼び分けに失敗します。

3つのうちサブエージェントだけが呼び出し時にだけ読み込まれる仕組みなので、各エージェントの定義は3,000〜10,000字書いても問題ありません。CLAUDE.mdより詳しく書ける。