【Claude Codeサブエージェント入門 第11回】演習(前編)― 練習用リポジトリの準備、準備プロンプトの全文、筆者の記録の読み方

Claude Codeサブエージェント入門 第11回 演習(前編)― 練習用リポジトリの準備、準備プロンプトの全文、筆者の記録の読み方 生成AI

「サブエージェントの演習を始めたいのですが、練習用のリポジトリに何を用意すればよいか分かりません」
「担当の定義を3つ、一から自分で書くのは大変です。そのまま送れる準備のプロンプトがあれば使いたいです」

サブエージェントは、定義を読んだだけでは身につきません。一覧に出るか、名前を言わずに頼んだとき選ばれるか、どのモデルで動くかは、動かして初めて分かります。

第11〜13回は、この連載の演習です。連載「Claude Code実践入門」第8回(演習 前編:準備から実装と検証まで)で作った練習用のリポジトリ(~/practice)に、調べる・作る・確かめるの3つの担当を置き、手順1〜7を順に試します。全体で約30分です。3回に分けて、次のように進めます。

  • 第11回(この回):準備。準備プロンプトの全文と、モデル・モードの設定、筆者の記録の読み方
  • 第12回:手順1〜4(担当の一覧、呼び出し、/tasks でモデルを見る、Explore のモデルの上書き)
  • 第13回:手順5〜7、4D での振り返り、自己点検、連載の結び

各手順の後には、「筆者の環境ではこうなった」の囲みを載せます(第12回・第13回)。この回では、その囲みの読み方と、準備を扱います。


この回でやること

演習は、練習用のリポジトリに3つの担当を置き、第1〜10回の内容を一度ずつ手で確かめます。流れは次の図のとおりです。第11回(この回)は準備、手順1〜4は第12回、手順5以降は第13回です。

演習(前編)の流れを上から下へ並べた図。準備は、~/practice を用意し、準備プロンプトを送る。3役を .claude/agents/ に置き、git commit まで進める。自分専用の検証用ホストで行い、本番や共用のホストは使わない。「手動」・既定のモデル・中で始める。準備のあとは新しいセッションで手順1へ。手順1は、「使えるサブエージェントの名前と説明を一覧にして」と頼む。確認は、3役が出るか。description が無い定義は一覧に出ず、エラーも出ない。手順2は、「@infra-researcher roles/ntp が何を設定しているか、ファイルと行を調べて」と送り、続けて名前を言わずに「roles/ntp の tasks はどこで定義されている?」と送る。確認は、返す形どおりか(結論・根拠〔ファイル:行〕・分からなかったこと・障害)。名前を言わない依頼では、どの担当が選ばれるか。手順3は、担当が動いている間(または直後)に /tasks を打つ。確認は、infra-researcher のモデルと effort(haiku・medium のはず)。版によって haiku が Haiku 4.5 のことがある。手順4(任意)は、「このリポジトリの構成を Explore で調べて」と送り、次に .claude/agents/Explore.md(name: Explore、model: haiku)を作らせ、同じ依頼を送る。確認は、Explore のモデルが、本体と同じモデルから Haiku に変わるか。終わったら Explore.md は消す。

演習の画面は、Claude デスクトップアプリの Code タブを前提に書きます。CLI の操作は「CLI では」と添えます。数値と仕様は2026年10月時点です。


筆者の記録の読み方

