The herding playbook

群れの導き方

Shepherd shows you every session; this guide is about what to do with that visibility — how to split work across sessions, teammates, subagents and background workers, which model to give each, and how to keep a 10-agent board readable. Everything here works with plain Claude Code; Shepherd just makes it observable.

Shepherd はすべてのセッションを見せてくれます。このガイドは、その可視性を得た上で何をするか についての話です — セッション・teammate・サブエージェント・バックグラウンドワーカーに作業をどう 分けるか、それぞれにどのモデルを与えるか、10エージェントの盤面をどう読みやすく保つか。ここに書く ことはすべて素の Claude Code で成立します。Shepherd はそれを観測可能にするだけです。

1. Pick the right vehicle for each task

1. タスクごとに正しい実行形態を選ぶ

There are four ways to run an agent. They differ in who consumes the result and whether a human can step in mid-flight:

エージェントの実行形態は4種類あります。結果を誰が受け取るか、人間が途中で介入できるかが異なります。

• You own the outcome and might steer it? Interactive session — long-lived workstreams, permission prompts and plan approvals you want to answer yourself, work you'll resume tomorrow.
• A lead Claude orchestrates and integrates? Teammates (or subagents for read-only fan-outs) — split N issues across N workers, parallel research; you only review the synthesis.
• Fire-and-forget with a definite end? Background worker. It holds real memory while parked (~600 MB measured) — the parked chip exists to catch the ones you forgot to stop.
• If there's any chance you'll want to interject mid-task, prefer a separate session over a teammate — teammates have no attach route; their questions reach you only through the lead.

• 結果の責任者はあなたで、途中で舵を取りたい? 対話セッション — 長時間の作業、自分で答えたい権限プロンプトやプラン承認、翌日に再開する作業向け。
• リードの Claude がオーケストレーションして統合する? teammate（読み取り専用の並列展開ならサブエージェント） — N件のissueをN人のワーカーに分割、並列調査。あなたは統合結果だけを見ればいい。
• 撃ちっぱなしで終わりが明確? バックグラウンドワーカー。駐機中も実メモリを保持し続けます（実測 ~600MB）— 駐機中チップは、止め忘れを捕まえるためのものです。
• 途中で口を挟みたくなる可能性が少しでもあるなら、teammate より別セッションを選んでください — teammate には attach 経路が無く、質問はリード経由でしかあなたに届きません。

2. Don't run the whole flock on one model

2. 群れ全体を1つのモデルで走らせない

Model choice is the biggest cost lever in a multi-agent setup, and the default works against you: subagents inherit the parent's model unless told otherwise. Run your lead on a frontier model, spawn ten workers, and you're paying frontier price for grep. Anthropic's own multi-agent research system uses a frontier orchestrator with cheaper workers — match the tier to the subtask, not to the parent.

マルチエージェント構成において、モデル選択は最大のコストのレバーです。しかもデフォルトの挙動は あなたに不利に働きます: 指定しない限り、サブエージェントは親のモデルを継承します。 リードをフロンティアモデルで動かしてワーカーを10体起動すれば、grep 相当の作業にフロンティア価格を 払うことになります。Anthropic 自身のマルチエージェント研究システムも、フロンティアのオーケストレーター に安価なワーカーを組み合わせています — 親ではなくサブタスクにモデルの階層を合わせましょう。

Pricing as of July 2026 — see current pricing.

価格は2026年7月時点 — 最新の価格はこちらを参照。

A Fable lead is 10× Haiku. A board where every model chip is the same color is usually money left on the table — that's why Shepherd puts the tier on every card.

Fable のリードは Haiku の10倍のコストです。盤面のモデルチップが全部同じ色なら、たいてい払わなくて 済むお金を払っています — だからこそ Shepherd は全カードに階層を表示します。

# Subagent — the Agent tool's model parameter
Agent(..., model: "haiku")            # 'haiku' | 'sonnet' | 'opus' | 'fable'

# Teammate — say it in the spawn instruction, or set a default once:
#   /config → "Default teammate model"

# Background worker
claude --bg --model sonnet -p "..."

# Blanket default for all subagents (settings.json env)
CLAUDE_CODE_SUBAGENT_MODEL=sonnet

The exception that proves the rule: single high-stakes judgments (a design tiebreak, a final review before merge) deserve the big model even inside a cheap pipeline. If re-verifying the output is cheap, use a cheap model; if a wrong answer is expensive to detect, pay for the good one.

この原則の例外: 一発勝負の重大な判断（設計の決着・マージ前の最終レビュー）は、安いパイプラインの 中でも大きいモデルに払う価値があります。結果の再検証が安く済むなら安いモデルを、間違った答えを 見抜くのが高くつくなら良いモデルに払いましょう。

3. Keep lineage visible

3. 親子関係を見えるようにする

