✨ はじめに

こんにちは。
普段は機能実装や修正を VS Code 拡張の Claude Code、日々のワークフローをアプリ版の Claude Cowork と使い分けています。

ここ最近、Claude Code で実装を任せる量がはっきり増えました。生成は速い。速いんですが、速くなった分だけ別の場所が詰まるようになりました。レビューです。

この記事は「サブエージェントの作り方」ではなく、レビューを2つの頭にどう分けるかという設計の話です。具体的には、Verification（正しく作ったか）と Validation（正しいものを作ったか）を別々のサブエージェントに割って、.claude/agents/ に置いて運用しています。その設計判断と、実際に Backlog の要件とつないだ動作イメージまで載せます。

対象読者

Claude Code（や類似のエージェント）で実装を任せていて、レビューがボトルネックになってきた人

サブエージェント / カスタムエージェントを「なんとなく1個」で運用していて、いまいち効いている実感がない人

AI に書かせたコードの品質ゲートをどこに置くか悩んでいる人

🧭 1. ボトルネックは上流から下流へ移った

これまで、品質の議論は「上流をどれだけ固めるか」に寄っていた気がします。要件をきちんと書く、仕様を詰める、設計レビューをする。もちろん大事です。

でも、AIが実装を肩代わりするようになって、体感が変わりました。昔は年単位だった量の作業が、日単位で要求される。 生成のスループットが跳ね上がった結果、相対的に「人間が下流で確認する速度」が追いつかなくなってきた。作るのは速いのに、作られたものが正しいか確かめるところで全部が止まる。

ボトルネックが上流から下流に移ったわけです。だったら、補強すべきは下流の検証側だよな、というのがこの記事の出発点です。

🪤 2. なぜ「レビュー役1個」だと浅くなるのか

最初は素直に、レビュー用のサブエージェントを1つ作りました。「バグもセキュリティも要件充足も、ぜんぶ見て」と。

これがうまくいかない。観点を全部詰め込むと、どれも浅くなるんです。よくあったのが、コードがキレイだと要求充足の判定まで甘くなるやつ。実装が整っていると「ちゃんとしてるからOK」と引っ張られて、「で、これそもそも頼まれたものだっけ?」が抜ける。逆に要件ばかり気にすると、エッジケースのバグを素通りする。

混ぜると軸がぶつかる。これは1個の頭に無理をさせている証拠でした。

📐 3. 2つの軸は直交している

整理してみると、見ている軸が2本あって、それが直交していました。

縦軸 = Verification（正しく作ったか）: バグ、セキュリティ、エッジケース、エラーハンドリング。書かれたものが書かれたとおりに正しく動くかを、コードの内側から見る。
横軸 = Validation（正しいものを作ったか）: 要件を満たしているか、利用者にとって良くなっているか。コードを1行も読まず、要求と成果物だけを突き合わせる。

肝は、必要な情報も判断基準も別物だという点です。Verification には diff とコードを渡す。Validation には、コードではなく元の要件・チケット・ユーザーの文脈を渡す。同じ頭にやらせると、さっきの「コードに引きずられる」が起きる。分ければそれぞれの軸に集中できる。

いちばん大事なのが左上の象限、「完璧に動くけど見当違い」 です。バグはゼロ、仕様も満たしている。でも要求とはズレている。これは Verification では絶対に捕まりません。Validation の頭がいないと、丸ごと盲点になる。レビュー役を1個に統合していたとき、自分が見落としていたのはまさにここでした。

ちなみにこの直交、ソフトウェアテストの世界で昔から言う Verification と Validation の違いそのものです。新しい概念ではなく、AIにレビューさせる時代に、改めて効いてくる古い区別という感じ。

🛠️ 4. 実装 ─ `.claude/agents/` に2つ置く

中身は YAML フロントマター付きの Markdown を .claude/agents/ に置くだけ。SKILL.md と同じノリで、description が「いつ呼ぶか」のルーティング条件になります。

🔎 code-verifier（Verification の頭）

---
name: code-verifier
description: コード変更が入ったら必ず使う。差分を読み、バグ・セキュリティ・エッジケース・エラーハンドリングの欠落を技術的に検証する。「正しく作れているか」だけを見る。実装役とは別コンテキストで動かすこと。
tools: Read, Grep, Glob, Bash   # 読む・検索する・チェックを走らせる。Write/Edit は渡さない
model: opus                     # バグ・脆弱性の見落としは高コスト。深い推論を優先
---
あなたはシニアコードレビュアーです。観点は「正しく作れているか（Verification）」だけに限定します。
要求そのものが妥当かどうかは扱いません（それは requirement-validator の仕事）。

