Use Superpowers

grill-with-docs の使い方:AI にうなずかせず、まずあなたの計画を炙らせる

AI に要望を投げると、たいてい考え切れていない部分ごとそのままコードに焼き込まれる。grill-with-docs は逆をやる。コードを書く前に、プロジェクト自身の用語集とソースを使ってあなたを問い詰め、言葉が研ぎ澄まされるまで先へ進ませず、決まった用語と決定をその場で書き残していく。下は実際に走らせた記録だ――私がまったく見落としていた用語の衝突を、その場で捕まえた。

github.com/mattpocock/skills @ 6eeb81b

30 秒で要点 · 全部読む時間がないなら、ここだけ

  • 問題:AI は素直すぎる。生煮えの計画を渡す → コードを書く → あなたの曖昧さがプロジェクトごと出荷される。
  • grill-with-docs は逆をやる:あなたを問い詰める。プロジェクトの CONTEXT.md 用語集とソースを使い、計画の穴を一つずつ突く。
  • やり方:一度に一問、まず推奨案を出す。コードで調べられることは聞かない。用語が確定 → CONTEXT.md へ。覆しにくい決定 → ADR。
  • インストール:npx skills@latest add mattpocock/skills · 使う:「grill-with-docs で私の計画を炙ってくれ:<計画>」
  • 向いている:成熟したプロジェクトに複雑な機能を足すとき、しかも数語の意味が人によってずれているとき。やめておけ:空のリポジトリ / どうでもいい小改修 / コードを代わりに書かせるつもりのとき。

1. 素直な AI は、隠れた爆弾だ

AI とペアでコードを書くとき、一番危ないのは ほとんど反論してこない ことだ。

考え切れていない計画を投げる――「機能を足す:ユーザーが注文の中の何品かをキャンセルして、その分を返金できるようにしたい」――するとまばたき一つせず「了解です!」と、コードが流れ出す。だがその一文には、あなたが詰め切れていないことが山ほど詰まっている。それを一つも聞かない。「キャンセル」は発送前か発送後か。返金は誰の仕事か。コードがすでに「キャンセル」と呼んでいるものと同じものか。聞かずに、勝手に仮定して、その仮定をコードに焼き込む。

三週間後に気づく。「キャンセル」という一語が、プロダクトとコードとデータベースで三つの別物を指している。コードはぐちゃぐちゃだ。

AI が賢くないわけじゃない。助けたい一心 で、立ち止まってあなたに考えさせることをしないのだ。

grill-with-docs は逆をやる。AI にうなずくのをやめさせ、まずあなたの計画を炙る(grill は「問い詰める、火にかける」の意だ)。言葉が研ぎ澄まされるまで、先へは進ませない。

2. 仕組み:あなたのプロジェクトを覚えているインタビュー

機構を一言で言えば、プロジェクト自身の言葉と決定を使って、新しい計画を炙る。

具体的にはいくつかある(作者はこの挙動を二つの skill、grilling と domain-modeling に分割した。後述する)。

一度に一問、まず推奨案。 計画の決定木を枝ごとにたどり、どの問いも「私ならこうする、なぜなら……」から入る。二十項目の質問票を一気に投げつけたりしない。

コードで調べられることは聞かない。 ソースをさっと見れば分かることは、自分で調べる。

用語集で押さえる。 プロジェクトのルートにある CONTEXT.md がその物差しだ。定義と合わない言葉を口にすると、即座に止める:「用語集では『void』は X だが、あなたが言っているのは明らかに Y だ――どっちだ?」

曖昧な言葉は研がせる。 「アカウント」と言えば聞く:「Customer のことか、User のことか? この二つは別物だ。」

コードと突き合わせる。 機能がこう動くと主張すれば、コードを読んで確かめる。食い違えば指摘する:「コードは注文全体を void しているが、いまあなたは一部と言った――どっちが正しい?」

用語が決まったら、その場で CONTEXT.md へ書き込む。 ためたり「あとで」と言ったりしない。

覆しにくい決定だけが、ADR に値する。 ADR(アーキテクチャ決定記録)はけちだ。三つすべてが成り立つときだけ提案する――覆しにくい、文脈がないと後で人を混乱させる、本物の取捨選択の結果である。

これは要するに、ドメイン駆動設計の二つの本気の習慣――ユビキタス言語(ubiquitous language) と 決定の記録を残すこと ――を、逃げられない会話に畳み込んだものだ。

知っておく価値のある変更:実は二つの skill を組み合わせたものだ。 Matt は grill-with-docs を grilling(あの執拗なインタビュー)と domain-modeling(用語集 + ADR の規律)に分け、grill-with-docs 自身は 薄い殻 になった。本体はたった一行、「/grilling を走らせ、/domain-modeling を使え」だ。挙動は何も変わっていない。だが 半分ずつ単独で使える:炙られたいだけなら /grilling、用語集と ADR を整えたいだけなら /domain-modeling、両方欲しいなら grill-with-docs。

