🧩

CLAUDE.md・Rules・Skills・SubAgents・AgentTeams——5つの引き出し、どれをいつ開けるか

に公開
AI
Claude
Claude Code
Subagents
Agent teams
tech

CLAUDE.mdが200行を超えたあたりから、書いたはずのルールをClaudeが無視し始めた。

「フロント触ってるのにAPIのルール読んでる」「レビュー指摘で会話が埋まって、次の指示が通らない」。全部、コンテキストの置き場を間違えてた。

Claude Codeには「コンテキストの置き場」が5つある。CLAUDE.md、Rules、Skills、SubAgents、AgentTeams。全部いきなり使う必要はないけど、どれをいつ開けるか知ってるだけで動きが変わる。

先に結論。「こういうとき、どれを使う？」の逆引き表。

こういうとき 使う引き出し なぜ効く
「strictって言ったのにまたany使ってる」 CLAUDE.md 毎セッション自動で読み込まれる
フロント触ってるのにAPIのルールまで読んでる Rules フォルダごとにルールを分離できる
「レビューして。観点は…」を毎回打ってる Skills /名前 で手順書を一発展開
レビュー指摘が長すぎて、次の実装指示が通らない SubAgents 独立コンテキストで動いて要約だけ返す
APIとフロントで型がズレてるのに誰も気づかない AgentTeams レビュアー同士が質問を投げ合える

サンプルプロジェクト（Next.js + Express API）で5つを実際に試しながら、それぞれの使いどころを見ていく。

まずは土台——CLAUDE.md と Skills

最初に使うのはこの2つ。

CLAUDE.md はセッション開始時に自動で読み込まれて、compaction（自動圧縮）後も再読み込みされる。つまり、ここに書いたルールは消えない。技術スタックやコーディング規約、ビルドコマンドを置く場所。

Skills は /スキル名 で呼び出すと本文が読み込まれる手順書。普段はdescription（1,536文字まで）だけがコンテキストに載っていて、呼ばれたときだけ本文が展開される。レビュー手順やテスト手順みたいな「毎回は要らないけど、呼んだら正確にやってほしい」ものを置く。

今回のサンプルプロジェクトはこんな構成。

task-api-sample/
├── client/          # Next.js（App Router + Tailwind）
│   └── src/
│       ├── app/
│       ├── components/
│       └── lib/     # API呼び出し
├── server/          # Express API（TypeScript）
│   └── src/
│       ├── routes/  # 認証 + タスクCRUD
│       ├── middleware/  # JWT認証
│       └── models/  # SQLite（sql.js）
├── CLAUDE.md        # プロジェクトルール
└── .claude/
    ├── rules/
    │   ├── server.md       # API開発ルール
    │   └── client.md       # フロント開発ルール
    ├── skills/
    │   └── review.md       # レビュー手順
    └── agents/
        ├── api-reviewer.md       # APIレビュアー
        └── frontend-reviewer.md  # フロントレビュアー

フロントエンドとAPIでルールが違う。この「違い」が、引き出しを増やす動機になる。

CLAUDE.mdはこれだけ。

# CLAUDE.md

## プロジェクト概要
タスク管理アプリ（Express API + Next.js フロント）

## 技術スタック
- server/: Express + TypeScript + sql.js (SQLite) + zod + JWT認証
- client/: Next.js (App Router) + TypeScript + Tailwind CSS

## コーディング規約
- TypeScriptのstrictモードを使う
- APIレスポンスにはzodバリデーションを通す
- エラーメッセージは日本語で返す
- コンポーネントは1ファイル1コンポーネント
- API呼び出しは `client/src/lib/api.ts` に集約する

## ビルド・実行
- `npm run dev` でサーバー（:3001）とクライアント（:3000）を同時起動

20行くらい。小さいプロジェクトならこれで十分回る。

ただ、ここにフロントエンドのルールもAPIのルールもレビュー手順も全部書き始めると、あっという間に200行を超える。自分のプロジェクトでも経験があるけど、長くなるほど精度が落ちて、聞いてないフリが増える。

残り4つの引き出しの出番。

5つの引き出し、もう少し詳しく

CLAUDE.mdとSkillsは前のセクションで触れたので、残り3つを掘り下げる。

Rules（.claude/rules/）