手順:
1. `git diff HEAD` で直近の変更を把握する。
2. 変更ファイルに絞って読む。リスクの高い順に: 認証・入力処理・データ露出・並行処理・境界値。
3. 次を重点的に検出する: バグ、SQLi / XSS / IDOR 等の脆弱性、抜けているエッジケース、
   エラーハンドリングの漏れ、リソースリーク、テナント分離の崩れ。
4. 必要なら lint / typecheck / 既存テストを Bash で実行して裏を取る。ただしファイルは一切変更しない。

出力:
- 指摘を CRITICAL / HIGH / MEDIUM / LOW に分類し、`file:line` と最小の修正方針を添える。
- 指摘ゼロなら「技術的な検証では問題なし」と明記する。

禁止事項:
- ファイルの修正・作成をしない（読むだけ・指摘だけ）。
- push 可否の最終判断をしない。最終判断は人間が行う。

✅ requirement-validator（Validation の頭）

---
name: requirement-validator
description: 実装が一区切りしたら使う。元の要件・チケット・受け入れ条件と成果物を突き合わせ、「そもそも正しいものを作れているか」を検証する。コードのキレイさに引きずられないこと。code-verifier とは別コンテキストで動かす。
tools: Read, Grep, Glob   # 要件・チケット・仕様を読むため。実行は不要。Write/Edit は渡さない
model: opus               # 「動くけど見当違い」を捕まえる唯一の頭。inherit でも可
---
あなたはプロダクト品質のレビュアーです。観点は「正しいものを作れているか（Validation）」だけに限定します。
バグ検出は扱いません（それは code-verifier の仕事）。

最重要のルール:
- 要件から読み始める。実装の diff から読み始めない。コードがキレイでも、要求とズレていれば不合格。
- 入力は「元の要件・チケット・受け入れ条件・ユーザーの文脈」。
  これらが見当たらなければ、推測で補わず「要件が特定できない」と報告していったん止まる。

手順:
1. 要件 / チケット / 受け入れ条件を読み、満たすべき項目をリスト化する。
2. 各項目について、成果物が満たしているかを ✓ / △ / ✗ で評価する。
3. 「仕様は満たすが、利用者の本当の課題を解いていない」ズレを特に疑う。
4. 要件にないのに作り込まれた機能（過剰実装）も指摘する。

出力:
- 要件項目ごとの充足表（項目 / 判定 / 根拠）。
- 要求と成果物のズレ・過不足を箇条書きで。

禁止事項:
- コードの修正・作成をしない。
- push 可否の最終判断をしない。最終判断は人間が行う。

補足: 要件が Backlog / Jira 等にある場合は、その MCP ツール（例: mcp__backlog__*）を tools に追加して直接読ませる。

この2ファイルに効いている設計判断が4つあります。

(1) レビュー役には Write / Edit を渡さない。 tools を読み取り系の許可リストにして、修正系を外す。これで「レビューと称して勝手に直す」が構造的に起きません。verifier には裏取り用に Bash を持たせていますが、プロンプト側で「ファイルは変更しない」と明示しています。

(2) input を意図的に変える。これが分割の肝です。 verifier は git diff から読み始め、validator は要件から読み始めて diff を見ない。読む順番を固定することで、「コードのキレイさに引きずられる」を仕組みで防いでいます。図の直交が、そのままファイルに落ちている形です。

(3) 役割を相互に閉じる。 verifier に「要求の妥当性は扱わない」、validator に「バグ検出は扱わない」と書いて、観点の越境を禁止。各頭が自分の軸だけに集中します。

(4) push可否の最終判断は両方とも禁止。 これは後述します。

🔗 実際に Backlog の要件とつなぐ

validator の本領は、要件が手元の頭の外（チケット）にあるときに出ます。tools に Backlog の MCP ツールを足すと、チケットを直接読んで突き合わせてくれます。動作イメージがこちら（顧客名・ID・担当者はマスク済み）。

注目してほしいのは、コードを一度も読まずに受け入れ条件と成果物を突合しているところ。そして✗で過剰実装（要件にない管理画面のCSV出力）を捕まえている点です。完璧に動いても要件外なら✗、という左上象限の話が、そのまま検出として出てきます。最後に push 前で止まっているのもポイントで、これは次の節の話です。

🚧 5. 人間が握る一線をどこに引くか

自分のルールは明確で、ソースコードを変更する前と、git push する前は、必ず人間がレビューする。ここは譲りません。

これを「時代遅れ」とは思っていなくて、責任が移る点で当事者性を保つための設計判断だと考えています。レビューもテストもAIに分担させる。でも「これを世に出す」と決める瞬間だけは握る。

