🧭 本記事は 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エージェントの仕事をラン単位で計測する横断ダッシュボード【テンプレ全公開】 ― このゲートの効果を数字で追うための計測基盤
🗺 シリーズ全記事の地図(親記事)