【Claude Codeサブエージェント入門 第9回】ログの要約とレビューの担当 ― 失敗を隠さない返す形、新しい目のレビュー担当、3役のひな形(筆者の例)

Claude Codeサブエージェント入門 第9回 ログの要約とレビューの担当 生成AI

「ログが長いので担当に要約させたら、『テストが失敗しました』としか返ってきません」
「自分が書いたものを同じ会話でレビューさせると、いつも『問題ありません』になってしまいます」

第8回(順に使う・前と裏)では、担当を順に使う条件、前と裏、巻き戻しで戻らないこと、調べものと Ansible の流れを見ました。その中で、ログの要約は調査担当に、差分の確認はレビュー担当に回しました。第9回は、この2つの担当の返す形と書き方です。

第9回では、ログの要約で失敗を隠さない書き方、経緯を知らない目で見るレビュー担当、そして調査・作成・レビューの3役のひな形(筆者の例)と、レビュー担当の定義の全文を扱い、最後にチームで使うなら決めておくことを挙げます。3役のひな形は筆者の例で、公式の推奨ではありません。数値・仕様は2026年10月時点で、筆者が試した結果は Claude Code 2.1.302 の CLI(非対話の claude -p、2026-10-18)です。


ログの要約で失敗を隠さない

長いログを担当に要約させるのは、担当に向いた作業です。ただし、要約が失敗を隠すことがあります。

  • Academy の注意:「テストが失敗しました」とだけ返す担当は、診断に要る出力を隠す。Academy は、テストランナーのパターンは構成の中で最も性能が低いと書く(Academy の記述)
  • 公式の例:「失敗したテストとエラーメッセージだけを報告する」。公式は、出力が大きい作業を担当に隔離する例として挙げる
  • 筆者の書き方(筆者の例):全文はファイルに残し、PLAY RECAP の数と、failed・unreachable のタスクの原文を返す
  • ログの作り方:本体が 2>&1 | cat を付けて実行し、全文をファイルに保存する。調査担当(Read, Grep, Glob)はそのファイルを読んで要約する
  • 直しは本体で:失敗の原因を探して直す作業は、前の発見に強く依存するので担当に任せない(第8回の「逐次パイプラインとの両立」)
ログの要約で失敗を隠さない仕組みを示した図。最上段の赤い帯に「「テストが失敗しました」とだけ返す担当は、診断に要る出力を隠す」とあり、赤い×印が付いている。その下に左から右へ、オレンジの箱「本体 2>&1 | cat を付けて実行」、灰色の箱「全文をファイルに保存 logs/verify.txt」、「読む」の矢印で緑の箱「調査担当(Read, Grep, Glob)が要約」が並ぶ。調査担当から「返す」の矢印が下の枠「返す形」へ伸び、中身は「## 要約」に続けて PLAY RECAP: ok=3 changed=0 failed=0 unreachable=1、「## 失敗したタスクの原文」に続けて fatal: (192.0.2.11): UNREACHABLE! => {"unreachable": true, "msg": "…"}、「## 全文の置き場所」に続けて logs/verify.txt。最下段のオレンジの枠「直しは本体で」に、失敗の原因を探して直す作業は、前の発見に強く依存する。担当に任せない、とある。

調査担当に返させる形の例です。

## 要約
PLAY RECAP: ok=3 changed=0 failed=0 unreachable=1
## 失敗したタスクの原文
fatal: [192.0.2.11]: UNREACHABLE! => {"unreachable": true, "msg": "…"}
## 全文の置き場所
logs/verify.txt

要約は短く、失敗の原文と、全文の置き場所が付いています。要約だけを読んだ本体が判断を誤りそうなときも、logs/verify.txt を開けば、担当が見たものを自分で確かめられます。

補足です。

  • 返す形の欄は、第4回の「返す形と、障害の報告」で扱った担当の定義の書き方です。「遭遇した障害」の欄を設けておくと、担当が詰まったことも報告に出ます
  • 2>&1 | cat を付けるのは、Claude Code から ansible 系のコマンドを実行すると「Ansible requires blocking IO」で止まることがあるためです。終了コードは cat の0になるので、成否は PLAY RECAP で見ます(連載「Claude Code実践入門」第4回の「チームで共有するCLAUDE.mdのひな形(筆者の例)」の「環境の癖」)
  • Academy の「最も性能が低い」に当たる公式の記述は、筆者は見つけられていません

