「サブエージェントの演習を始めたいのですが、練習用のリポジトリに何を用意すればよいか分かりません」
「担当の定義を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回です。

演習の画面は、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 が無ければ、短い版も置きます。
使い方
~/practiceを開いた新しいセッションを作る- 最初のプロンプトを送る前に、入力欄の下を「手動」・既定のモデル・中にする
- 下のプロンプトをそのまま送る。
.claude/への書き込みは確認が出るので、内容を見てから、その1回だけ許可する - 報告を見て、
.claude/agentsに3つのファイルがあること、作業ツリーがきれいなこと(git status --shortに何も出ないこと)を確かめる - 新しいセッションを作ってから、手順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に進むのはなぜでしょうか。
- 筆者の準備の囲みで、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サブエージェント入門の入口のページにまとめています。
- サブエージェントとは
- 組み込みの担当と使い分け
- 担当を定義する
- toolsと返す形
- 担当のモデルの決まり方
- 役割とモデル・effort
- スキルから担当を呼ぶ
- 順に使う・前と裏
- ログの要約とレビューの担当
- 費用を測って小さく使う
- 演習(前編):準備(この記事)
- 演習(中編):読み込む・呼ぶ・モデルを見る
- 演習(後編):レビュー・スキル・費用

コメント