Claude CodeのSubagent・Skills・CLAUDE.md、どこに何を書くべきか整理してみた

はじめに

Claude Code を触り始めると、Subagent、Skills、CLAUDE.md、Hooks などが出てきて、
どこに何を書くべきか少し迷います。

特に実務では、
「レビューの観点はどこに置くのか」「コーディング規約はどこにまとめるのか」
が曖昧になりやすいです。

この記事では、その違いを整理しつつ、実務で使いやすい分け方をまとめます。

まず結論

• CLAUDE.md は、プロジェクト全体で共有したい前提やルールを書く場所
• Subagent は、役割ごとに分担する専用エージェント
• Skills は、特定の作業をどう進めるかという手順や観点をまとめる場所
• Hooks は、必ず実行させたい処理を強制する仕組み

この分け方は、Claude Code の公式ドキュメントで説明されている各機能の役割とも整合しています。

Subagentとは何か

Subagent は、特定の役割に特化した専用エージェントです。

Claude が「この仕事はこの担当に向いている」と判断したときに、その Subagent に委譲されます。

たとえば、実務では次のような分け方が考えやすいです。

• review-agent
• test-agent
• implementation-agent

このとき重要なのは、Subagent は単なる「メモ」や「設定ファイル」ではないということです。

役割ごとに独立して仕事をさせるための仕組みです。

なお、公式ドキュメントでは、複数エージェントが並列で動いて相互連携するような本格的な構成が必要な場合は、Subagent ではなく Agent Teams を参照するよう案内されています。

つまり、Subagent は「役割分担」の理解で捉えるのがよいです。

Subagentはどう実行するのか

Subagent の実行方法は、大きく 2 つあると考えると分かりやすいです。

1つは Claude による自動委譲です。Subagent の description に合う依頼が来ると、Claude が自動的にその Subagent に仕事を振ることがあります。

もう1つは、明示的に使う方法です。

たとえば「review-agent を使ってこの変更をレビューして」といった自然文で依頼できます。

Skillsとは何か

Skills は、Claude に追加する再利用可能な作業知識です。

SKILL.md を作ると Claude の toolkit に追加され、Claude が関連する場面で自動的に使ったり、/skill-name で明示的に呼び出したりできます。

ここで大事なのは、Skills は「注意書き」だけではないということです。

むしろ、実務で使う「手順書」や「チェックリスト」に近いです。

たとえば次のようなものは Skills に向いています。

• React コンポーネント実装時の確認項目
• レビュー時に見る観点
• テスト追加時の進め方
• デプロイ前の確認手順

つまり Skills は、「この作業ではこう進める」という実践知をまとめる場所です。

CLAUDE.mdとの使い分け

CLAUDE.md は、Claude Code がそのプロジェクトで最初から知っておくべき共通前提を書く場所です。

ここに書くべき内容は、たとえば次のようなものです。

• プロジェクト概要
• ドメイン知識
• 命名規約
• コーディング規約
• アーキテクチャ方針
• ディレクトリごとの責務
• 禁止事項

要するに、CLAUDE.md は「このプロジェクトでは何を前提に実装するのか」を共有するための土台です。

作業単位ではなく、プロジェクト全体に効くルールを書く場所だと考えると整理しやすいです。

作業単位のものは Skills にまとめましょう。

レビューの注意点はSubagentか、Skillsか

これはかなり迷いやすいですが、結論としては「両方に分けて書く」のがよいと思います。

ただし、同じ内容を二重で書くのではなく、役割で分けます。

Subagent 側には「その担当者としてどう振る舞うか」を書きます。

たとえば、review-agent なら「設計と責務分離を重視する」「重大な問題から先に指摘する」といった方針です。

Subagent は独自のコンテキストとシステムプロンプトを持つので、このレベルの役割定義は agent 側に置くのが自然です。

一方で、レビュー観点の詳細は Skills に置く方が向いています。

たとえば「コンポーネントの粒度」「責務の分離」「props の肥大化」「hooks の副作用」「依存方向」「テスト容易性」などです。

これらは review-agent 以外でも再利用できる可能性があるため、
Skill として切り出す方が保守しやすくなります。

実務では、次のように分けると運用しやすいです。

review-agent

• 設計と責務分離を重視する
• 指摘は重要度順に返す
• review-frontend skill を使う

review-frontend skill

• コンポーネントは責務過多ではないか
• hooks は薄く保たれているか
• props が肥大化していないか
• テストしやすい構造か

この構成なら、agent は役割、skill は作業手順という分離がきれいにできます。

コーディング規約はSkillsか、CLAUDE.mdか

これは基本的に CLAUDE.md です。

コーディング規約は、特定の担当だけではなく、実装担当にもレビュー担当にもテスト担当にも共通して効いてほしいものです。

そのため、プロジェクト全体の共通ルールとして CLAUDE.md に置くのが自然です。

Claude Code の settings ドキュメントでも、CLAUDE.md は user / project scope で使える共通の指示ファイルとして扱われています。

たとえば次のようなものは CLAUDE.md に向いています。

• hooks は薄く保つ
• データ取得は service 層に寄せる
• 命名は業務用語ベースにする
• UI とロジックを分離する
• 直接 DB を叩く実装は禁止する

一方で、Skills に書くのは「その規約を実際の作業でどう使うか」です。

たとえば「新規コンポーネントを作るときは props の責務を確認する」「Server Component で済むか最初に判定する」のような作業手順です。

つまり、規約の本体は CLAUDE.md、具体的な適用方法は Skills という切り分けが分かりやすいです。

Hooksはどう使い分けるのか

Hooks は、「絶対に実行させたい処理」があるときに使います。

たとえば、次のようなものは Hooks 向きです。

• 保存や編集後に lint を必ず走らせる
• format を強制する
• 危険なコマンドを禁止する
• 特定の検査を毎回実行する

逆に、「この責務分離は妥当か」「設計としてこちらが良いか」といった判断を伴うものは Hooks より Skills や Subagent の方が向いています。

Hooks は“必ずやること”を機械的に実行する仕組みとして考えると分かりやすいです。

実務ではどう構成するのがよいか

Web アプリ開発なら、まずは次のような構成から始めるのが扱いやすいと思います。

CLAUDE.md

ここにはプロジェクト共通の前提を書きます。

• プロダクト概要
• 命名規約
• アーキテクチャ方針
• hooks / services / components の責務分離
• テスト方針
• 禁止事項

Subagents

役割ごとに分けます。

• implementation-agent
• review-agent
• test-agent

Skills

作業単位の手順やチェックリストを切り出します。

• implement-react-component
• review-frontend
• write-tests
• refactor-component

Hooks

必ず実行したい最低限の自動処理だけ入れます。

• lint
• format
• 危険操作のブロック

この構成にしておくと、CLAUDE.md で共通前提をそろえ、Subagent で役割を分け、Skills で作業手順を標準化し、Hooks で品質を下支えする、という形に整理できます。

迷ったときの判断基準

最後に、迷ったときの基準を一つにまとめます。

その内容が「プロジェクト全体の前提」なら CLAUDE.md。
「担当者としての振る舞い」なら Subagent。
「特定作業の進め方」なら Skills。
「必ず強制したい処理」なら Hooks。

この基準で考えると、かなり整理しやすくなります。

まとめ

Claude Code を実務で使うときは、すべてを一箇所に詰め込まない方が運用しやすいです。

CLAUDE.md に共通ルールを置き、Subagent で役割を分け、Skills で各作業の進め方を標準化し、Hooks で最低限の品質を強制する。

この分担にしておくと、プロジェクトが大きくなっても破綻しにくくなります。