3. 始める:入れて、計画を渡す

入れる。 mattpocock/skills にある。公式の一行コマンドで、プロンプトが出たら grill-with-docs にチェックを入れる:

npx skills@latest add mattpocock/skills

さっきの分割のせいで、grill-with-docs は完全に動くのに grilling と domain-modeling を必要とする。だから 三つともチェックを入れる(または後ろの二つを直接使う)。すでにリポジトリを clone してあるなら、それらのディレクトリをプロジェクトの .claude/skills/ にコピーしてもいい。

渡す。 「X を実装して」はやめる。代わりにこう言う:

grill-with-docs で私の計画を炙ってくれ:<まだ詰め切れていない計画を入れる>

注意:これは disable-model-invocation が付いているので 自分から出てこない。名指しで呼ぶ(または /grill-with-docs と打つ)まで起動しない。そして覚悟しておく。同意はしない。問い始める。

最初の本物の結果は、たいていその 最初の問い だ。分かっていたつもりが、一問されただけで、分かっていなかったと気づく。下は私が実際に走らせた記録だ。

4. 実際の炙りを見る

炙らせるための小さなプロジェクトを用意し、わざと罠を仕込んだ。プロジェクトにはすでに CONTEXT.md があった:

**Cancellation**:
An order is voided in full before shipping; stock returns to inventory as-is. No refund flow is involved.
_Avoid_: Refund, Return

src/orders.ts のコードもまっすぐだ。cancelOrder() は注文全体しか void せず、発送前だけ、金には一切触れない。

そこで例の計画を渡した(冒頭のあれだ):「ユーザーが注文の中の何品か(全部ではなく)をキャンセルして、その品の分を返金できるようにしたい。」

コードと用語集を読み、その第一声は「了解です」ではなかった:

始める前に、二つの用語の衝突を指摘しておく。

あなたの言う「何品かをキャンセルして返金」は、既存の二つの定義とぶつかる:

  1. CONTEXT.md は Cancellation = 注文全体の void + 返金フローなし と定義している。あなたが描いているのは部分的なキャンセルで、しかも返金付きだ――両方とも衝突する。
  2. 用語集の _Avoid_ リストは「Return」という語を明示的に排除している。

つまり、あなたが描いている動作には 対応する既存の語がない。先へ進む前に、この新しい概念に名前を付ける必要がある。

自分でも気づいていなかった。私の文の中の「キャンセル」と、プロジェクトですでに定義された Cancellation は、別物だったのだ。捕まえただけではない――コードまで読みに行った:

いまの cancelOrder は src/orders.ts:3 で status === "PLACED" の注文しか許していない。あなたの言う「何品かをキャンセル」は、発送前だけか、発送後も含むか?

私の推奨:発送前だけ。 発送後の返品はビジネス上は返品フローで、複雑さが一桁違う……まず発送前の経路を出荷しよう。境界が一番きれいだ。

私は「採用、発送前だけ」と答えた。すると、もっと大事なことをやった――名前のない概念に名前を付け、そのまま用語集に書き込んだ:

Partial Cancellation: before shipping, remove some (not all) line items from an order; the removed items’ stock returns to inventory. No refund flow involved. _Avoid_: Partial refund, Partial return, Item cancellation

これは口先だけでなく 本当に CONTEXT.md ファイルに書き込んだ。返金の半分は明確に押し戻した:「それは Billing の管轄だ――ここには書かない。」

境界の方へ炙り進めると、記録を残すべきか判断するために手を止め、そして 本当に ADR を生成した:

docs/adr/0001-partial-cancellation-no-refund.md に ADR を残した: 「Partial Cancellation は返金を発火させない。返金は完全に Billing 文脈に委ねる。……代替案は Ordering 内部で返金を発火させ、『キャンセル + 返金』を一つの不可分な操作にすることだったが、それを退けた。Ordering が Billing の内部に依存し、既存の文脈境界を壊してしまうからだ。」

一番見事なのは、その 次の問い だ。たった今自分が書いた ADR をそのまま引用してきた:

問い 3 / Billing はどうやって返金を知る? いまの cancelOrder はイベントを一切発していない(src/orders.ts:7)。

  • A. ドメインイベントを発し、Billing が購読して返金する。
  • B. Ordering が Billing の返金 API を直接呼ぶ。
  • C. 何も発せず、呼び出し側に配線させる。

私の推奨:A。 案 B は Ordering を Billing に直接依存させる――まさに ADR 0001 が退けたものだ。

