CLAUDE.mdに書くか、スラッシュコマンドにするか。Claude Codeの使い分けメモ
Claude Codeを使っていると、「毎回同じ指示を書いている」場面が出てきます。この指示を CLAUDE.md に書くのか、スラッシュコマンドにするのか。私は、繰り返す手順はスラッシュコマンドに寄せています。
この記事では、その使い分けの考え方と、実際に使っている /design-review-loop と /orchestra の設計、そして CLAUDE.md と AGENT.md の関係をまとめます。
2026年10月16日 追記: 公開後に変わった点
サブエージェントの入れ子: 本文では「サブエージェントが別のサブエージェントを起動することはできない」と書きましたが、現在の公式ドキュメントでは、標準でサブエージェントが自分のサブエージェントを起動でき、メインの会話から3階層下までとされています。出典: Claude Code Docs「Subagents」 https://code.claude.com/docs/en/sub-agents
AGENTS.md の読み込み: 本文で「(最新の挙動は要確認)」としていた点は、現在の公式ドキュメントで「AGENTS.md を直接読むには Claude Code v2.1.277 以降が必要」と明記されています。読めないセッションもあるため、CLAUDE.md から @ で取り込む方法も引き続き案内されています。出典: Claude Code Docs「How Claude remembers your project」 https://code.claude.com/docs/en/memory
本文はそれぞれ公開時点(2026年10月6日)の内容です。確認日: 2026年10月16日。最新は公式ドキュメントで確認してください。
この記事が関係する人・関係しない人
関係する人
Claude Codeを使っていて、CLAUDE.md に何を書くか、スラッシュコマンド(スキル)に何を切り出すかを決めたい人
毎回同じ指示や手順をプロンプトに書いている人
長い作業をサブエージェントに分けて、メインの会話の文脈を保ちたい人
AGENTS.md など、ほかのツールと共通の指示ファイルを Claude Code でも使いたい人
関係しない人
Claude Code を使っていない人(この記事は Claude Code の CLAUDE.md・スラッシュコマンド・サブエージェントの話です)
自分が当てはまるかの確認方法
今の CLAUDE.md が読み込まれているかは、セッション中に /context を実行し、Memory files の一覧で確認できます
使っている Claude Code のバージョンは、次のコマンドで確認できます(AGENTS.md の読み込みはバージョンによって挙動が違うため)
claude -vCLAUDE.md・スラッシュコマンド・サブエージェントの違い
Claude Codeの公式ドキュメントでは、拡張の仕組みを次のように整理しています。
CLAUDE.md: セッションごとに常に読み込まれる、永続的なプロジェクトの前提。/init で雛形を作り、/memory で編集できます。
スラッシュコマンド / スキル: 繰り返す手順やワークフローをMarkdownファイルにしたもの。.claude/commands/(プロジェクト用)や ~/.claude/commands/(個人用)に置き、必要なときに呼び出します。
サブエージェント: 独立したコンテキストウィンドウで作業し、結果の要約だけを返す仕組み。
(出典: Claude Code公式ドキュメント「Extend Claude Code」「Create custom subagents」。仕様は更新されるので、最新の内容は公式で確認してください)
私の使い分け
常に守らせたい前提は CLAUDE.md、繰り返す手順はスラッシュコマンドに入れています。
理由は、コンテキストの使われ方の違いです。公式ドキュメントによると、CLAUDE.md はセッション開始時に読み込まれ、その後のすべてのリクエストに残り続けます。手順が長いものまで CLAUDE.md に入れると、毎回それを抱えたまま作業することになります。呼び出したときだけ読み込まれるスラッシュコマンドにしておけば、必要なときだけ使えます。
If an entry is a multi-step procedure or only matters for one part of the codebase, move it to a skill or a path-scoped rule instead.
訳: 項目が複数ステップの手順であったり、コードベースの一部にしか関係しなかったりする場合は、スキルかパス指定のルールに移してください。(How Claude remembers your project)
/design-review-loop: サイト全体のUI/UXを評価・改善するループ
プロジェクトで使っているデザインレビューのコマンドです。説明文は「サイト全体のUI/UXをオーケストラ方式で評価・改善するループ」で、SKILL.md として置いています。
使い方
引数には、対象ページのパスやブランチ名を渡せます。指定しなければ、app/ 配下の全ページが対象になり、作業ブランチは ux-loop-full になります。変更範囲に制限は付けておらず(コンポーネント、レイアウト、共通スタイル、文言、ページ個別のコードすべてが対象)、作業は専用ブランチの上で行います。前提は、dev サーバーを npm run dev で起動できることと、Playwright MCP が接続済みであることです。
指揮官とサブエージェント
このコマンドでは、メインのClaudeを「指揮官」にします。決めているルールは次のとおりです。
指揮官は、実装・編集・分析などの実作業をしない。必ず Task tool でサブエージェントを起動して委譲する
各フェーズは独立した1つのサブエージェント呼び出しにする。前フェーズの文脈をそのまま渡さず、そのフェーズに必要な情報だけをプロンプトにして渡す
指揮官の仕事は、結果を受け取って、次に進むか、差し戻すか、ループを終えるかを判断すること
フェーズの開始時に、フェーズ名・担当の役割・入力・期待する出力形式を明示してから起動する
サブエージェントは独立したコンテキストウィンドウを持ち、結果だけを返します(公式ドキュメントの説明)。長いループでも、指揮官の文脈が膨らみにくい構成です。
フェーズ構成
フェーズ0 準備: 作業用ブランチを切り、app/ 配下の全 page.tsx を走査してページ一覧を作る
フェーズ1 トーン定義: 既存ページのスクリーンショットと文言を見て、サイトが目指すトーンを3〜5行で定義する
フェーズ2 デザインリサーチ: 近い業種・トーンの実在サイトを5〜8件調べ、配色、タイポグラフィ、余白のリズム、マイクロインタラクションなどを、コピーではなく原則やパターンのレベルで言語化する
フェーズ3 ページ別ループ: 1ページあたり最大4ラウンド。観測、レビュー、実装を繰り返す
フェーズ4 最終報告: 全ページ・全ラウンドの指摘と対応をまとめ、ページ間の一貫性とデザインシステム化すべき点を一覧にする
ページ別ループの中身(Generator-Evaluator)
中心はフェーズ3です。実装する側(Generator)と評価する側(Evaluator)を、別のサブエージェントに分けています。
観測担当: Playwright MCP でスクリーンショットとスナップショットを取り、axe-core を注入・実行してアクセシビリティ違反を取得する
レビュー担当(第三者として評価): フェーズ1・2の結果と観測結果を入力に、PASS/FAIL と具体的な改善指示を出す。UX軸は Jobs-to-be-done、Nielsen の10ヒューリスティック、axe-core の違反。UI/デザイン軸は、ビジュアルの一貫性、タイポグラフィの階層、文言のトーン、絵文字・アイコンの使い方、余白と情報密度、リサーチ結果と比べた物足りなさ。改善指示には、配色コードの例、余白の数値、文言の修正案を含める
実装担当(FAILのときだけ): 改善指示を実装に反映する
実装担当の結果を受けて、指揮官が観測に戻るか、そのページのループを終えるかを判断します。レビューの指示に「配色コード例」「余白数値例」を含めているのは、実装担当がそのまま手を動かせる粒度にするためです。
/orchestra: 汎用のオーケストレーター
/orchestra は、特定の作業に決め打ちしない汎用のオーケストレーターです。考え方は、公式ドキュメントのサブエージェントの仕組みがベースです。
各サブエージェントは、専用のシステムプロンプト、ツールの権限、独立したコンテキストウィンドウを持つ
親は、タスクの内容をまとめた依頼メッセージをサブエージェントに渡し、サブエージェントは独立して作業して結果を返す
サブエージェントが別のサブエージェントを起動することはできない(入れ子にならない)
Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions.
訳: 各サブエージェントは、独自のシステムプロンプト、特定のツールへのアクセス、独立した権限を持ち、それぞれのコンテキストウィンドウで動きます。(Create custom subagents)
/design-review-loop も同じ構造で、司令塔はメインのセッション側にあり、実作業をするサブエージェントは1段だけです。公式の仕組みの上に載せているので、特殊な設定は要りません。
CLAUDE.md と AGENT.md の使い分け
CLAUDE.md は Claude Code が読む指示ファイルで、その中に書いた内容が毎セッション読み込まれます。一方で、AGENT.md は、特定のツールに依存しない、エージェント開発用の共通ファイルとして私が整理しているものです(設計メモとして AGENT-DESIGN-NOTES.md も用意しています)。
使い分けは次のように考えています。
ツールを問わず共通にしたいルール: AGENT.md 側に書く
Claude Code 専用の指示: CLAUDE.md に書く
この2つをつなぐ方法として、公式ドキュメントでは、CLAUDE.md の中から共通ファイルを @ で取り込む書き方が紹介されています。AGENTS.md(複数のツールが対応している共通の指示ファイル)の場合は、次のように書きます。
@AGENTS.md
## Claude Code
(Claude Code 専用の指示をここに書く)CLAUDE.md files can import additional files using @path/to/import syntax.
訳: CLAUDE.md ファイルは、@path/to/import の構文で別のファイルを取り込めます。(How Claude remembers your project)
Claude Code は、セッション開始時に取り込んだファイルを読み込み、その下に書いた指示を追加で読みます。共通のルールを1か所に置いたまま、Claude Code 専用の指示だけを足せるのがポイントです。AGENT.md を同じ形で取り込む場合も、考え方は同じです。
なお、Claude Code が AGENTS.md を直接読むかどうかは、バージョンによって挙動が変わってきているようです。確実に読ませたいときは、公式ドキュメントが案内している @ での取り込みを使うのが安全です(最新の挙動は要確認)。
もう1つ、整理中のことがあります。Next.js 用に自動生成される nextjs-agent-rules のブロックが CLAUDE.md に入るため、それとプロジェクト固有のルールをどう同居させるかです。自動生成の部分とは書き分けておくのが前提ですが、運用はまだ試行錯誤しています。
まとめ
常に前提にしたい内容は CLAUDE.md、繰り返す手順はスラッシュコマンドにする
長い手順やレビューのような作業は、指揮官とサブエージェントに分けると、メインの文脈を保ちやすい
ツール共通のルールは別ファイルに置き、CLAUDE.md から @ で取り込む
関連記事
出典(2026年10月16日に確認):
Claude Code Docs「Extend Claude Code」 https://code.claude.com/docs/en/features-overview
Claude Code Docs「How Claude remembers your project」 https://code.claude.com/docs/en/memory
Claude Code Docs「Create custom subagents」 https://code.claude.com/docs/en/sub-agents
仕様は更新されるので、最新の内容は公式ドキュメントで確認してください。
開発ツールの仕様変更・提供終了の情報を毎朝お届けしています。見逃したくない方は、フォローしてください。