出典:https://academy.claude.com/ja/courses/introduction-to-subagents/using-subagents-effectively 、https://code.claude.com/docs/ja/sub-agents


レビュー担当(新しい目)

書いた会話の中でレビューさせると、レビューが甘くなりがちです。Academy は、Claude はコードが他の誰かが書いたものとして示されたときに、より効果的にレビューすると説明しています。作成に関わった会話では、新鮮な目で見るのが難しいからです。

レビュー担当(playbook-reviewer)は、別のコンテキストで git diff を実行し、変更されたファイルを読み、書かれた経緯を知らないまま基準を当てます(連載「Claude Code実践入門」第7回の「新しい目でレビューする」)。

  • 基準は担当の本文に書く:レビューの基準を担当の本文に書いておけば、誰が頼んでも同じ基準になる
  • Edit と Write は持たせない:Bash は git diff と ansible-lint のためだけに持たせる
  • 「変更しない」は本文の指示:道具で外せるのは Edit と Write まで。Bash の使い方の制限は、本文と deny ルールで補う
  • model は sonnet、effort は high:確かめる役は、軽くしすぎない(筆者の例)

deny ルールについては、補足があります。連載「Claude Code実践入門」第6回の「Ansibleの作業での設定例(筆者の例)」にある deny が、担当の Bash にも及ぶかを、公式の文書で確かめました。公式のサブエージェントのページには、組み込みの担当は親の会話の権限ルールを引き継ぐ(「Each inherits the parent conversation’s permission rules」。組み込みの担当の段落の文です)と書かれ、さらに「The rule applies to the main conversation and to subagents.」という文もあります(2026年10月18日に確認)。ただし、同じ日に取った permissions のページの全文には、同じ文が見つかりませんでした。また、ask ルールが担当にも効くかを書いた文は、見つかっていません。deny だけに頼らず、tools で Edit・Write を外し、本文にも書く、という重ね方を勧めます。

要点

  • 経緯を知らない担当に、差分を読ませる
  • 基準は担当の本文に書き、誰が頼んでも同じにする
  • Edit・Write は持たせず、sonnet・high で動かす

筆者が試したら

「手動」で、「playbook-reviewer 担当に、git diff を見てレビューさせて」と頼みました(Claude Code 2.1.302、claude -p)。担当(claude-sonnet-5-5 で動きました)は、ファイルを編集せず、git diff 2>&1 | cat で差分を見て、main.yml・defaults・site.yml・.ansible-lint を読み、ansible-lint と ansible-playbook --syntax-check を実行しました。

返ってきた判定は「直す(軽微)」で、理由は「(確認)が何を確認するのか分からない。一時的な印なら戻す」でした。もとからある点として、regexp なら最後の1行の注意には当たらないこと、ほかの server・pool 行が残ることがあること、handler が無いので chronyd に反映されないことも挙げました。さらに、担当が確認したこと(lint 0・構文成功)と、まだ確認していないこと(stg の --check --diff、冪等性は実機で確かめていない)を分けて返しました。返す形の「判定」と「遭遇した障害」を、決めた形で出してくれた例です。この演習は、第13回の手順5で手順どおりに扱います。


3役のひな形(筆者の例)

筆者のひな形は3役です。これは筆者の例で、公式の推奨ではありません。公式は、担当を速く安いモデル(Haiku など)に回して費用を抑える使い方を挙げ、単純な担当の作業には model: haiku を書くよう勧めています(sub-agents、costs)。3役への割り当て(調べる=haiku・作る=sonnet・確かめる=sonnet・high)は、筆者が決めたものです。

