Grill-with-docsは文字通り「文書を添えて徹底的に問い詰める」ことです。AIが計画の隙間を執拗に質問するだけでなく、会話中に確定した用語はCONTEXT.mdに、元に戻すのが難しい設計決定はADR（Architecture Decision Record、アーキテクチャ決定記録）に残します。
この違いが重要な理由は簡単です。長い設計会話が終わったとき、人は結論を覚えているものの、次のAIセッションはその会話を知りません。コードには「何を作ったか」は残っても、「なぜこの用語を選んだのか」「なぜ他の選択肢を捨てたのか」はよく見えません。そうなると、次のセッションで同じ質問を繰り返したり、意図的に選択した構造を誤って元に戻したりする可能性があります。
Matt Pocockのgrill-with-docsは、この断絶を解決しようとする小さなオーケストレーションスキルです。この記事では、実際のSKILL.mdとともに呼び出される2つのスキルを詳しく見て、以前取り上げたGrill-meと何が違うのか、どのような文書がいつ作成されるのか、実務でどこまで信頼して使うべきなのかをまとめます。
驚くべきことに本体は7行だけだ
Skills.shで公開されているgrill-with-docsのSKILL.mdは、説明を含めて7行です。核心的な指示は1文です。
grillingとdomain-modelingスキルをそれぞれ呼び出せ。
つまり、このスキルは質問法と文書作成法を改めて長く定義しません。すでに分かれている2つの能力を一度にオンにするユーザー呼び出し用オーケストレーターです。
- grilling: 計画を意思決定ツリーに変換し、現在答えられる質問をラウンドごとに尋ねます。
- domain-modeling: 会話の用語をプロジェクトの共有言語と比較し、確定した用語と重要な決定を文書に反映します。
原文にはdisable-model-invocation: trueも含まれています。これは、モデルが状況を見て自動的にこのスキルを選択するのではなく、ユーザーが明示的に呼び出すフローを意図した設定です。一方、内部のgrillingとdomain-modelingは、複数の上位ワークフローが再利用できる下位ルールです。
この構造は、スキル設計自体にも興味深いメッセージを与えます。1つの巨大なSKILL.mdにすべての行動をコピーすると、ルールが簡単に分岐します。小さなスキルを組み合わせれば、質問方法が改善されたときにgrillingだけを修正し、用語管理方法が変わったときにdomain-modelingだけを修正できます。
図: 7行のオーケストレーターが質問と文書化の2つのルールを結合する。公式リポジトリのgrill-with-docsに基づいて再構成。
最初のエンジン: 計画を意思決定ツリーに変換する
grillingは計画を平坦な質問リストではなく、意思決定ツリーとして捉えます。上位の決定が定まって初めて意味を持つ下位の質問を連結し、先行条件が解決された質問だけを現在のラウンドのFrontierとして取り出します。
例えば、「注文キャンセル機能を作成する」という計画があるとします。すぐにAPIパスやデータベースフィールドから決めると、重要な前提を見落とす可能性があります。まず、次のような上位の決定を確認する必要があります。
- 注文全体のみキャンセルできるのか、品目の一部もキャンセルできるのか？
- 決済承認前のキャンセルと払い戻し後のキャンセルを同じ状態と見なすのか？
- 配送が開始された後はキャンセルなのか、返品なのか？
- 顧客センターによる強制キャンセルと顧客による一般キャンセルでは、権限と監査記録がどのように異なるのか？
ユーザーの回答が出ると、次のFrontierが開きます。そこで初めて状態遷移、イベント名、API境界、テストシナリオを具体化できます。まだ開いている上位の質問に依存する下位の質問は次のラウンドに延期します。
この過程で事実確認と決定も分離します。既存のコードが部分キャンセルをサポートしているか、現在のイベント名が何かは、エージェントがリポジトリで調査すべき事実です。部分キャンセルを製品ポリシーとして許可するかどうかは、ユーザーが下すべき決定です。スキルはユーザーにファイルを代わりに探させませんが、組織の価値判断までAIが静かに代行することもありません。
2番目のエンジン: 会話をプロジェクトの共有言語と比較する
domain-modelingは、質問を多く作成するツールではなく、質問の言葉を鋭くするルールです。ユーザーが「アカウント」「キャンセル」「顧客」のように範囲が広かったり、複数の意味で使われる言葉を使用すると、既存のCONTEXT.mdと比較します。
例えば、プロジェクト用語集でCancellationを「決済承認前に注文を撤回すること」と定義しているのに、会話では配送後の払い戻しまでキャンセルと呼ぶ場合、その衝突をすぐに明らかにします。「既存の用語集のCancellationと今話した動作は異なりますが、後者はReturnまたはRefundのどちらの概念ですか？」のように尋ねる形です。
ここでCONTEXT.mdは実装仕様ではありません。原文は実装の詳細を含めず、プロジェクトドメインの用語集としてのみ使用するよう強調しています。良い項目は短いです。
## Language
**Order**:
고객이 구매 의사를 확정해 생성한 거래 단위.
_Avoid_: Purchase, transaction
**Cancellation**:
결제 승인 전에 Order를 철회하는 행위.
_Avoid_: Refund, return複数の単語が同じ概念を指す場合は標準用語を1つ選び、避けるべき同義語はAvoidに記載します。一般的なプログラミング用語ではなく、当該プロジェクトの業務を理解するのに必要な言葉だけを盛り込みます。
単一ドメインリポジトリは通常、ルートのCONTEXT.md1つで十分です。注文、決済、配送のように境界が明確な複数のコンテキストがある場合は、ルートのCONTEXT-MAP.mdが各コンテキストの文書位置と関係を指し示す構造を使用します。ファイルは事前に空のシェルとして作成せず、実際に確定して記録する内容が生じたときに生成します。
すべての決定をADRとして残すわけではない
ADRはArchitecture Decision Recordの略で、後でコードを見た人が「なぜこうなったのか？」と尋ねるような設計決定を記録する文書です。Grill-with-docsは会話中に出た結論をすべてADRとして積み上げません。次の3つの条件をすべて満たす場合にのみ提案します。
| 条件 | 確認する質問 | 記録しなくてもよい例 |
| — | — | — |
| 元に戻すのが難しい | 後で変更するコストが大きいか？ | 簡単に交換できる小さなユーティリティの選択 |
| 背景なしでは驚く | 将来の開発者が理由を疑問に思うか？ | エコシステムの明白なデフォルト設定 |
| 実際のトレードオフ | 合理的な代替案の中から理由があって1つを選んだか？ | 選択肢が事実上1つしかない場合 |
例えば、「注文と決済は同期HTTPではなくドメインイベントで連携する」という決定は、障害隔離と一貫性遅延というトレードオフがあり、変更コストも大きいです。将来の開発者が直接呼び出しに変更したいと思う可能性があるため、ADR候補です。
一方、変数名1つ、小さなライブラリ1つ、簡単に元に戻せるフォーマット設定までADRにすると、重要な決定が文書の山に埋もれてしまいます。原文テンプレートは驚くほど短く、タイトルと「何をなぜ決定したのか」を説明する1〜3文だけでも十分だと考えられています。考慮した代替案、結果、状態は、実際に価値がある場合にのみ選択的に追加します。
図: 用語はCONTEXT.mdに、元に戻すのが難しく、背景なしでは驚きがあり、実際のトレードオフがある決定のみADRに記録する。domain-modeling原文に基づいて再構成。
Grill-meと何が違うのか
2つのスキルは競合関係ではありません。grill-with-docsがgrillingを内部で呼び出すため、質問方式の根幹は同じです。違いは、会話が終わった後に何が残るかにあります。
| 区分 | Grill-me | Grill-with-docs |
| — | — | — |
| 主な対象 | 一般的な計画・アイデア・意思決定 | 実際のコードベースの設計とドメインモデル |
| 質問方式 | 意思決定ツリーとFrontier | 同じgrilling方式 |
| コード対照 | 必要な事実調査 | 現在のコードと用語説明が衝突するか積極的に確認 |
| 共有言語 | 会話の中で合意 | 確定した用語をCONTEXT.mdに即時反映 |
| 決定記録 | 別途文書化規則なし | 条件を満たす決定のみADRとして提案 |
| 適切な状況 | 製品アイデア、購入、運用計画など | 長く維持するコードベースの設計変更 |
一回限りの計画を検証したり、まだリポジトリがないアイデアであればGrill-meだけで十分かもしれません。逆に、複数の人が長く管理するコードベースで、用語と設計理由が次のセッションにも残る必要がある場合は、Grill-with-docsの文書化規則が意味を持ちます。
1セッションは実際にどのように流れるか
注文キャンセル機能を例にとると、全体の流れは次のように整理できます。
- エージェントがリポジトリの既存コード、CONTEXT.md、CONTEXT-MAP.md、ADRを読み込みます。
- 計画を意思決定ツリーに変換し、先行条件が解決された質問を1つのラウンドにまとめます。
- 「キャンセル」のように曖昧な用語が既存の用語集と衝突する場合、直ちに正確な境界を尋ねます。
- 部分キャンセル、払い戻し、返品のような具体的な例外シナリオでモデルの境界を圧迫します。
- 用語が確定したら、該当するCONTEXT.mdをその場で更新します。
- 元に戻すのが難しく、背景なしでは驚きがあり、実際の代替案を比較した決定のみADRとして残すか提案します。
- 質問ツリーのFrontierが空になり、共有理解に達しても、ユーザーが確認するまでは実装を開始しません。
重要な点は、文書が議事録のように最後にまとめて作成されるのではないということです。用語が確定した瞬間に用語集に反映し、ADRの条件が満たされた瞬間に記録の可否を判断します。こうすることで、後のラウンドの質問も、たった今定めた言語を使用するようになります。
インストールと呼び出し
Skills.shページでは、次のインストールコマンドが案内されています。
npx skills add https://github.com/mattpocock/skills --skill grill-with-docsリポジトリのREADMEでは、Codexや他のエージェントで次の形式も案内されています。
npx skills@latest add mattpocock/skills2番目の方法は、インストールするスキルと対象エージェントを選択するフローです。リポジトリは、最初に一度setup-matt-pocock-skillsを実行して、文書の位置やイシュートラッカーなどのプロジェクト設定を決定するよう案内しています。
呼び出す際は、計画と文書範囲を一緒に与えるのが良いでしょう。
이 주문 취소 설계를 grill-with-docs로 검토해줘.
현재 코드와 CONTEXT.md를 먼저 확인하고,
용어가 확정되면 glossary에 반영해줘.
ADR은 세 가지 조건을 모두 만족할 때만 제안하고,
합의 전에는 구현하지 마.インストールコマンドは、外部リポジトリのコードをプロジェクトに取り込む作業です。実行前に現在のSKILL.md、一緒に呼び出される下位スキル、およびライセンスを確認し、組織のリポジトリでは変更内容をコードレビューの対象として扱う方が安全です。このリポジトリはMITライセンスで公開されていますが、ライセンスがセキュリティ検証を意味するわけではありません。
利点と限界
最大の利点は、設計会話が次のセッションの入力として残ることです。標準用語が生まれると、変数、関数、ファイル、説明で同じ言葉を使う可能性が高まります。ADRは、意図的に選択した構造を次の開発者が「不必要な複雑さ」と誤解して元に戻すことを減らします。
また、本体が小さな組み合わせスキルであるため、再利用の境界が明確です。質問規則と文書規則を別々に改善でき、他のワークフローも同じgrillingまたはdomain-modelingを呼び出すことができます。
しかし、自動的に良いドメインモデルを保証するわけではありません。誤った前提をユーザーが確定すると、短く一貫した用語集に間違った概念が残る可能性があります。既存のコードがすでに業務規則と食い違っている場合、「コードと会話が異なる」という事実だけではどちらが正しいかを決定できません。この場合は、ドメイン専門家、運用データ、実際のポリシーをさらに確認する必要があります。
文書を更新する権限も注意が必要です。単にアイデアを探索する段階で共有リポジトリのCONTEXT.mdをすぐに変更すると、まだ合意されていない用語が公式言語のように固まってしまう可能性があります。チーム環境では、変更内容をdiffで検討し、ADRの提案と実際の反映の承認境界を明確に設ける方が良いでしょう。
最後に、この方式は国際標準やすべてのエージェントの組み込み機能ではありません。grill-with-docs、CONTEXT.md形式、および3つのADRゲートは、Matt Pocockリポジトリが選択したプロジェクト規則です。有用なパターンですが、組織に既存のADRテンプレート、ドメイン文書の位置、承認手順がある場合は、その体系に合わせて調整する必要があります。
まとめ
Grill-with-docsの核心は、文書を多く作成することではありません。質問で曖昧な設計を絞り込み、再利用する価値のある知識だけを最小限の文書として残すことです。
記憶すべき構造は3段階です。grillingが意思決定ツリーの空白を見つけ、domain-modelingがコードと用語の衝突を明らかにし、確定した結果は用語集または厳格なゲートを通過したADRへと続きます。そして、すべての質問が終わった後も、ユーザーが共有理解を確認するまでは実装を開始しません。
以前のGrill-meが「思考の空白を徹底的に問う方法」であったとすれば、Grill-with-docsは一歩進んでいます。次のセッションが同じ質問を繰り返さないように、今日の合意をプロジェクトが読み取れる記憶に変えます。
コメントを残す