このループを噛みしめてほしい。私に一語を研がせ → 用語集に書き込み → 境界の決定を ADR に記録し → その ADR を使って、後で境界を壊しかねない選択肢を塞いだ。たった今あなたと一緒に作った言葉を使って、その後の一手一手を守っている。 これが「あなたのプロジェクトを覚えているインタビュー」の意味だ。

5. こいつの気性:いつ使い、いつ無理に使わないか

頭がしゃきっとする道具だが、万能薬ではないし、いつでも正解でもない:

  • 炙る材料が要る。 CONTEXT.md とコードがあれば、押さえる材料も突き合わせる相手もある。まっさらな空リポジトリでも用語集をゼロから組んでくれる(それでも役には立つ)が、すでにある言葉で穴を突くほど鋭くはない。だから一番向くのは すでに育ったプロジェクトに足すとき だ。
  • 研ぐのは明晰さであって、コードではない。 炙り終えて手元に残るのは、研がれた用語、数本の ADR、ようやく考え抜いた計画だ――実装の山 ではない。コードを書くのは、はっきりしたあとの次の一歩。それを代わりにやってくれると期待するな。
  • どうでもいいことを炙るな。 ボタンの色、使い捨てのフィールド――無理に流れに乗せれば、律儀に付き合ってくれるが、純粋な無駄だ。価値があるのは、曖昧な一語が果てしない災いを生む場所 だ:ドメイン概念、文脈境界、いくつかの考えが絡まりやすいところ。蚊に大ハンマー:蚊は無事、あなたは疲れる。
  • ADR がけちなのは欠点ではなく利点だ、嫌がるな。 三つすべてが当たるときだけ記録する:覆しにくい、後で混乱させる、本物の取捨選択。「もっと記録すればいいのに」と思ったときは自問しろ。本当に記録が要るのか、それとも完璧に揃えた儀式感が欲しいだけか。ADR は多いほど良いのではない。記録すべきものを記録するのが良いのだ。

一言でいえば:成熟したプロジェクトに複雑な機能を足すとき、しかも「言葉の意味が人によってずれている」という引っかかりがあるとき――オンにしろ。 そこが主戦場だ。

6. チートシート

インストール：npx skills@latest add mattpocock/skills   # プロンプトで grill-with-docs にチェック
炙る：AI に「grill-with-docs で私の計画を炙ってくれ：<計画>」と言う

やること：
  一度に一問、まず推奨案を出す
  コードで調べられることは聞かない
  CONTEXT.md 用語集で押さえる。語が合わなければ止める
  曖昧な語を研がせる（「アカウント」= Customer か User か？）
  コードと突き合わせ、食い違いを指摘する
  用語が確定 -> その場で CONTEXT.md へ書き込む（用語集、実装詳細は入れない）
  覆しにくい決定 -> ADR（docs/adr/、三基準すべて当たるときだけ）

CONTEXT.md：用語集だけ ―― 各語につき一、二行、使うべき語 + _Avoid_ 避けるべき語
ADR の三基準：覆しにくい + 文脈がないと混乱する + 本物の取捨選択（一つ欠けたら記録しない）

向いている：成熟したプロジェクトに複雑な機能を足し、「言葉の意味が人によってずれている」とき
やめておけ：空のリポジトリ / どうでもいい小改修 / コードを代わりに書かせるつもりのとき

7. もっと知る

  • ソース:grill-with-docs(MIT)、それと分割された grilling と domain-modeling。用語集と ADR のフォーマット説明は今は domain-modeling にある:CONTEXT.md フォーマット、ADR フォーマット――どちらも一読の価値がある。
  • もっと深掘りしたいなら、ドメイン駆動設計(DDD)の ユビキタス言語(ubiquitous language) と ADR(Architecture Decision Record、アーキテクチャ決定記録) を調べてほしい――grill-with-docs はその二つを手軽にやれるようにした軽い殻だ。
  • この「角度を変えて AI と協働する」遊び方が気に入ったら、前回は caveman(AI を黙らせ、要点だけ言わせる)を解剖した――ちょうど対になる:一方は無駄話を削らせ、もう一方は痛い問いを投げさせる。このシリーズで Matt のリポジトリの他の skill も順に解剖していく。

この記事は usesuperpowers.com のオリジナル解説で、扱っている grill-with-docs skill は mattpocock/skills(source_commit: 6eeb81b)に由来し、その MIT ライセンスに従う。本文中の炙りの過程は実際に走らせた記録だ(無関係な細部は省いた)。引用した原作のルールの著作権は原作者に帰属する。解説・デモ・文章はすべて当サイトのオリジナルだ。

バージョンについて:本記事は 6eeb81b に基づく。このバージョンで Matt は単一だった grill-with-docs を grilling + domain-modeling の二つの skill に分け、grill-with-docs を両者を組み合わせる入口にした。解説した挙動と上の実際の炙りはどちらも影響を受けない。「半分ずつ単独で使える」という層が一つ増えただけだ。