担当役割model・efforttools返す形
infra-researcher調べる(調査担当)haiku・mediumRead, Grep, Glob だけ(Web なし)結論、根拠(ファイル:行)、分からなかったこと、遭遇した障害
playbook-writer作る(作成担当)sonnet・mediumRead, Grep, Glob, Edit, Write, Bash変更したファイル、理由、未確認の点、遭遇した障害
playbook-reviewer確かめる(レビュー担当)sonnet・highRead, Grep, Glob, Bash(Edit なし)重大・主要・軽微、判定、遭遇した障害
3役のひな形を示す図。最上部に橙の箱「判断は本体と人(opus)」。その下に3枚のカードが縦に並ぶ。緑の「infra-researcher」は虫眼鏡のアイコンで「haiku・medium」「tools: Read, Grep, Glob(Web なし)」。青の「playbook-writer」はチェックリストのアイコンで「sonnet・medium」「tools: Read, Grep, Glob, Edit, Write, Bash」。青の「playbook-reviewer」は丸いチェックのアイコンで「sonnet・high」「tools: Read, Grep, Glob, Bash(Edit なし)」。最下部の灰色の帯に「.claude/agents/ に置き、Git で共有」
  • 調べる:haiku・medium・読み取りだけ
  • 作る:sonnet・medium・編集と Bash
  • 確かめる:sonnet・high・Edit なし
  • 置き場所:各リポジトリの .claude/agents/。Git で共有する(公式のサブエージェントのページも、プロジェクトの担当を Git に入れてチームで共有するよう勧めています)

調査担当は haiku・medium で、読み取りだけ、出典つきにしています。Anthropic の Haiku 5.5 のガイドは、Effort が low・medium のとき、Haiku 5.5 は変更を確かめずに「完了」と報告することがある、と注意しています(https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5 の節「Tell coding agents to verify their changes」。連載「Claude Code実践入門」第7回の「検証を強制する4段階」でも引いています)。この注意は medium でも当てはまるので、この例では Haiku の担当には書き込みと判断を任せず、確かめる役は Sonnet の high にしています。判断は、本体と人です。

担当の定義は、.claude/agents/ に置きます。このフォルダーへの書き込みは保護されたパスで、「手動」でも「編集を受け入れる」でも確認が出ます(連載「Claude Code実践入門」第5回の「6つの権限モード」の、保護されたパス)。筆者が試したときも、3つのファイルの書き込みは、どれも承認待ちになりました。


ひな形の中身(レビュー担当)

レビュー担当の定義の全文です。

  • ファイル:.claude/agents/playbook-reviewer.md。frontmatter が設定、本文が担当のシステムプロンプト
  • 見る観点:冪等性、inventory/prod に触れていないか、秘密情報、deny に当たるコマンド(連載「Claude Code実践入門」第6回の「Ansibleの作業での設定例(筆者の例)」)
  • 返す形:重大・主要・軽微、判定、遭遇した障害の欄
---
name: playbook-reviewer
description: Ansible の差分を、経緯を知らない目でレビューする。playbook や role を直した後に「レビューして」と頼まれたら使う。
tools: Read, Grep, Glob, Bash
model: sonnet
effort: high
---
git diff で変更を確かめ、変更されたファイルを読んでレビューする。
ファイルは変更しない。Bash は git diff・ansible-lint・ansible-playbook --syntax-check だけ。
Ansible のコマンドは 2>&1 | cat を付け、成否は出力で見る。
観点:冪等性、inventory/prod への影響、秘密情報、deny に当たるコマンド。
ansible-lint の name[casing](英小文字で始まるタスク名の指摘。.ansible-lint の skip_list に入れていれば出ない)は想定内として扱う。
返す形:
1. 指摘(重大/主要/軽微。ファイル:行と理由)
2. 判定(このまま進める/直す)
3. 遭遇した障害(なければ「なし」)
  • description は、いつ使うかを書く。「レビューして」と頼まれたら使う、と書いておくと、Claude が任せる判断に使う
  • tools に Edit・Write が無いので、ファイルの編集はできない。Bash だけは持つので、git diff・ansible-lint・--syntax-check に限る、という制限は本文の指示で書く
  • model と effort は、筆者の例では sonnet と high。別名で書いたので、版が変わると解決先も変わる(第5回の「別名で書く理由」)

name[casing] の行は、「日本語のタスク名」と書きたくなりますが、筆者が ansible-lint 26.1.1 で確かめると、指摘されたのは英小文字で始まる名前(たとえば chronyの参照先を設定する)だけで、日本語の文字で始まる名前は指摘されませんでした。そのため、定義には「英小文字で始まるタスク名の指摘」と書き、.ansible-lint の skip_list に入れていれば出ないことも添えています(連載「Claude Code実践入門」第4回の「補足:日本語のタスク名と ansible-lint の name[casing]」)。