Shepherd nests children under parents so a 10-agent board still reads as 3 workstreams. In-process teammates and subagents nest automatically (detected from the transcript). For a separate process — launching a new interactive session or background worker from inside a session — export the parent's session id first:

Shepherd は子を親の下にネストするので、10エージェントの盤面でも3つのワークストリームとして読めます。 in-process の teammate とサブエージェントは自動でネストします（transcript から検出）。 別プロセス — セッション内から新しい対話セッションやバックグラウンドワーカーを 起動する場合は、まず親のセッション ID を export してください:

SHEPHERD_PARENT_SESSION_ID=<parent-session-id> claude ...

This is Shepherd's own convention (read from the child's environment via ps), not an official Claude Code variable. Fork/resume lineage needs nothing — Shepherd detects forks from transcript fingerprints and marks them with a branch icon.

これは Shepherd 独自の規約です（子の環境変数を ps 経由で読む）。公式の Claude Code 変数ではありません。fork/resume の親子関係は何もしなくて大丈夫 — Shepherd が transcript の fingerprint から fork を検出し、ブランチアイコンで示します。

4. Let the board drive your attention

4. 盤面に注意を導かせる

The board is sorted by urgency, so the operating loop is simple: if nothing is orange, keep doing your own work. Orange banner → answer it; context gauge red → wrap up or hand off; a parked chip growing a duration → a background worker you forgot to stop; stale? → looks busy but isn't. The full signal table is in Reading the board.

盤面は緊急度順に並ぶので、運用ループはシンプルです: オレンジが無ければ、自分の仕事を 続ければいい。 オレンジのバナー → 答える。コンテキストゲージが赤 → 切り上げるか引き継ぐ。 伸び続ける駐機中チップ → 止め忘れたバックグラウンドワーカー。stale? → 稼働中に見えて実際は止まっている。信号の全一覧は 盤面の読み方にあります。

5. Receive deliverables as URLs

5. 成果物は URL で受け取る

Research reports, design docs, dashboards — have agents publish them as Claude Artifacts instead of chat scrollback. An Artifact is a hosted page with a stable URL: updates keep the same link, and it's readable from anywhere. Shepherd puts the link on the agent's card the moment it's published, so a finished workstream reads as one card carrying a PR badge and an Artifact badge — everything reviewable straight from the board.

調査レポート・設計書・ダッシュボードは、チャットのスクロールバックではなく Claude Artifacts として 公開させます。Artifact は安定した URL を持つホスト済みページで、更新しても同じリンクのまま、 どこからでも読めます。Shepherd は公開された瞬間にそのリンクをカードに載せるので、 終わったワークストリームは「PR バッジ + Artifact バッジが付いた1枚のカード」になり、 盤面から直接レビューできます。

6. A worked example

6. 実例

Shipping four groomed issues in parallel:

整えた4件のissueを並列で出荷する例:

1. Lead session (Fable/Opus, interactive — you and the orchestrator) creates one git worktree per issue. Isolated worktrees mean four agents can't step on each other's checkouts.
2. Implementation teammates (Opus; Sonnet for the well-specified ones), one per issue, each pointed at its own worktree. On the board: four cards nested under the lead, each with its own branch, changed-file count and context gauge.
3. Watch the board, not the terminals. When a teammate goes orange, the question is on the card; relay the answer and go back to your own work.
4. Ship teammates (Sonnet) take over per-issue as implementation lands: commit, push, PR, CI fixes, review rounds. Mechanical work, cheap model, fresh context.
5. Finished records fold into the archive lane. PR badges turn green as CI passes — that's your merge queue.

1. リードセッション（Fable/Opus、対話 — あなたとオーケストレーター）が issue ごとに git worktree を1つ作ります。worktree を隔離することで、4体のエージェントが互いの checkout を 踏み荒らさなくなります。
2. 実装 teammate（Opus。仕様が明確なものは Sonnet）を issue ごとに1体、それぞれ 自分の worktree に向けて起動します。盤面上ではリードの下に4枚のネストカードが並び、それぞれに ブランチ・変更ファイル数・コンテキストゲージが載ります。
3. ターミナルではなく盤面を見る。 teammate がオレンジになったら質問はカードに 載っています。答えを中継したら自分の作業に戻ります。
4. 実装が固まったら ship teammate（Sonnet）が issue ごとに引き継ぎます: commit・push・PR作成・CI修正・レビュー対応。機械的な作業なので安いモデル、コンテキストも新規。
5. 完了した記録はアーカイブレーンに畳まれます。CI が通れば PR バッジが緑になります — それが あなたのマージキューです。

The lead never edits code. Cheap models do the wide work, expensive models do the deep work, and the only human interrupts are the orange cards.

リードは一度もコードを編集しません。広い作業は安いモデルが、深い作業は高いモデルがやり、 人間の割り込みはオレンジのカードだけです。