実装前に設計を徹底的にインタビューし、要件を明確にするためのスキル `/grill-me`
コーディングエージェントの自律性が向上し、並行して複数のエージェントを動かすことが当たり前になってきた今、エージェントの動きを逐一監視することは現実的ではなくなっています。そのため実装前に人間と AI の間で共通理解を形成することが重要になっています。この記事では、実装前の設計フェーズで要件を明確にし、人間と AI の間で共通理解を形成するためのスキル `/grill-me` について紹介します。
コーディングエージェントが登場した当初はコマンドの実行やコードの生成のたびに承認し、間違った方向に進みそうになれば随時介入するような、つきっきりで監視する手法が一般的であったと記憶しています。しかし最近では AI モデル自身の性能の向上やハーネスエンジニアリングの発展により、エージェントが自律的にタスクを完了できるようになっています。エージェントの自律性の向上は、ユーザーがエージェントの動きを逐一監視する必要がなくなるためさらなる生産性の向上につながります。今日では複数のタスクを並行して実行したり、大規模なワークフローを構築するような動かし方が当たり前の日常になってきました。
複数のエージェントを並行して動かすことが当たり前になってきた今、エージェントの動きを逐一監視することは現実的ではなくなっています。以前までは多少指示に曖昧さが残っていたとしても、実装フェーズの動きを見ていれば認識のズレを早期に発見できていました。物理的にエージェントの動きを監視することができなくなった今、認識のズレを発見できるのはエージェントのタスクが完了した後になってしまいます。エージェントのタスクが完了するまで認識のズレに気づけない場合、そもそも要求が満たされなければすべてやり直しになってしまいます。要求が満たされている場合でも、コードのアーキテクチャが不適切だったりコードの品質が低かったりすれば、コードレビューの段階で大幅な修正が必要になってしまいます。そのため今日の開発では、実装前の設計フェーズで要件を明確にし、人間と AI の間で共通理解を形成することが重要になっています。
人間と AI の間で共通理解を形成するためには、はじめのプロンプトで漏れなく要求や設計の意図を伝える必要があるのですが、これを実際に行うのは思ったよりも難しいものです。第一に暗黙知の問題があります。人間は自分の頭の中である程度の前提知識を共有していることを前提に物事を考える傾向があるため、要求や設計の意図を伝える際に、無意識のうちに重要な情報を省略してしまうことがあります。同じチームで働いている人間同士であれば、ある程度の前提知識が共有されているため、暗黙知の問題はあまり大きな問題にはならないかもしれません。しかし AI は(AGENTS.md のようなメモリ機能はあるものの)毎回新しいプロンプトを受け取るたびにゼロから理解を構築する必要があるため、暗黙知の問題は非常に大きな問題になります。
第二に、要求や設計の意図を言語化すること自体が難しい場合もあります。特に複雑なシステムや抽象的な概念を扱う場合、言葉だけで正確に伝えることが難しいことがあります。第三に要件がまだ固まっていない場合もあるでしょう。自分の頭の中ではある程度のイメージができているものの、実際に言葉にしてみると、設計に漏れがあったり、矛盾していたりすることに気づくことがあります。
実装に入る前に設計を明確にするための手法として、多くのハーネスには「プランモード」といった機能が備わっています。プランモードでは、エージェントは決してコードを変更することなくコードベースを徹底的に調査し、コードベースや既存のコードの設計を理解したうえでユーザーに対して変更内容の方針や手順をまとめて計画を提示します。計画を提示するうえで不明瞭な点があればユーザーに質問を行い、ユーザーの回答をもとに計画を修正します。プランモードでは実際にコードの実装を始める前に意図のすり合わせを行うことができるため、認識のズレを早期に発見することができます。また要件がまだ固まっていない場合でも、設計を考える壁打ち相手としてプランモードを活用することができます。プランモードでは複数の選択肢を提示してくれることも多いため、選択肢を比較・議論しながら設計を考えることができます。
しかし、プランモードには欠点も指摘されています。問題の本筋は設計の全体像が一度にまとめて提示されることです。提示された計画は全体像ではもっともらしく見える分、全体を分割することなくつい「OK」と承認してしまいがちです。その結果発生するのは計画の主導権が奪われるという問題です。設計を考える際に全体像が完了するまで AI は一気通貫に突き進めてしまうため、人間と AI が議論しながら進めることが難しくなります。
このようなプランモードの欠点を克服するために Matt Pocock 氏が作成したのが /grill-me スキルです。/grill-me は計画や設計についてユーザーを徹底的にインタビューし、設計ツリーの各分岐を解決しながら共通理解に到達するまで質問を続けるスキルです。このスキルでは AI が質問してユーザーが答える、という形式を取っているので設計の主導権は人間側にあるというのが大きな特徴です。設計ツリーの各分岐を 1 つずつ解決していくため、ユーザーはツリー状の末端ノードのレベルまで設計の詳細を詰めることができます。
grill という英単語は「（肉などを）焼く」という意味の他に、「厳しく尋問する」という意味もあります。
この記事では /grill-me スキルの概要と実際の使い方について紹介します。
/grill-me スキルとは
/grill-me は Agent Skills として提供されています。実際に /grill-me スキルを使用したい場合はコマンドとして明示的に呼び出す方法が一般的でしょう。
/grill-me [設計のテーマ]grill-me スキルの特徴的な点は、スキルの内容自体はわずか 3 行しかないという点です。スキルの内容を日本語に訳すと以下のようになります。
この計画のあらゆる側面について、私たちが共通理解に達するまで徹底的に質問してください。設計ツリーの各枝をたどり、決定事項間の依存関係を 1 つずつ解決していきましょう。それぞれの質問に対して、あなたの推奨する回答を提示してください。
質問は 1 つずつしてください。
コードベースを調べることで疑問が解決できるのであれば、コードベースを調べてください。要点は「この計画のあらゆる側面について、私たちが共通理解に達するまで徹底的に質問してください。設計ツリーの各枝をたどり、決定事項間の依存関係を 1 つずつ解決していきましょう」の一文です。設計のテーマにもよりますが、おおよそ 10 ~ 50 個程度の質問がされて徹底的に掘り下げられていきます。プランモードを使用するよりも遥かに長い時間をかけて、かつ人間の体力も消耗するのですが、あらかじめ設計を細部まで詰めることができるため、実装フェーズでの認識のズレを大幅に減らし、結果的には早く実装を完了させることができるようになるでしょう。
設計ツリーとは、書籍デザインのためのデザインに由来する概念です。設計者は何か 1 つの設計判断を下すと、その判断に依存する複数の設計判断を下す必要が出てきます。さらに重要なのはそれぞれのノードでは別の道を選ぶことができたという点です。木構造になった設計空間を探索していくことで、設計の全体像を把握しながら、設計の詳細を詰めていくことができます。
/grill-me スキルを活かすうえで最も重要なことは、AI に設計を任せきりにするのではなく、人間側で設計の構成要素をある程度把握しておくことです。/grill-me スキルを使用した最も多い失敗パターンは人間が質問に対して受け身になりすぎてしまうことだと言われています。エージェントの質問に対して深く考えずに「OK」と答えるような態度は避けるべきです。人間が受動的すぎると、極端な失敗例では 540 個もの質問を浴びせられたり、重要度の低い細部に関する要求まで範囲を広げられてしまったりすることもあるようです。エージェントの質問に対してアクティブに、つまりどこに向かうかを決めたり、会話の方向性を調整するといった議論をリードするような振る舞いが求められます。これは面接ではなく、会話なのです。
あくまで自分の頭の中にある設計のイメージを AI と協力して言語化するためのツール、という位置づけで使用することを心がけましょう。結局、何も考えのないところから魔法のように設計が生まれてくることはないのです。
音楽はもう全部、頭の中で完成している。楽譜にするのは、ただ書き写すだけだ。- 映画『アマデウス』（1984）の中のモーツァルトの台詞
Matt 氏は /grill-me スキルをさらに発展させた /grill-with-docs スキルの使用を推奨しています。/grill-with-docs スキルは計画を既存のドキュメントと照らし合わせながら検証するスキルで、CONTEXT.md や ADR などのドキュメントを決定が固まるたびにその場で更新するというアプローチを取っています。CONTEXT.md はドメイン駆動開発に由来し、アプリケーションの境界領域内（=コンテキスト）で使用される共通言語を定義するためのドキュメントです。
実際に /grill-me スキルを使ってみる
それでは実際に /grill-me スキルを使ってみましょう。/grill-me スキルは GitHub リポジトリで公開されているため、直接コピーするか npx skills コマンドを使用してインストールできます。
npx skills add https://github.com/mattpocock/skills --skill grill-me/grill-me スキルを使用した設計を考える際のポイントは、質問の忠実度とスコープにあります。/grill-me スキルで回答できる質問は低忠実度な質問に限られています。低忠実度な質問は詳細なプロトタイプや画像がなくとも答えられる質問で、例えば「この画面の URL は何にすべきか？」といった質問があげられます。高忠実度な質問は詳細なプロトタイプや画像がないと答えられない質問で、たとえば「この画面のレイアウトはどうすべきか？」といった質問です。こうした問いは実際にプロトタイプを作ってみないと適切な判断が下せないためです。できる限り低忠実度な質問を得られるようにプロンプトを渡すようにすべきですが、どうしても高忠実度な質問が出てきてしまう場合もあるでしょう。そのような場合はハンドオフパターンを使用するべきとされています。これは、高忠実度な質問が出てきたら一旦 /grill-me スキルを終了させてプロトタイプセッションに移行するパターンです。プロトタイプを作成したうえで、再度 /grill-me スキルを呼び出し、作成したプロトタイプをもとに質問を続けます。
また設計のスコープも重要なポイントです。設計のスコープが広すぎると、高忠実度な質問が多くなってしまう傾向があります。さらに、コンテキストウィンドウの限界に達しやすくなるという問題もあります。コンテキストウィンドウの限界に達してしまうと、重要な情報を見落としたり、判断の精度が落ちてしまったりする可能性があります。巨大なスコープを扱う場合には、まずエージェントとともにタスクを分解してから、分解されたタスクごとに /grill-me スキルを使用するのが良いでしょう。
ここではカンバンアプリケーションにおいて「タスクの完了率や平均完了時間をダッシュボードに表示して開発生産性を計測する」という機能を実装することをテーマにして、/grill-me スキルを使用してみましょう。まずは以下のようなプロンプトを渡してみます。
/grill-me タスクの完了率や平均完了時間やボトルネックをダッシュボードに表示して開発生産性を計測する機能を実装したい。最初のプロンプトではあえてざっくりとした指示を出し、設計の詳細には踏み込まないことを意識しています。自分が思い描いた設計像から大きく外れてしまわないように、すでに具体化された設計部分を渡してしまう誘惑にかられてしまいがちです。例えば既にデータベースのテーブル設計や API のエンドポイントの設計が頭の中でできている場合、最初のプロンプトでそれらを渡してしまいたくなります。しかしそうしてしまうと、AI がよりよい解を見つける余地がなくなってしまいます。「API のエンドポイントを設計して」という指示を含めると、それ以前に Next.js の Server Components でデータを取得するほうが適切だった、という選択肢があったとしても、AI は API のエンドポイントを設計することに固執してしまうかもしれないのです。
なにかデザインされるものを指定するときには、どうやって達成するかではなく、どんな性質が必要かを伝えなさい。実装方法が制約として与えられていると、よりよい解が排除されてしまう。- 『デザインのためのデザイン』（フレデリック・P・ブルックス Jr. 著）
/grill-me スキルを呼び出すと、まずはコードベースの調査から始めます。データベースのスキーマや、既存のコードの構造を把握してからユーザーへの質問を開始します。1 つ目の質問は「計測のためのデータ記録方式はどうするか？」というものでした。「平均完了時間」「ボトルネック」を出すには、タスクの状態遷移を時系列で記録する必要があります。しかし既存のデータベースのスキーマにはそのためのテーブルが存在していません。どのようにデータを記録するかを決める必要がある、というのが質問の背景にある理由です。
エージェントは 3 つの選択肢と同時に、推奨される回答を提示してくれます。AI の推奨回答は「カラム移動履歴テーブルを追加」でした。推奨される回答を提示するのは、質問に対して「はい」とだけで変更できるようにして会話のスピードアップを図るためです。ただし何度も言うように、推奨される回答をそのまま受け入れるのではなく、質問に対してアクティブに答え設計の主導権を AI に渡さないようにしてください。
最終的には 18 回にわたる質問が徹底的に行われました。質問事項としては以下のようなものがありました。
- 「完了」をどう定義するか？
- 「ボトルネック」をどう算出・表示するか？
- ダッシュボードの集計範囲（スコープ）をどうするか？（ボード単位かプロジェクト単位か）
- 集計の対象期間（時間範囲フィルタ）をどうするか？
- グラフの描画手段をどうするか？
- 完了カラムから別カラムへ戻された（差し戻し）場合、どう扱うか？
すべての質問が完了したら、最終的な設計の全体像が提示されます。提示された仕様に問題がないかを確認し、問題がなければ実装フェーズに移ります。
実装フェーズに入る際に、コンテキストをリセットしてしまうのは失敗パターンとして定義されています。設計フェーズでの質問と回答のやりとりは、実装フェーズに入る際のコンテキストとして引き継がれるべきです。多くの設計判断が詰まったコンテキストは非常に価値の高い資産となります。コンテキストに余裕があれば、そのまま実装フェーズに入ることができます。コンテキストに余裕がなかったり、実装自体が大規模であったりする場合は、設計フェーズでのやりとりを /docs ディレクトリなどにドキュメントとして保存しておくのが良いでしょう。後のセッションで設計の内容を参照して進めることができます。設計を PRD（Product Requirements Document）にまとめるための /to-prd スキルも提供されているので、そちらを使用しても良いでしょう。
まとめ
- コーディングエージェントの自律性が向上し、並行して複数のエージェントを動かすことが当たり前になってきた今、エージェントの動きを逐一監視することは現実的ではなくなっている
- エージェントのタスクが完了するまで認識のズレに気づけない場合、タスクがやり直しになったり、コードレビューの段階で大幅な修正が必要になったりする可能性があるため、実装前の設計フェーズで要件を明確にし、人間と AI の間で共通理解を形成することが重要になっている
- 人間と AI の間で共通理解を形成するには、はじめのプロンプトで漏れなく要求や設計の意図を伝える必要がある。しかし暗黙知の問題や、言語化すること自体の難しさ、要件がまだ固まっていない場合があることなどから、実際に行うのは思ったよりも難しい
- 実装に入る前に設計を明確にするための手法として、多くのハーネスには「プランモード」といった機能が備わっているが、プランモードには設計の全体像が一度にまとめて提示されることによる、設計の主導権が奪われるという問題がある
- プランモードの欠点を克服するために Matt Pocock 氏が作成したのが
/grill-meスキル。/grill-meは計画や設計についてユーザーを徹底的にインタビューし、設計ツリーの各分岐を解決しながら共通理解に到達するまで質問を続ける。AI が質問してユーザーが答える形式を取っているので、設計の主導権は人間側にあるというのが大きな特徴 /grill-meスキルを活かすうえで最も重要なことは、AI に設計を任せきりにするのではなく、人間側で設計の構成要素をある程度把握しておくこと。エージェントの質問に対して深く考えずに「OK」と答えるような態度は避けるべきで、エージェントの質問に対してアクティブに、つまりどこに向かうかを決めたり、会話の方向性を調整するといった議論をリードするような振る舞いが求められる