調査・作成のひな形は、演習の準備プロンプトが練習用のリポジトリに置きます(第11回の「準備プロンプト」)。担当の定義に、本実行は書きません。


チームで使うなら決めておくこと

3役のひな形を、複数人で使うときに決めておくことを5つ挙げます。いずれも筆者の案で、公式の推奨ではありません。決まったことは、あとで各リポジトリの担当の定義に反映します。

  1. 3役のひな形:名前・model・effort・tools はこれでよいか。置き場所は、各リポジトリの .claude/agents/ か、個人の ~/.claude/agents/ か(第2回の「担当の置き場所と優先順位」)
  2. どこまで分けるか:調査→作成→レビューを担当に分けるか。作成と直しは本体に残すか(第8回の「逐次パイプラインとの両立」)
  3. 費用:使用量の枠の中で、担当を使う作業をどれにするか。資料1つで約67ドル相当(API の定価で換算)の使い方を、チームで許すか(第10回の「筆者の例:資料1つで約67ドル相当」)
  4. レビューの基準:レビュー担当の本文に書く、チームの観点は何か(上の「ひな形の中身(レビュー担当)」と、連載「Claude Code実践入門」第7回の「新しい目でレビューする」。この担当は、連載「Claude Codeフック入門」でも使います)
  5. モデルの書き方:この連載のひな形は別名で書きました。版を固定したい場面はあるか(第5回の「別名で書く理由」)

組織(Team・Enterprise)で使う場合の、管理設定や許可リストの話は、第5回の「組織の許可リスト(availableModels)と置き換え」にあります。


考えてみよう

  1. 今の担当(またはスキル)は、失敗したときに何を返しますか。「失敗しました」だけで、診断に要る原文と全文の置き場所が欠けていませんか。
  2. 自分が書いた変更を、その会話の中でレビューさせたことはありますか。経緯を知らない担当に頼むと、何が変わりそうですか。
  3. 3役のひな形のうち、自分の作業に足りない役は何ですか。その役の tools、model、effort、返す形を、筆者の例と比べて決めてください。

ヒント:1は「ログの要約で失敗を隠さない」の節、2は「レビュー担当(新しい目)」の節、3は「3役のひな形(筆者の例)」の節を見直してください。


まとめ

  • ログの要約は、全文はファイルに残し、PLAY RECAP の数と、failed・unreachable のタスクの原文を返す。「失敗しました」だけでは、診断に要る出力が隠れる。直しは本体で
  • レビュー担当は、別のコンテキストで git diff を実行し、経緯を知らないまま基準を当てる。基準は担当の本文に書き、Edit・Write は持たせず、sonnet・high で動かす(筆者の例)
  • 3役のひな形は、調べる(haiku・medium・読み取りだけ)、作る(sonnet・medium・編集と Bash)、確かめる(sonnet・high・Edit なし)。筆者の例で、公式の推奨ではない
  • 定義は .claude/agents/ に置き、Git で共有する。.claude/ への書き込みは確認が出る。担当の定義に本実行は書かない
  • チームで使うなら、3役のひな形・どこまで分けるか・費用・レビューの基準・モデルの書き方の5つを決めておく(筆者の案)
  • deny が担当にも効く、という公式の文は確認したが、ask が担当に効くかの文は見つかっていない。道具(tools)で外せるものは外す

次回は、担当も同じ使用量の枠を使うこと、筆者の費用の例、/usage の内訳の見方、小さく使う工夫を扱います。


連載「Claude Codeサブエージェント入門」全13回

全回の目次と、読む順番・目的別の読み方は、Claude Codeサブエージェント入門の入口のページにまとめています。

  1. サブエージェントとは
  2. 組み込みの担当と使い分け
  3. 担当を定義する
  4. toolsと返す形
  5. 担当のモデルの決まり方
  6. 役割とモデル・effort
  7. スキルから担当を呼ぶ
  8. 順に使う・前と裏
  9. ログの要約とレビューの担当(この記事)
  10. 費用を測って小さく使う
  11. 演習(前編):準備
  12. 演習(中編):読み込む・呼ぶ・モデルを見る
  13. 演習(後編):レビュー・スキル・費用

コメント

タイトルとURLをコピーしました