CLAUDE.mdの分割版。frontmatterに paths を書くと、そのパスにマッチするファイルをClaude Codeが触ったときだけ自動で読み込まれる。たとえば server/** と書けば、server/ 配下を編集してるときだけそのルールが有効になる。

---
paths:
  - "server/**"
---

フロントエンドを触ってるときにAPIのルールが読み込まれても邪魔なだけ。地味だけど、これだけでClaudeの精度が変わる。

SubAgents（.claude/agents/）

独立したコンテキストウィンドウで動く。親がタスクを投げて、結果の要約だけ受け取る。Fork-Join（分岐して合流）パターン。

親の会話履歴は引き継がない。CLAUDE.mdやRulesは読み込まれるけど、メインの会話は持ち込まない。だから、コンテキストを汚さずに専門タスクを回せる。レビュー結果が5,000トークンあっても、親に返るのは要約だけ。これがかなり助かる。

AgentTeams

複数のClaude Codeインスタンスが、共有タスクリストとメールボックスで協調する。Peer-to-Peer（対等な参加者同士が直接やりとりする）パターン。各メンバーが独立インスタンスなので、トークン消費は一番大きい。

SubAgentsが「投げて待つ」なら、AgentTeamsは「議論させる」。視点の違うレビュアーに同時にレビューさせて、お互いの指摘を見て追加の意見を出す、みたいなことができる。

ここで大事なのが1つ。 .claude/agents/ の定義ファイルは、SubAgentにもAgentTeamsにも使える共通の部品 。同じ定義を委譲にも協調にも使い回せる。

Anthropic公式ブログでも「SubAgentを使うべき場面 = メイン会話をノイズで埋めてしまうサイドタスク」と整理されてる。ログ解析、大量ファイル探索、テスト実行。結果だけ受け取りたい場面。

サンプルプロジェクトで試す

実際に定義を作って動かしてみる。

エージェント定義を作る

.claude/agents/ にレビュアーを2つ定義した。フロントエンド担当とAPI担当。

SubAgent定義ファイル
.claude/agents/ にレビュアー定義を配置

.claude/agents/api-reviewer.md
---
name: api-reviewer
description: "API・バックエンド専門のコードレビュー。セキュリティ・データ整合性・
  エラーハンドリング・API設計の観点でserver/配下をレビューする"
tools:
  - Read
  - Glob
  - Grep
  - Bash
model: sonnet
---

あなたはAPI・バックエンド専門のレビュアーです。

## 観点

- **セキュリティ**: 認証バイパス、SQLインジェクション、機密情報の露出、入力バリデーション
- **データ整合性**: トランザクション、競合状態、外部キー制約
- **エラーハンドリング**: 想定外入力への対応、適切なHTTPステータスコード
- **API設計**: RESTful規約、レスポンス形式の一貫性

## レビュー対象

`server/` ディレクトリ配下の `.ts` ファイルを対象にレビューしてください。

## 出力形式

ファイルごとに問題点を列挙してください:
- ファイル名と行番号
- 問題の説明（1文）
- 重要度: 🔴 致命的 / 🟡 改善推奨 / 🔵 提案

フロントエンド版も同じ構造で、観点がUX・アクセシビリティ・型安全に変わるだけ。

ポイントは tools と model の指定。レビューなら読む系のツール（Read, Glob, Grep）とBashがあれば十分。modelもSonnetを指定してコストを抑えてる。tools未指定だと意図しないツールまで使えてしまうので、必ず最小権限で明示する。

description は「何をするか・いつ使うか・何を出力するか」を1文に収めるのがコツ。Claudeがこの定義を使うかどうかを判断する材料になる。

委譲で使う（SubAgent）

「api-reviewer と frontend-reviewer のSubAgentを使って、このプロジェクトをレビューして」。これだけ。

SubAgent実行中
2つのエージェントが並列で走ってる

Claudeが .claude/agents/ の定義を読み取り、APIレビューとフロントレビューを並列で起動した。各エージェントが独立コンテキストでファイルを読み、レビュー結果を親に返す。

SubAgent結果
レビュー結果のサマリが親に返ってきた

返ってきた結果:

API側

  • 🔴 critical 5件 — JWT_SECRET ハードコード、パスワード平文保存・比較
  • 🟠 high 8件 — JWTアルゴリズム未指定、CORS固定、try-catch欠如
  • 🟡 medium 7件 — PRAGMA foreign_keys未設定、Number(req.params.id)の検証不足

フロント側

  • 🔴 致命的 2件 — JWTをlocalStorageに保存（XSS耐性なし）、認証情報ハードコード
  • 🟡 改善推奨 10件 — ローディング/エラーハンドリング欠落、<label> 未使用
  • 🔵 提案 4件 — priority型の精度、SWR/React Query導入

各自がそれぞれの領域を独立にレビューして、結果のサマリだけが返ってきた。会話が指摘で埋まらない。これがFork-Joinパターンの良さ。

ただ、1つ気になることがある。APIレビュアーは「パスワード平文」を指摘して、フロントレビュアーは「localStorage JWT」を指摘してる。両方とも正しい。でも 「APIのレスポンス形式とフロントの型定義がズレてる」という境界の問題は、どちらも触れてない 。各自が自分の領域だけ見てるから、境界で起きる問題は視界に入らない。

協調で使う（AgentTeams）

同じ定義をAgentTeamsのTeammateとして呼んでみた。今度はプロンプトを変える。

api-reviewer と frontend-reviewer をチームメイトとして、
このプロジェクトのコードレビューを協調で進めて。
フロントとAPIの境界（型定義の整合性、レスポンス形式）
についてお互いの意見を交換させて

AgentTeamsタスクリスト
両レビュアーが並列起動し、お互いに質問を投げ合う

SubAgentと決定的に違ったのは、レビュー完了後の動き。各レビュアーが「相手への質問・確認事項」を持っていて、お互いに送り合った。

api-reviewerからfrontend-reviewerへの質問（抜粋）:

Task.description の null 安全性 — サーバーからNULLが返った場合にUIでどう対処してる？
priority の型 — string になってるけど、サーバーは z.enum(["low", "medium", "high"]) で制約してる。リテラルユニオン型に絞らない？
JWT有効期限切れ時 — 401を受け取ってもトークンクリアもリダイレクトもしない。自動ログアウトは？

frontend-reviewerからapi-reviewerへの質問（抜粋）:

details フィールドの形式 — zodの flatten() 結果を返すエンドポイントと返さないエンドポイントがある。統一する方針は？
GET /tasks が SELECT * で全カラム返してるけど、レスポンス型の保証はある？
DELETE が 204 を返すことはAPI仕様として明示されてる？

協調レビュー結果
合意事項がテーブルで整理された

最終的に、両者が合意した Critical 事項がテーブルで出てきた:

指摘 該当箇所 両者の見解
パスワード平文保存 auth.ts:40 api_rev: 最優先修正。fe_rev: マイグレーション方針を事前合意
priority型の不整合 api.ts:74 vs tasks.ts:12 両者完全合意 。リテラル型へ即時修正
401時の自動ログアウト欠如 api.ts:32-34 両者合意。request<T>で401検知→clearToken()→ログイン画面遷移
detailsフィールドの非対称 auth.ts:22 vs tasks.ts:59 全エンドポイントで統一

さらに「変更しない」事項も合意された。401/403/404の使い分けは現状維持——api-reviewerが「RFC 9110に沿った設計だから現状でいい」と説明して、frontend-reviewerも納得。

長期課題と推奨アクション
型共有の方式まで議論が発展した

最後に「型共有の仕組み」が長期課題として挙がった。server の zod スキーマと client の Task/User インターフェースが独立定義されているのが境界問題の根本原因で、モノレポ化か OpenAPI 自動生成か tRPC 検討を次スプリントの議題にする、と。ここまで踏み込んだ提案が出てきた。

委譲と協調、何が違ったか

同じプロジェクト、同じ定義ファイル。使い方を変えただけで、出てくるものがまるで違った。

SubAgent（委譲） AgentTeams（協調）
レビュー範囲 各自の領域のみ 各自の領域 + 境界
指摘の質 個別に正確 境界問題を発見
合意形成 なし（各自が独立に報告） あり（Q&Aで合意・反論）
出力形式 サマリのみ 合意事項テーブル + 長期課題

一番の違いは「合意」が生まれるかどうか。priority型の不整合は両者が同時に指摘して即合意。401/403の使い分けでは片方が根拠を示して、もう片方が納得した。1人のレビュアーに全部見せても、こういう「反論→納得」のプロセスは起きない。

この実験結果はAnthropic社内のデータとも一致してる。社内でも複数エージェントによるPRレビューシステムを構築して、実質的なレビューコメントがつくPRの割合が16%から54%に改善した事例がある。Correctness・Security・Performance・Styleの4専門エージェントが互いの指摘を踏まえて追加レビューする構成。

裏を返すとトークンコストは大きい。シンプルなタスクにAgentTeamsを投入しても、議論が起きずにコストだけ増える。まずSubAgentから試して、境界をまたぐ複雑さが出てきたらAgentTeams。それが現実的な判断になる。

段階移行マップ

自分のプロジェクトがどのステージにいるかで、次に手を出す引き出しが変わる。

全部のステージを順に上がる必要はない。ほとんどのプロジェクトはStage 2で十分回る。

Stage 0 → 1: CLAUDE.mdが200行に近づいたら

CLAUDE.mdにフロントとAPIのルールが混在し始めたら、Rulesに分離するタイミング。パススコープをつければ server/ を触ってるときにフロントのルールが読み込まれなくなる。

.claude/rules/server.md
---
paths:
  - "server/**"
---

# API開発ルール
- ルートハンドラは必ず async にする
- リクエストボディは zod でバリデーションしてからアクセスする
- 認証が必要なルートには authenticate ミドルウェアを適用
.claude/rules/client.md
---
paths:
  - "client/**"
---

# フロントエンド開発ルール
- コンポーネントは関数コンポーネント + hooks
- API呼び出しは src/lib/api.ts を経由する
- エラーハンドリング: API呼び出しは try-catch で囲む

CLAUDE.mdからルール部分が消えて、ルール本体はRulesへ。CLAUDE.mdにはプロジェクト概要とビルドコマンドだけが残る。

Stage 1 → 2: 同じ手順を何回もコピペしてたら

「レビューして。観点はセキュリティ、パフォーマンス、保守性の3つで」。これを毎回チャットで打ってたら、Skillsに切り出すサイン。

.claude/skills/review.md
---
description: "コードレビューを実行する。セキュリティ・パフォーマンス・保守性の3観点でチェック"
---

# コードレビュー

## 手順

1. 対象ファイルを特定（指定がなければ git diff の変更ファイル）
2. 各ファイルを読んで以下の観点でレビュー
   - **セキュリティ**: SQLインジェクション、認証バイパス、機密情報
   - **パフォーマンス**: N+1クエリ、不要な再レンダリング
   - **保守性**: 型安全性、エラーハンドリング、責務の分離
3. 問題がある場合: ファイル名・行番号・問題の説明・修正案

/review で呼び出すだけ。descriptionだけが常時ロードされるから、コンテキストもほとんど食わない。

Stage 2 → 3: メインのコンテキストが汚れて精度が落ちたら

レビュー結果が長くて、メインの会話がレビュー指摘で埋まる。そこに追加の実装タスクを投げると、レビュー指摘と実装指示が混ざって精度が下がる。

SubAgentsに切り出せば、レビューは独立コンテキストで走る。メインに返るのは要約だけ。コンテキストがきれいなまま次のタスクに移れる。

Stage 3 → 4: 境界の問題が見えないとき

SubAgentsで出てこなかった「APIとフロントの型不整合」が、AgentTeamsでは質問の応酬から自然に浮かび上がった。上の実験でやった通り。

全部は要らない。でも中身は知っておく

自分のプロジェクトではCLAUDE.md + Skills で回してる。200行超えたときにRulesに分離して、レビュー手順をSkillsに切り出したら、それだけで十分に安定した。

今回SubAgentsとAgentTeamsを試してみて、「使い方が変わる境界線」が見えた。独立して回せるタスクならSubAgent。視点を交差させたいならAgentTeams。どちらも .claude/agents/ に定義を置くだけで動く。

5つ全部使う必要はないけど、何がどこにあるか知っていると、場面に合わせて自然に手が伸びる。「どこに何を置くか」を迷わなくなった分、Claudeに渡すコンテキストの質が上がった気がする。

Discussion