Claude Codeを育てる - Part 4：拡張編

CLAUDE.md（説得）と settings.json（強制）だけだと、いずれ限界が来る。

• 同じ長文プロンプトを何度も書いている
• ロールが1つだと別の視点でレビューさせられない
• CLAUDE.mdが200行を超えて分離が必要

ここで使うのが Skills と Subagents。

■ Skills とは

呼び出されると Claude がその指示通りに動き始める、再利用可能なタスク定義。 単に読まれるドキュメントではなく、発火すると Claude がその場でその作業を開始する「実行トリガー付きの指示セット」。

.claude/skills/code-review/SKILL.md

構成は frontmatter + 本文。

※ frontmatter とは、Markdown ファイルの冒頭に --- で囲んで書く YAML メタデータブロックのこと。Skill の場合、ここに name / description などの設定を書く。本文（手順書の中身）はその下に普通の Markdown で書く。

---
name: code-review
description: コードレビュー時に責務分離・KISS/SOLID・セキュリティ・
  エラーハンドリング・テスト容易性の観点で厳しめに評価する。
  /code-review で明示呼び出し、または「レビューして」「review this」
  と言われた時に発動。
---

# Code Review

## 対象範囲
- 引数なしで呼ばれた場合：直近の git diff（未コミット差分 + 最新コミット）
- /code-review <path> でパス指定可能
- 対象が曖昧な場合は実行前にユーザーに確認

## 観点
- 責務分離
- KISS / SOLID
- セキュリティ（入力検証、認可、シークレット）
- エラーハンドリング
- テスト容易性

## 出力フォーマット
- ID / Severity / Category / Problem / Required Action / Verification

■ Skills の発火メカニズム

発火タイミングは2つ：

• 自動発火 — 毎ターン Claude がユーザー入力と各 Skill の description を照合し、マッチしたら発火
• 手動発火 — ユーザーが /skill-name で明示的に呼び出す

セッション開始時に全 Skill の description だけが Claude のコンテキストに事前ロードされており、Claude はそれを毎ターン参照して判定する。だから description の精度が自動発火の確率を直接決める。

■ description フィールドが命

ここが Skill 設計で一番重要。

👉 description が曖昧だと自動発動されにくくなる

Claude は description を見て「今このタスクでこの Skill を使うべきか」を判断する。曖昧だと判断材料が無く、関連クエリで呼ばれない。

ダメ：

description: 厳しめコードレビュー

→ Claudeから見ると「いつこのスキルを使うべきか」が分からない。

OK：

description: コードレビュー時に責務分離・KISS/SOLID・セキュリティの観点で
  厳しめに評価する。/code-review で明示呼び出し、または
  「レビューして」「review this」と言われた時に発動。

書くべきこと：

• 何をするか
• どんな観点で
• いつ発動すべきか（明示呼び出しのコマンド名 + 自然言語のトリガー）

なお、frontmatter の name と description は厳密には必須ではない（name はディレクトリ名、description は本文1段落目がデフォルトになる）。ただし「いつ呼ばれるか」を制御したいなら明示的に書くのが現実解。

■ Skill 化するタイミング

結論から言うと、

👉 Skill は前倒しで作らない

最初から「これは Skill 化しておこう」とやると、使われない Skill が溜まっていく。

タイミング：

同じ長文プロンプトを3回書いたら Skill 化

例：

• レビュー観点を毎回書いている → /code-review
• 既存システムの調査手順を毎回書いている → /investigate
• マイグレーション計画書のフォーマットを毎回書いている → /migration-plan

3回未満なら、CLAUDE.md か直接プロンプトで足りる。

■ Subagents とは

※ このパートでは概念と使い分けだけ扱う。Subagent の具体的な書き方・実装例は Part 5（Subagent 実装編） で詳述する。

別のロール・別の文脈で動かしたいときに使う。

.claude/agents/code-reviewer.md
.claude/agents/security-reviewer.md

メインエージェントが Agent ツール（旧 Task ツール、v2.1.63 でリネーム）経由で呼び出し、別の context window で並行して動かせる。

特徴：

• メインの context を圧迫しない
• 別ロール・別ペルソナを持たせられる
• 複数同時実行で並列調査ができる

■ Subagent にすべきタイミング

Skill との使い分け：

• Skill = 同じメインエージェントに「手順を渡す」
• Subagent = 別のエージェントに「丸投げする」

Subagent にすべきとき：

• メインのロールと根本的に違う立場で動かしたい（例：レビュアー）
• 大量のファイル読み込みが必要で、メインの context を汚したくない
• 並列で複数の調査をしたい
• メインに見せたくない試行錯誤をやらせたい

逆に Subagent にしないほうがいいとき：

• 結果のすり合わせが多い（往復コストが膨らむ）
• メインの context を持っていないと判断できない
• 1ターンで終わる単純な処理（Skill で十分）

■ Skill / Subagent / CLAUDE.md の使い分け

新しいルールを追加するときの判断表：

• 全セッションで効かせたい方針 → CLAUDE.md
• いつでも呼べる手順書 → Skills
• 別ロールで動かしたい → Subagents
• 危険操作の物理ブロック → settings.json deny
• 編集後の自動チェック → Hooks

これを暗記しておくと、「どこに書くか」で迷わない。

■ 今回のまとめ

• Skills は再利用可能な手順書。description を具体的に書かないと自動ロードされない
• Skill 化は3回ルール（同じ長文プロンプトを3回書いたら）
• Subagents はメインと違うロール / 別 context で動かしたいとき
• Skills は「手順を渡す」、Subagents は「丸投げ」

CLAUDE.md だけで足りなくなったらこの2つで拡張する。 ただし前倒しで作らないのは共通。

次回 Part 5 は Subagent 実装編。具体的な書き方、ロール定義、複数 Subagent の連携など、ここで「概念だけ」にとどめた部分を詳述する。 そのあと Part 6 が最終回 — 運用編。インシデント駆動の改善ループと、再現テストの話。