grill-with-docs

grill-with-docs skill の概要

grill-with-docs は、リポジトリ内にすでにある言葉づかいと意思決定を踏まえて、設計を“圧”にかけて検証したいチーム向けの、計画・ドキュメント作成用スキルです。CONTEXT.md や ADR と用語をきちんと揃えたまま進めたい Technical Writing、プロダクト志向のエンジニアリング、AI 支援のアーキテクチャ検討に特に向いています。曖昧な“プロンプトだけ”の表現へ流れていくのを防ぎやすいのが強みです。

基本の役割はシンプルです。ユーザーに一問一答で質問し、答えの候補を提示し、質問がソースから解決できるならコードベースやドキュメントを参照します。そのため、grill-with-docs skill は、実際のリスクが用語の不一致、未文書化の前提、古い意思決定記録にある場合、単なるブレスト用プロンプトよりも役立ちます。

grill-with-docs が他と違う理由

この skill は、単なる会話ではなく、ドメイン理解を軸にしています。既存のコンテキストファイルを確認し、ADR を読み、判断が固まるたびにドキュメントを更新するよう促してくれるため、grill-with-docs for Technical Writing のようなドキュメント重視のワークフローと相性が良いです。

最適な利用シーン

次のような場面で grill-with-docs を使うと効果的です。

• 既存のドメインモデルに照らして計画を検証したい
• プロジェクト内で使う用語を厳密に選びたい
• 意思決定を、その場で記録していきたい
• 実装前に、ドラフトを確立済みドキュメントと揃えておきたい

向いていないケース

短い要約が欲しいだけ、整った仕様書が欲しいだけ、あるいはリポジトリを前提にしない自由な発想だけが目的なら、この skill は通常のプロンプトより遅く感じるはずです。価値が出るのは、厳密な質問設計とドキュメントに基づく確認があるときです。

grill-with-docs skill の使い方

grill-with-docs をインストールする

リポジトリ標準の skill manager を使って、grill-with-docs skill を skills ディレクトリにインストールし、その後で対象プロジェクトのコンテキストで skill ファイルを開きます。基本のインストール手順は次の通りです。

npx skills add mattpocock/skills --skill grill-with-docs

これは grill-with-docs install の開始点として扱い、実際に使う agent 環境で skill が利用可能か必ず確認してください。

最初の入力を正しく渡す

この skill は、最初のメッセージに次の要素が入っていると最も効果を発揮します。

• 計画したいゴール
• システム名または機能名
• 重要な既知の用語
• 解決したい意思決定の境界

弱いプロンプトの例: 「この機能の設計を手伝って」
強いプロンプトの例: 「現在の請求ドメインに照らして、この機能案を grill-with-docs で精査してください。subscription period の適切な用語、データ形、そしてドキュメント化すべき意思決定があれば、docs を書く前に知りたいです。」

まず読むべきファイル

grill-with-docs usage では、まず次のファイルから確認してください。

• SKILL.md でインタビューの振る舞いとワークフローを確認する
• CONTEXT.md または CONTEXT-MAP.md で現在のドメインモデルを確認する
• docs/adr/ で過去の意思決定を確認する
• ファイルを新規作成または更新する必要があるなら ADR-FORMAT.md と CONTEXT-FORMAT.md を確認する

これらのファイルを読むことで、リポジトリから推論できることと、明示的に書き残すべきことの境界が見えてきます。

出力をよくするワークフロー

skill は次のループで使うと効果的です。

1. 具体的な計画、または粗いドラフトを渡す
2. skill に一問ずつ質問させる
3. repo に根ざした、できるだけ具体的な情報で答える
4. 質問がファイルから解けるなら、コードベース探索を許可する
5. 用語と確定事項をコンテキストや ADR の नोटに残す

実務上の重要ポイントは、「名前が必要なのか」と「意思決定が必要なのか」を分けることです。そうすると grill の焦点がぶれず、不要な ADR まで増やさずに済みます。

grill-with-docs skill の FAQ

grill-with-docs はドキュメントチーム専用ですか？

いいえ。既存のドメイン用語に計画を合わせる必要があるなら、どのチームでも役立ちます。特に、product engineering、platform work、または grill-with-docs for Technical Writing のように、言い回しや構成が下流の分かりやすさに影響するワークフローでは有効です。

通常のプロンプトと何が違いますか？

通常のプロンプトはアイデアを出せますが、grill-with-docs は前提を問い直し、リポジトリを確認し、既存コンテキストに合わせて用語を詰めるために設計されています。そのぶん、名称の衝突や、コードベースと噛み合わないドキュメントが生まれるリスクを下げられます。

使うのに成熟した docs 基盤は必要ですか？

必要ありません。ただし、CONTEXT.md と ADR がすでにあると、最も力を発揮します。まだ無くても、意思決定が見えてきた段階で、必要なものを段階的に定義していく手助けはできます。

使わないほうがいいのはいつですか？

純粋に探索的な作業、リポジトリに意味のあるドメインコンテキストがない場合、あるいは構造化されたインタビューよりも、即答の一発回答が必要な場合は避けてください。

grill-with-docs skill を改善する方法

より良い意思決定材料を渡す

品質を最も大きく上げるのは、skill に対して狭く、意思決定に直結するプロンプトを渡すことです。機能名、その機能が触るシステムの範囲、そして解消したい曖昧さを入れてください。例: 「会計コンテキストでは、これを invoice、billing record、charge のどれと呼ぶべきですか。また、その決定はどこに置くべきですか？」

早い段階で repo の根拠を与える

関連しそうなファイルが分かっているなら、最初から伝えてください。CONTEXT.md、特定の ADR、あるいは src/billing/ のようなフォルダを指すだけで、skill は一般的な質問を減らし、より実用的な質問をしやすくなります。grill-with-docs usage で特に重要なのはここです。というのも、この skill は既存の用語と構造に対して計画を比較できるときに最も強いからです。

よくある失敗パターンに注意する

最大の失敗パターンは、ドメインの指定が弱すぎてインタビューが抽象論のまま続くことです。もう一つは、言語モデルが適切な用語を持つ前に実装の話を求めてしまうことです。最初の出力が広すぎると感じたら、意思決定をより狭い言い方に言い換え、最後に確定した分岐から続けるよう skill に依頼してください。

1回目のあとに反復する

最初のラウンドが終わったら、得られた答えを次の3つのどれかに落とし込みます。整理済みの用語集エントリ、短い ADR、または改訂版の実装ブリーフです。そのうえで、まだ残っている未解決の論点に対して grill-with-docs をもう一度回します。2回目のパスこそ、この skill が最も効きやすい段階です。用語と境界がすでにクリアになっているからです。