実装上は2段構えにしています。1つは subagent 側のプロンプトに「push 可否の最終判断をしない」と書くこと。もう1つは、オーケストレーション側（メインの依頼）で「レビューとvalidationの結果を見せてから、push せずいったん止まって」と明示すること。エージェントの権限設計と、依頼文の指示、両方で効かせる。

⚖️ 6. トレードオフ：トークンは素直に増える

正直に書いておくと、いいことばかりではありません。サブエージェントはそれぞれ自分のコンテキストを持つので、トークン消費は素直に増えます。 実装役・verifier・validator と頭を分けるほど、単発でやるより数倍いくこともある。「最小トークンで多頭」みたいな夢とは逆方向です。

なので、毎コミットで全頭を回すというより、ある程度まとまった単位で回す運用にしています。質を取るなら払う、というトレードオフはそのまま残る。ここは各自の規模とコストで調整してください。

体感としては、単発レビュー1回に対して2ヘッド分割で数倍のトークンを見ておくと安全です（実装役を除いた verifier + validator 分のオーバーヘッド）。正確な実測値は環境差が大きいので、まずは小さく回して自分の規模で計測することをおすすめします。

💡 7. 追記：実際の使い方 ─ CLAUDE.md に「進め方」を書いておく

このサブエージェントをしばらく運用してみて、1つ大きな学びがありました。エージェントを定義しただけでは、肝心なときに片方しか起動してくれないことがあるんです。「レビューして」とだけ言うと、verifier だけ動いて validator が呼ばれない、みたいなことが起きる。

そこで、プロジェクトの CLAUDE.md に「レビューの進め方」を明文化して、毎回かならず両方起動させるようにしました。実際に入れているのがこれです。

## コードレビューの進め方

実装が一区切りしたら、以下の 2 つのサブエージェントを **必ず両方** 起動してレビューする。
片方だけで済ませない。観点が異なるため、両方そろって初めてレビューが成立する。

- `requirement-validator` … 「正しいものを作れているか」（Validation）
- `code-verifier` … 「正しく作れているか」（Verification）

「レビューして」と言われた場合も、この 2 つを起動する前提で進める。

### 起動時に必ず渡すもの

サブエージェントはメインの会話文脈を引き継がない（別コンテキストで動く）。
そのため、起動プロンプトに以下を明示する。曖昧なまま起動しない。

- 対象の Backlog 課題キー（XD_RELEASE-xxxx 等）と受け入れ条件
  ※ requirement-validator は要件が特定できないと「止まる」設計のため、これは必須
- レビュー対象の差分の範囲（ブランチ / コミット / `git diff HEAD` など）

ポイントは2つです。

(1) 「必ず両方」をルール化する。 これが分割のいちばん怖い落とし穴で、片方だけ回すと「左上象限（完璧に動くけど見当違い）」がまた盲点に戻ります。エージェントを分けた意味が消える。だから surface 側のルールで「両方そろって初めて成立」と縛る。

(2) 別コンテキストだからこそ、入力を明示的に渡す。 サブエージェントはメインの会話を引き継ぎません。これは「コードに引きずられない」ための利点なんですが、裏を返すと要件もチケット番号も自動では伝わらないということ。特に validator は要件が特定できないと止まる設計なので、起動時に Backlog の課題キーと受け入れ条件、diff の範囲を必ず添える。.claude/agents/ の定義と CLAUDE.md の運用ルール、この2枚がそろって初めて狙いどおり動く、という感覚です。

🌱 8. まとめ ─ 育て方

レビューを1個の頭に詰め込むと浅くなる。Verification と Validation は軸が直交しているので分ける。
分割の肝は input を変えること。verifier は diff、validator は要件から読み始める。
レビュー役には Write を渡さない。最終判断（push可否）は人間が握る。
代償としてトークンは増える。まとまった単位で回す。
定義しただけでは片方しか動かないことがある。CLAUDE.md に「必ず両方／渡すものを明示」と書いて運用で縛る。

最初から .claude/agents/ に固定する必要はなくて、まずは依頼文の中で「実装が終わったら別の頭にレビューさせて、さらに別の頭に要件と突合させて、push せず止まって」と書くだけでも動きます。「この頭、毎回欲しいな」と思ったらファイルに固定する。スキル開発と同じ育て方です。

作るのが速くなった分、どこで品質をゲートするかを設計できる人の価値が上がっている気がします。この記事がその一例になれば。

この記事のサブエージェント定義は、自分の運用をそのまま抜き出したものです。環境に合わせて tools や model は調整してください。