独立コンテキストの subagent には grill-with-docs を渡せ

TL;DR

subagent は 独立したコンテキストで動く。メインの長い会話を引き継がないので「察してくれ」が一切効かない。渡した文脈が全てだ
だから薄い指示を投げると、薄い仕事が返ってくる。並列で 3 つ回せば薄い仕事が 3 つ並ぶ
Matt Pocock の
```
grill-with-docs
```
は、頭の中の暗黙の前提を問い詰めて
```
CONTEXT.md
```
/ ADR に外部化するスキル
この 2 つは欠点を埋め合う。subagent の「文脈が渡らない」弱点を、grill-with-docs の「文脈を外部化する」出力がちょうど埋める

subagent は「察してくれない」

Claude Code の subagent（Agent ツールで起動する、独立したコンテキストを持つ Claude インスタンス）は、メインエージェントのコンテキストを引き継がない。これは設計上の強みで、メインの会話がどれだけ長くなっても subagent の作業は汚染されない。

だが裏返すと、こういう性質になる。

メインの会話で積み上げた前提・経緯・暗黙の了解を、subagent は何ひとつ知らない。

人間相手なら「いつもの感じで」「さっき話したやつ」で通じる。subagent には通じない。渡した指示に書かれていないことは、subagent にとって存在しない。書かれていない部分は、subagent が自分の解釈で勝手に埋める。

実際にやって痛い目を見た。「Issue #1234 を実装して」程度で投げると、subagent は曖昧な部分を各自の解釈で埋めて実装してくる。並列で 3 つ走らせれば、詰めの甘い実装が 3 つ同時に上がってくる。レビューと手戻りも 3 倍だ。並列化は、薄い指示を薄い成果に増幅する装置でもある。

subagent をうまく使う鍵は、結局これに尽きる。

曖昧さのない明示的な文脈さえ渡せば、subagent は独立して完走できる。問題は、その文脈をどう用意するか。

grill-with-docs は暗黙の前提を外部化する

その「明示的な文脈」を作る道具が、Matt Pocock の

grill-with-docs

（SKILL.md）だった。名前から「ドキュメントでまとめるスキル」だと思い込んでいたが、実際はまったく違う。計画を既存のドメインモデルに対して容赦なく問い詰める スキルだ。

Matt Pocock 本人の定義（拙訳）はこう。

共通理解に達するまで、この計画のあらゆる側面について容赦なくインタビューする。設計ツリーの各枝を降りていき、決定間の依存関係を 1 つずつ解消する。

具体的な挙動はこうなっている。

質問を 1 つずつ投げ、回答を待ってから次へ進む。コードで答えが出るものは、聞かずにコードを探索して確認する
曖昧・多義的な用語が出たら正準的な用語を提案して研ぐ。「あなたは "account" と言ったが、Customer か User か。別物だ」
グロッサリー（
```
CONTEXT.md
```
）と矛盾する用語の使い方は即座に指摘する
コードと食い違う主張が出たら矛盾を表に出す
決定が固まった その場でする。
```
CONTEXT.md
```
（用語集）と ADR を更新
```
CONTEXT.md
```
は実装詳細を持たない用語集に徹し、ADR は「後戻りしにくい・文脈なしだと驚かれる・本物のトレードオフがある」3 条件が揃ったときだけ慎重に切る

ポイントは出力だ。問い詰めの結果、自分の頭の中にしかなかった暗黙の前提が CONTEXT.md / ADR という外部ファイルに書き出される。要約とは逆で、情報を削るのではなく、曖昧さを潰して判断の根拠を足していく。

なぜこの 2 つが噛み合うのか

ここまで来ると、組み合わせる理由は明白だ。一方の弱点が、もう一方の出力でちょうど埋まる。

subagent 単体	grill-with-docs を通すと
持っている文脈	メインの暗黙の前提を知らない	CONTEXT.md に前提が明文化済み
曖昧な用語	各自の解釈で勝手に埋める	用語集で定義が一意に固定済み
設計判断	指示になければ無視 or 独断	ADR にトレードオフごと記録済み
並列で 3 つ	詰めの甘い実装が 3 つ＋手戻り	同じ前提に沿った実装が 3 つ

subagent が欲しいのは「実装詳細を持たない、曖昧さのない共有文脈」だ。そして grill-with-docs が吐き出す

CONTEXT.md

は、まさに 実装詳細を持たない用語集 として設計されている。狙ったわけではないだろうが、出力の形が subagent の入力要件にぴったり一致している。

逆方向も成り立つ。grill-with-docs で文脈を研いでも、「で、この研いだ文脈を誰が使うのか」が宙に浮きがちだ。そこに subagent が 並列の実装の受け手 として収まる。研いだ文脈を、複数の subagent が同じ前提を共有しながら並列で消化していく。

あなた
  │  /grill 1234     ← 暗黙の前提を問い詰めて CONTEXT.md / ADR に外部化
  ▼
CONTEXT.md / ADR（曖昧さのない共有文脈）
  │  この CONTEXT.md を参照させて委任
  ├─▶ subagent A ─┐
  ├─▶ subagent B ─┼─ 同じ前提を共有したまま並列実装
  └─▶ subagent C ─┘

実際のフロー

順番が大事だ。研いでから、並列に流す。

— worktree を切る前に計画を問い詰め、用語・境界・トレードオフを
```
/grill
```
で研ぐ
```
CONTEXT.md
```
/ ADR に書き出す。ここに一番時間をかける
worktree で分離する— 研いだ文脈を持って作業を物理分離する（前回の記事の構成）
subagent に委任する— 指示の本体は書かず、「
```
CONTEXT.md
```
と該当 ADR を読んでから実装せよ」と参照させる。subagent は曖昧さを埋める必要がなく、実装に集中できる

skill 化するとこうなる。

# .claude/skills/grill.md
着手前に計画を問い詰め、CONTEXT.md / ADR を更新する。

# .claude/skills/delegate.md
CONTEXT.md と該当 ADR を読ませた上で、subagent に実装を委任する。

/grill

を飛ばして

/delegate

だけ叩くと、結局「察してくれない subagent に薄い指示を渡す」状態に逆戻りする。研ぐ工程を省くと、並列化したぶんだけ手戻りが増える。

まとめ

内容
subagent の性質	独立コンテキスト。察してくれない。渡した文脈が全て
その帰結	薄い指示 → 薄い成果。並列化はそれを増幅する
grill-with-docs の役割	暗黙の前提を問い詰めて CONTEXT.md / ADR に外部化する
噛み合う理由	subagent が欲しい「曖昧さのない共有文脈」を、grill-with-docs がそのまま吐き出す
順番	研いでから並列に流す。 /grill → worktree → subagent

subagent を並列で回す前に、やることがある。頭の中の暗黙の前提を、subagent が読める形に外部化すること だ。grill-with-docs はそのための道具で、出力される

CONTEXT.md

は subagent の入力要件にちょうど噛み合う。並列化の価値は、流す量ではなく、流す前に文脈をどれだけ研いだかで決まる。

参考

この記事は Vottia のプロダクト開発の中で得た知見をまとめたものです。

独立コンテキストの subagent には grill-with-docs を渡せ

추출된 키워드

원문

独立コンテキストの subagent には grill-with-docs を渡せ

TL;DR

subagent は「察してくれない」

grill-with-docs は暗黙の前提を外部化する

なぜこの 2 つが噛み合うのか

実際のフロー

まとめ

参考