各手順の後に、「筆者の環境ではこうなった」の囲みを付けます。筆者が試した環境は次のとおりです。

  • 日付と環境:2026-10-18。筆者の PC(Ubuntu 26.04.1、ansible-core 2.20.1、ansible-lint 26.1.1)、Claude Code 2.1.302 の CLI、個人のアカウント
  • 試し方:対話の画面ではなく、非対話の claude -p で試した。本体のモデルは指定せず、既定(claude-opus-5-5 で動いた)。権限モードは「手動」(--permission-mode default)で、作成担当の手順(第13回の手順5)だけ「編集を受け入れる」
  • 練習用のリポジトリ:~/practice。連載「Claude Code実践入門」の演習のあと、連載「Claude Codeスキル入門」の演習で ansible-verify のスキルを足した状態(.claude/settings.local.json に Skill(ansible-verify) の allow がある)を引き継いだ
  • 担当のモデル:セッションの記録(~/.claude/projects/ の下の subagents/*.jsonl に残る model)で見た

確認の画面が出る操作は、-p では「承認が要る」として実行されずに終わります(Code タブなら確認の画面が出る所です)。囲みで「承認が要って止まった」とあるのは、この意味です。また、-p には /tasks と /usage が無いので、担当のモデルは上の記録で、費用は -p が返す total_cost_usd(API の定価で換算した値。Pro・Max では使用量の枠から引かれる)で見ました。

Code タブ・CLI・-p の対応は、次のとおりです。

操作Code タブCLI(対話)-p(筆者の記録)
担当を名前で指定する筆者は確かめていない(公式の desktop のページに、@ で担当を選ぶ記述は見つかっていない)入力欄で @ を打ち、候補から担当を選ぶ(公式の sub-agents)@ は名前の文字列として本体に渡り、本体が担当を選ぶ。「infra-researcher 担当に…」と頼んだ
動いている担当のモデルを見る筆者は確かめていない/tasks(担当の行にモデルと、あれば effort が出る。v2.1.242 以降)/tasks は無い。セッションの記録の model で見た
使用量を見る/usage(筆者の Code タブで使えた。担当ごとの内訳は確かめていない)/usage/usage は無い。total_cost_usd で見た
.claude/ への書き込み確認の画面が出る(保護されたパス)同じ承認が要るものは止まる

出典:https://code.claude.com/docs/ja/sub-agents 、https://code.claude.com/docs/ja/permission-modes

費用の目安は、後編の第13回にまとめて載せます。


準備

用意するもの

  • 連載「Claude Code実践入門」第8回の ~/practice:自分専用の検証用の環境(SSH の検証用ホストか手元の「ローカル」)にある練習用のリポジトリ。ansible-core と git が入っていること。ansible-lint も入っていればよい。環境の選び方は、同じ第8回の「環境を選ぶ」を参照。本番や共用のホストは使わない
  • ~/practice が無い人は、先に第8回の「準備プロンプト」で作る
  • 連載「Claude Codeスキル入門」の ansible-verify(第6・7回):あれば第13回の手順6で使う。無くても、下の準備プロンプトが短い版を作る

モデルとモード

練習用のリポジトリを開いた新しいセッションで、最初のプロンプトを送る前に、入力欄の下の表示を「手動」・既定のモデル(Opus 5.5)・Effort は中にします。

  • モデルと Effort:連載「Claude Code実践入門」第1回の「モデルとEffortの選び方(公式の推奨)」のとおり、公式の既定(Opus 5.5・Effort medium)から始めます。筆者が演習で送った版は本体のモデルを指定していましたが、ここでは既定のモデル・中にしています。筆者の記録も、モデルを指定せずに起動して Opus 5.5 でした。担当のモデルは、本体とは別に、担当の定義の model で決まります(第5回の「モデルの決まる順番」)
  • 確認の画面:.claude/ の下(agents・skills・hooks・settings.json)への書き込みは保護されたパスで、「手動」でも「編集を受け入れる」でも確認が出ます。内容を見て、その1回だけ許可します。公式の permission-modes は、この確認に、そのセッションの間だけ .claude フォルダーの編集を許す選択肢(「Yes, and allow Claude to edit files in this project’s .claude folder for this session」)が出ることがある、と書いています(この演習では、1つずつ内容を見るために使いません)。筆者の -p の記録では、3つのファイルの書き込みは、どれも承認待ちになりました
  • 新しいセッションで:準備プロンプトのあとは、新しいセッションで手順1に進みます。公式は、セッションの開始時に無かった agents フォルダーに最初のファイルを置いたときは、再起動しないと読み込まれない、と書いています(第4回の「反映のタイミングと、読み込まれないとき」)。準備で初めて .claude/agents/ を作るなら、これに当たります

準備プロンプト

次のプロンプトを、~/practice のセッションに送ります。Claude が、.claude/agents/ に3つの担当(調べる・作る・確かめる)のひな形を置き、git commit まで進めます。ansible-verify が無ければ、短い版も置きます。

使い方

  1. ~/practice を開いた新しいセッションを作る
  2. 最初のプロンプトを送る前に、入力欄の下を「手動」・既定のモデル・中にする
  3. 下のプロンプトをそのまま送る。.claude/ への書き込みは確認が出るので、内容を見てから、その1回だけ許可する
  4. 報告を見て、.claude/agents に3つのファイルがあること、作業ツリーがきれいなこと(git status --short に何も出ないこと)を確かめる
  5. 新しいセッションを作ってから、手順1を始める

送るプロンプト

サブエージェントの演習の準備をしてください。書いてあること以外はしないでください。コマンドの前後に何も付け足さないでください。終了コードは報告しなくてよいです。
1. git status --short を実行し、結果をそのまま報告する。何か出ていたら、ここで止まって私に聞く
2. 次の3つのファイルを、記載の内容そのままで作る(既にあれば、上書きせずに止まって私に聞く)
3. ls -d .claude/skills/ansible-verify を実行する。見つからないときだけ、下の「ansible-verify の短い版」のファイルも、記載の内容そのままで作る
4. git add .claude を実行し、git commit -m "担当エージェントのひな形(3役)" を実行する
5. ls -R .claude/agents .claude/skills と git log --oneline -3 を実行し、結果をそのまま報告する

--- ファイル: .claude/agents/infra-researcher.md ---
---
name: infra-researcher
description: リポジトリ・手順書の中を読んで、聞かれた事実だけを調べて返す調査担当。ファイルは変更しない。「調べて」「どこで定義されている?」「既定値は?」と頼まれたときに使う。
tools: Read, Grep, Glob
model: haiku
effort: medium
---
あなたは調査担当です。ファイルは変更しません。聞かれたことだけを調べます。
推測で埋めず、見つからないものは「分からなかったこと」に書きます。
返す形:
1. 結論(1〜3行)
2. 根拠(ファイル:行)
3. 分からなかったこと(なければ「なし」)
4. 遭遇した障害(なければ「なし」)

--- ファイル: .claude/agents/playbook-writer.md ---
---
name: playbook-writer
description: Ansible の playbook・role を作る・直す作成担当。直すファイルと内容が決まっているときに「playbook を書いて」「role を直して」と頼まれたら使う。
tools: Read, Grep, Glob, Edit, Write, Bash
model: sonnet
effort: medium
---
あなたは作成担当です。頼まれた変更だけを行い、頼まれていないファイルは変えません。
Bash は ansible-lint・ansible-playbook --syntax-check・git diff・git status だけに使います。本実行(--check なし)と inventory/prod への実行はしません。
Ansible のコマンドは 2>&1 | cat を付け、成否は出力で見ます。
返す形:
1. 変更したファイル(パスと要点)
2. 理由
3. 未確認の点(なければ「なし」)
4. 遭遇した障害(なければ「なし」)

--- ファイル: .claude/agents/playbook-reviewer.md ---
---
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. 遭遇した障害(なければ「なし」)

--- ansible-verify の短い版(手順3で、見つからないときだけ作る) ---
--- ファイル: .claude/skills/ansible-verify/SKILL.md ---
---
name: ansible-verify
description: Ansible の playbook・role を変更した後の検証(ansible-lint、構文確認、stg への --check --diff)を行う。「検証して」「lint 通る?」「stg で差分を見て」と頼まれたとき、または playbook を編集し終えたときに使う。
---
# Ansible の検証(短い版。完全版は scripts/verify.sh を使う)
1. 次の3つを順に実行する(失敗しても3つとも実行する):
   ansible-lint 2>&1 | cat
   ansible-playbook --syntax-check -i inventory/stg site.yml 2>&1 | cat
   ansible-playbook --check --diff -i inventory/stg site.yml 2>&1 | cat
2. 報告する:実行したコマンド、それぞれの結果(lint の指摘の数、構文の可否、PLAY RECAP)、changed の一覧
3. ここで止まる。差分を読むことと本実行は人の判断
してはいけないこと:本実行(--check なし)、inventory/prod への実行

筆者が演習で送った版から書き換えた所は、次の3か所です。

  • 1行目の演習の名前を「サブエージェントの演習の準備」に、コミットのメッセージを「担当エージェントのひな形(3役)」にした
  • playbook-reviewer の name[casing] の行:筆者が送った版は「日本語のタスク名」を想定内としていましたが、筆者の実測では、指摘されるのは英小文字で始まるタスク名(chronyの参照先を設定する など)だけで、日本語の文字で始まる名前は指摘されません(連載「Claude Code実践入門」第4回の「補足:日本語のタスク名と ansible-lint の name[casing]」)。.ansible-lint の skip_list に入れていれば、そもそも出ません(同第9回の「早く終わったら」)。そこで、この言い方に直した
  • 短い版の ansible-verify の見出しの括弧書きを「完全版は scripts/verify.sh を使う」にした

補足

  • ホストの中は、Claude があなたのユーザーの権限で操作します。自分専用の検証用ホストで行い、共用のホストや本番では行わないでください
  • 3役の中身は、第9回の「3役のひな形(筆者の例)」「ひな形の中身(レビュー担当)」で解説したものと同じです。モデルは別名(haiku・sonnet)で書いています。haiku がどの版の Haiku になるかは、Claude Code の版で変わります(第5回の「別名で書く理由」)。筆者の CLI では、2.1.289 で Haiku 4.5、2.1.302 で Haiku 5.5 でした
  • 調査担当は Web を使いません(Read・Grep・Glob)。Web を使わせたいときは、tools に WebFetch, WebSearch を足します(第3回の「ファイルの形」)
  • ホストのアドレスは文書用の 192.0.2.x(例の値)なので、--check --diff は unreachable で終わります。ansible-lint が name[casing] を指摘するかは、タスク名と skip_list しだいです。どちらも想定内です
  • .claude/settings.json の allow・ask・deny は変えません(inventory/prod を指す実行は ask、ansible-vault view は deny)。deny のルールは担当の Bash にも効きます(ask のルールが担当に効くかを書いた公式の文は見つかっていません。第9回の「レビュー担当(新しい目)」)
  • 第12回の手順4で作る .claude/agents/Explore.md は、終わったら消します(残すと、Explore がずっと Haiku で動きます)
  • Ansible のコマンドを直接実行させるときは、2>&1 | cat を付けさせ、成否は PLAY RECAP で見ます。環境の癖は、連載「Claude Code実践入門」第4回の「チームで共有するCLAUDE.mdのひな形(筆者の例)」と、第8回の「準備プロンプト」の補足を参照

筆者の環境ではこうなった(準備)
ホームの下の ~/practice で、準備プロンプトを「手動」でそのまま送った(--permission-mode default)。
手順1の git status --short は空だった。手順2の .claude/agents/ の3つのファイルの書き込みは、どれも承認待ちになり(保護されたフォルダー)、Claude は「書き込みを許可してもらえれば手順2から続ける。どうしますか」と止まった。手順3の ls -d .claude/skills/ansible-verify は見つかったので、短い版は作らない、と判断した。
筆者は、プロンプトに書かれた中身のまま3つのファイルを置き、git add .claude && git commit を通した(確認の画面で、その1回だけ許可するのに当たる)。このときの playbook-reviewer の name[casing] の行は、書き換える前の「日本語のタスク名は想定内」のままだった(筆者の ~/practice は skip_list に入れてあるので、レビューの結果に name[casing] の指摘は出ていない)。
3役の定義:infra-researcher(tools: Read, Grep, Glob/model: haiku/effort: medium)、playbook-writer(tools: Read, Grep, Glob, Edit, Write, Bash/model: sonnet/effort: medium)、playbook-reviewer(tools: Read, Grep, Glob, Bash/model: sonnet/effort: high)。
コミットのメッセージは、書き換える前の「第4回 担当エージェントのひな形(3役)」だった(この「第4回」は、この連載の回の番号ではない)。


考えてみよう

  1. 準備プロンプトを送る前に、入力欄の下をどう設定しますか。なぜその設定で始めるのでしょうか。
  2. 準備のあと、同じセッションではなく新しいセッションで手順1に進むのはなぜでしょうか。
  3. 筆者の準備の囲みで、3つの担当のファイルの書き込みが、どれも承認待ちになったのはなぜでしょうか。

ヒント:1つ目と2つ目は「モデルとモード」の節、3つ目は同じ節の「確認の画面」と、準備の囲みを見直してください。


まとめ

  • 演習は、連載「Claude Code実践入門」第8回の ~/practice に、準備プロンプトで3つの担当(調べる・作る・確かめる)を置いて行う。第11〜13回の3回で進める
  • 始めは「手動」・既定のモデル・中。公式の既定(Opus 5.5・Effort medium)から始め、担当のモデルは定義の model で決まる
  • .claude/ の下への書き込みは保護されたパスで、確認が出る。筆者の -p の記録では、3つのファイルの書き込みはどれも承認待ちだった
  • 準備のあとは新しいセッションで始める。担当の定義はセッションの開始時に読み込まれる
  • 筆者の記録は、Claude Code 2.1.302 の非対話の claude -p のもの。確認の画面が出る操作は「承認が要る」として止まる。/tasks と /usage は無いので、担当のモデルはセッションの記録、費用は total_cost_usd で見た
  • 手順4で作る Explore.md は、終わったら消す

次回の第12回は、手順1〜4です。新しいセッションで、担当の一覧、呼び出し、/tasks でのモデルの確認、Explore のモデルの上書きを試します。


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

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

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

業務でオンプレミスとクラウドのインフラに携わり、勉強会の資料をもとに、インフラの基礎の入門の連載を書いています。仕様は公式の文書で、手順は手元の Windows・Linux・FreeBSD の環境で確かめています。
プロフィール詳細は「プロフィール」をご覧ください。
AWS Certified Solutions Architect – Professional (https://www.credly.com/badges/fd8feb88-6f1f-42ff-a94b-445bb6661cb8/public_url)
Nutanix Certified Professional - Multicloud Infrastructure 6 (https://www.credly.com/badges/5c081bef-a425-42e4-809c-85138e676630/public_url)
Palo Alto Networks System Engineer (PSE) - Hardware Firewall Professional (https://www.credly.com/badges/69dc3880-4a51-47eb-8843-47ba6ea7d013/public_url)

seichanをフォローする
生成AI
シェアする
seichanをフォローする

コメント

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