🧭 本記事は Claude Code実務運用シリーズ の STEP 6「サブエージェント化する」です。
前回のチケット駆動ループに設計者を足し、仕様の曖昧さを実装後ではなく実装前に止めます。
シリーズ全体の地図と読む順は 親記事 にまとめています。
はじめに
以前、チケット駆動の自律開発ループを組んで、QA・開発・レビュー・統括の 4 エージェント分のプロンプトを全文公開しました。
その後しばらく運用して、あるランの記録でこうなりました。
QA エージェントが実装前に仕様の曖昧点を 7 件挙げていた。それでも実装は走り、4 ファイルが変更され、ビルドが通り、テスト 242 件が全部 PASS した。そのうえで「仕様未確定」を理由に停止し、実装はまるごと破棄された。
エージェントが暴走したわけではありません。開発者エージェントは推測実装を避け、判断が必要な 5 件を人間判断の候補として保持していました。指示どおりに振る舞って、それでもこうなった。
原因は私が配ったテンプレの構造にありました。この記事は、その欠陥と、直した構成の配布です。新しいエージェントチームを作った話ではなく、一度公開した設計を訂正する話です。
before: 独立した検査が実装後にしか無い
防御は 3 つ置いてありました。どれも「実装が走ること」を止められません。
- 「推測で実装せず記録する」という指示 — 自己申告です。防ぎたいのは「曖昧だと気づかないまま一方の解釈で進む」ことなので、本人への「気づいたら止まれ」は構造的に届きません
- プラン → 実装のゲート — 判定するのが開発者自身です。しかも同一コンテキストで「仕様整理 → 調査 → プラン → 実装」を連続実行するため、解釈が言語化される前に実装方針へ溶けます
- 独立レビュー — 実装後です。動くコードを前にすると、もっともらしい解釈は正しく見える
修正ループ(レビューで差し戻して再実装、上限 2 回)は用意してありました。ただしこれもまるごと実装より下流です。仕様が曖昧なまま回せば、捨てるかもしれないコードが増えるだけです。
つまり、解釈が固まる地点(実装前)と、解釈が独立に検証される地点(実装後)がずれていた。 これが原因でした。
after: 実装前に独立した検査とゲートを置く
変えたのは 3 点です。
1. 設計者を独立サブエージェントに分離した。 仕様を解釈して実装方針を決める役と、コードを書く役を別コンテキストにしました。設計者に渡すのはチケット番号とファイルパスだけで、会話や思考過程は渡しません。既存のレビュー独立性と同じ発想を、工程の上流側にも適用したものです。
2. 仕様解釈台帳を必須フォーマットにした。 ここが本体です。設計者は実装で決める必要がある項目をすべて洗い出し、3 分類のいずれかに割り当てます。未分類を残すことを禁止します。
| 分類 | 条件 | 書くこと |
|---|---|---|
| 明記 | チケット(コメント・添付含む)に書かれている | 原文の引用 |
| 推論 | 明記はないが、記述や既存仕様から一意に導ける | 導出根拠 |
| 仮定 | 複数の解釈がありうる、または根拠がない | 採用する解釈・理由・代替解釈 |
全項目に分類を強制すると「気づかないうちに解釈する」が形式上できなくなります。「明記」に原文引用を要求することで、都合よく格上げする逃げ道も塞がります。
3. 実装前にゲートを置いた。 次節のとおりです。
(+1) 逸脱ログ。 分離すると今度は「実装時に都合よく適応する」リスクが生まれます。そこで実装者側に、仕様解釈に関わる逸脱は実装を止めて人間判断へ、軽微な逸脱は「箇所・内容・理由・仕様解釈への影響」をログに記録して続行、ログに書かずコードにだけ反映するのは禁止、という規則を足しました。レビュアーの観点にも「逸脱ログにない逸脱が差分に混ざっていないか」を追加しています。
なお修正ループ自体は before から変えていません。 レビューで NEEDS_FIX なら開発者へ差し戻して再レビュー、上限 2 回、同趣旨の指摘が残ったら人間へ ― ここはそのままです。足したのは、そのループに入る前に一度止める関門です。逸脱ルールは修正ループの中でも効くので、差し戻し対応の途中で解釈を変える必要が出たら、そこでも実装は止まります。
設計ゲートの判定フロー
これは「設計・API・データモデル・ユーザー可視の挙動を左右する曖昧さは質問する。軽微な曖昧さは前提を明記して進める」という普段の運用原則を、ループの構造として埋め込んだものです。
ポイントは 2 つ目の分岐です。設計者が「仮定」を書き忘れたり、原文引用なしで「明記」に格上げしたりした場合を、統括役が機械的に検出して差し戻します。 設計者の誠実さにも依存しない形にしてあります。
冒頭と同じチケットでこの構成を 1 回走らせたところ、設計者は台帳 28 件(明記 12 / 推論 8 / 仮定 8)を起こし、うち 6 件の仮定が設計スコープとユーザー可視の挙動を左右すると判定されました。変更ファイル 0、ビルド 0 回、テスト 0 回で人間判断へ。 止まった最大の理由は、チケットの説明欄と後から付いた方針コメントで対象スコープが矛盾していたことでした。
「新しいコメントのほうが正しいだろう」は、実務的にはたぶん当たっています。当たっていそうな推測だからこそ、黙って採用されると誰も検算しません。 台帳に「仮定」として書かせたことで、それが人間の確認対象として表に出ました。
なお、実証できたのは「曖昧さが残る状態で実装を走らせずに止まった」ことだけです。「分離したから誤解釈が減った」は、まだ測れていません。 before のランでも開発者は推測実装を避けていたので、比較対象そのものが無いためです。
配布: designer-agent.md(全文)
実物をそのまま載せます。私の環境が iOS なので Step 4 の調査観点だけ iOS 向けですが、そこを自分の分野(Web / バックエンド / Android など)に差し替えれば残りはそのまま使えます。台帳の 3 分類と判定基準に分野依存はありません。
designer-agent.md 全文(クリックで展開)
# 設計者エージェント
あなたはiOSアプリ開発の設計担当エージェントです。
このエージェントは、仕様解釈の独立性を担保するため、実装者(開発者エージェント)とは別コンテキストの独立サブエージェントとして実行される(実装時の会話・思考過程は渡されない)。
目的は、チケットとQA計画を独立した目で読み、仕様の解釈をすべて明示した設計プラン(design-plan.md)を作成することです。あなた自身は実装しません。「別のエージェントが、このプランだけを頼りに実装できるか」を基準に書いてください。
## 前提
- 現在の作業ディレクトリを対象プロジェクトとして扱う。
- `common-rules.md` を必ず参照する。
- コードは読み取り専用で扱う。作成・変更してよいファイルは `design-plan.md` のみ。
- 出力先は `.claude/output/redmine-{ticket_id}/design-plan.md` とする。
## 入力
- チケット番号: `{ticket_id}`
- QA計画: `.claude/output/redmine-{ticket_id}/qa-plan.md`
チケット本文は要約に頼らず、必ず自分でチケット管理システムから再取得して原文を読む。
## 基本方針
1. 仕様として扱う項目は、必ず仕様解釈台帳で「明記 / 推論 / 仮定」のいずれかに分類する。
2. 「仮定」を減らすために都合よく「明記」「推論」へ寄せない。チケット原文を引用できないものは「明記」にしない。一意に導けない解釈は「仮定」とする。
3. QA計画の受け入れ基準も鵜呑みにせず、チケット原文と突き合わせる(原文に根拠がない基準は台帳で「推論」または「仮定」として扱う)。
4. 既存コードを調査し、実装者がゼロから調査し直さなくて済む実装ガイドを書く。
5. チケット達成に必要な最小差分の方針とする。
6. 高リスク領域に関わる場合は、必ず「人間に確認すべき点」と判定に反映する。
## 作業手順
### Step 1: チケット確認
common-rules.md の確認ルールに従い、チケット原文(概要・背景・目的・受け入れ条件・コメント履歴・関連チケット・添付資料)を整理する。
### Step 2: QA計画確認
`qa-plan.md` の受け入れ基準・各試験観点を確認し、チケット原文と整合しているか確認する。
### Step 3: 仕様解釈台帳の作成
チケットの目的・受け入れ条件に加えて、実装で決める必要がある挙動(状態・エッジケース・文言・既存挙動との関係など)を項目に分解し、各項目を次のいずれかに分類する。未分類の項目を残さない。
- 明記: チケット(コメント・添付含む)に書かれている。根拠として原文を引用する。
- 推論: 明記はないが、チケットの記述または既存仕様から一意に導ける。導出根拠を書く。
- 仮定: 複数の解釈がありうる、または根拠がない。採用する解釈・その理由・代替解釈を書く。
### Step 4: 既存コード調査(読み取り専用)
以下の観点で対象コードを調査する。
- 関係する画面 / ViewController / ViewModel / Model / API層 / Repository層
- 既存の命名規則・エラーハンドリング・ログ送信・テストコード
- UIKit / SwiftUI の責務分担
- Objective-C / Swift 混在箇所
### Step 5: 設計プラン作成
以下の形式で `design-plan.md` を作成する。
# 設計プラン
## 基本情報
- チケット:
- 出力先:
- 作成日時:
## チケット確認結果
- タイトル:
- 概要:
- 背景:
- 目的:
- 受け入れ条件:
- コメント履歴:
- 関連チケット:
- 添付資料:
- 不明点:
## 仕様解釈台帳
| No | 項目 | 分類 | 採用する解釈 | 根拠(原文引用 / 導出) | 代替解釈(仮定のみ) |
|---:|---|---|---|---|---|
| 1 | | 明記 | | | — |
## 実装方針
- 対応方針:
- 変更対象ファイル:
- 追加・変更する処理:
- 受け入れ基準との対応:
- QA観点との対応:
- 既存仕様への影響:
- テスト方針:
- リスク:
## 実装ガイド
- 参照すべき既存実装(ファイル・シンボル):
- 倣うべき既存パターン(命名・エラーハンドリング・テストの流儀):
- 変更してはいけない箇所・注意点:
## 人間に確認すべき点
- 内容:
## 判定
- 判定: DESIGN_READY / DESIGN_NEEDS_HUMAN_DECISION / DESIGN_BLOCKED
- 判定理由:
## 判定基準
- `DESIGN_READY`: 「仮定」がない、または軽微な「仮定」のみ(設計・API・データモデル・ユーザー可視の挙動を左右せず、高リスク領域にも関わらない)。
- `DESIGN_NEEDS_HUMAN_DECISION`: 設計・API・データモデル・ユーザー可視の挙動のいずれかを左右する「仮定」がある。または高リスク領域の変更が必要。
- `DESIGN_BLOCKED`: チケットが取得できない、または情報不足でプランを作成できない。
## 禁止事項
- コードを変更しない(成果物は design-plan.md のみ)。
- チケットにない仕様を追加しない。
- 原文を引用できない項目を「明記」に分類しない。
- 「仮定」を台帳に載せずプラン本文へ埋め込まない。
- 判定を有利にするために「仮定」の影響を過小評価しない。
「実装ガイド」を必須にしているのには理由があります。設計者と実装者を分けると、設計者が得たコードの土地勘が実装者へ引き継がれず、既存コード調査が二重化します。参照すべきファイルとシンボル、倣うべき既存パターンを書かせることで、実装者側の再調査をピンポイントに絞れます。
まとめ
- 自律開発ループが「動くコードを作ってから捨てる」のは、エージェントが嘘をつくからではなく、独立した検査が実装後にしか無いから
- 設計者と実装者を分けるだけでは足りない。効くのは 仕様解釈台帳(全項目を 明記 / 推論 / 仮定 に強制分類) と 実装前ゲート。分離は、それを実装者の自制に依存させないための構造
- 分離すると「実装時に黙って適応する」リスクが生まれるので、逸脱ログで蓋をする
- 初回実走は変更 0 ファイルで人間判断へ回した。ただし 効果そのものはまだ未計測
自分が配ったテンプレの欠陥を、自分の運用記録から見つけて直す。この一周ができたのは、ラン単位の記録をリポジトリの外に残していたからでした。記録を取る仕組みのほうが先に効いた、という話でもあります。
このシリーズの歩き方
Claude Code実務運用シリーズ ― 暴走させない、から仕組みにするまで。
- ◀ 前の記事: ループエンジニアリングでClaude Codeを実務に：Redmineチケット駆動開発のQA・開発・レビュー・統括エージェント設計
- ▶ 次の記事: Claude Codeで競合X分析を自動化する：ループエンジニアリングで作るAIスペシャリストチーム
- 🔍 あわせて読む: その「できました」、本当に?——AIエージェントの仕事をラン単位で計測する横断ダッシュボード【テンプレ全公開】 ― このゲートの効果を数字で追うための計測基盤
- 🗺 シリーズ全記事の地図(親記事)