ask-matt

Matt に聞いてください

すべてのスキルを覚えているわけではないので、確認してください。

スキルの内容を説明したり、手順を省略するよう勧めたりする前に、そのスキルの SKILL.md を読んでください。ここに記載されている概要は、あくまで参考用です。

フローとは、スキルを通る経路です。ほとんどの経路は 1 つのメインフローに沿って進み、2 つの入り口がそこに合流します。それ以外は、単独で動作するか、その下層で動く用語レイヤーです。

1 つの任意の上流フロー

以下のフローは、利用可能なアプローチを示すものであり、このフォークの前提条件ではありません。承認済みの作業は、会話、仕様、課題、ドキュメント、またはリポジトリの証拠に基づく場合があります。フォークが所有する境界スキルは、実装方法と検証方法をそれぞれ独自に選択します。

主な流れ：アイデア → リリース

多くの作業がたどる道筋です。アイデアがあり、それを形にしたい場合に進みます。

1. /grill-with-docs は、インタビューを通じてアイデアを磨き上げます。作業ディレクトリで作業している場合は、いつでもここから始めてください。状態を保持し、学んだ内容を GLOSSARY.md と ADR に記録します。（作業ディレクトリがない場合は、代わりに /grill-me を使ってください。これは「スタンドアロン」の項で説明しています。どちらも同じ /grilling プリミティブを実行します。grill-with-docs は記録を残すため、記録を残せるリポジトリがある場合は、こちらのほうが適しています。）

2. 分岐：会話だけですべての疑問を解決できますか？ 実行可能な回答が必要な疑問（状態、ビジネスロジック、実際に見て確認する必要がある UI）がある場合は、両方向で /handoff を使って橋渡しし、プロトタイプを経由します（プロトタイプは専用のディレクトリに置かれますが、まさにそのための /handoff です。「フェーズの境界」を参照してください）。

   • /handoff で切り替えてから、そのファイルを対象に新しいセッションを開始します。
   • /prototype で使い捨てのコードを作成し、疑問に答えます。
   • /handoff で学んだ内容を戻し、元のアイデアのスレッドから参照します。

3. 分岐：複数セッションにまたがるビルドですか？

   • はい → /to-spec でスレッドを仕様書にまとめ、次に /to-tickets でトレーサーバレット形式のチケットに分割します。各チケットには、ブロックする依存関係を明記します。その後、次のどちらかの方法でチケットに取り組みます。
     • チケットごとに /implement を実行し、その間に毎回コンテキストを /clear でクリアします。ローカルトラッカーでは、.scratch/<feature>/issues/ 配下にチケットごとに1つのファイルを作成し、ブロッカーから手作業で順に取り組みます。実際のトラッカーでは、依存関係がネイティブのブロッキングリンクになるため、ブロッカーが完了したチケットを誰でも取得できます。各チケットは自己完結しているため、最後のチケットのコンテキストは破棄できます。
     • 仕様書全体に対して /implement-spec を1回実行します。チケットを タスクグラフとして読み込み、着手可能な フロンティアで実装サブエージェントを並列実行し、すべてを1つの 統合ブランチに取り込みます。各チケットを自分で進めるより、ビルドのオーケストレーションを行いたい場合に使ってください。
   • いいえ → このまま同じコンテキストウィンドウで /implement を実行します。

   どちらの方法でも、コードは /tdd（一度に1つのレッド・グリーンのスライス）を進めて構築し、差分を2つの軸（標準 + 仕様）でレビューする /code-review で締めくくります。/implement はチケットごとに両方を実行します。/implement-spec では各実装エージェントがそれぞれ /tdd を進め、統合ブランチ全体に対して /code-review を1回実行します。完全な仕様書を用意せず、具体的な振る舞いをテストファーストで実装したい場合は /tdd を単独で使ってください。固定された基準に照らしてブランチや PR をレビューしたい場合は、いつでも /code-review を単独で使えます。

   作業をプルリクエストとして提出するときは、/pr が本文を整えます。変更点を示す最小限のビジュアル、動作を示す変更前後の証拠、一方向または双方向のドアの判断を含めます。モデルから呼び出されるため、エージェントは PR を作成するときにいつでもこれを使います。

4. /retro で一連の流れを締めくくります。ビルドの後、特に問題が起きた場合に、セッションを振り返り、コードではなくエージェントの 環境に対する改善を提案します。対象は、ナビゲーションの手がかり、自動チェック、/code-review が適用するコーディング規約、ステアリングファイル、ツールなどです。機械的なミスは決定論的なチェックにし、判断を要する事項はコーディング規約にします。次のビルドは、より良い環境から始められます。

コンテキストの衛生管理

手順1〜3は途切れない1つのコンテキストウィンドウで進めます（/to-ticketsが終わるまで、圧縮したりクリアしたりしないでください）。そうすることで、掘り下げ、仕様、チケットがすべて同じ思考の流れを引き継ぎます。各/implementはチケットをもとに、新しいセッションで開始します。振り返る対象のセッション内で、クリアする前に/retroを実行してください。クリアした後に実行する場合は、そのセッションのログを指定してください。

この制限の目安は**スマートゾーン**です。これは、モデルが鋭い推論を保てるウィンドウ（最先端モデルで約15万トークン）を指します。/to-ticketsの前にセッションがこの上限に近づいた場合は、推論が鈍ったまま進めず、最も近いフェーズの境界で/compactを実行して続けてください（「フェーズの境界」を参照）。

導入経路

作業が発生する状況から始まり、メインフローに合流する経路です。

• バグやリクエストが積み上がっている → /triage。トリアージの各役割を通して課題を処理し、エージェントが対応できる課題を作成します。これを後から**/implement**が取り込みます。

  トリアージの対象は、自分で作成していない課題に限ります。バグ報告、寄せられた機能リクエストなど、未加工のまま届いたものが対象です。/to-ticketsが作成したチケットはすでにエージェントが対応できる状態なので、トリアージしないでください。

• 何かが壊れている → /diagnosing-bugs。一筋縄ではいかないバグに使います。ひと目では原因がわからないバグ、断続的に発生する不安定な問題、正常な状態の間に紛れ込んだリグレッションなどが対象です。まず短いフィードバックループ（そのバグで実際に失敗するコマンド1つ）を確立するまでは、原因を推測しません。その後、リグレッションテストを追加して修正します。修正が入ったら、同じセッション内で**/retroを実行し、バグを未然に防ぐには何ができたかを振り返ります。根本的な発見が、問題を確実に防ぐための適切な接点がないことなら、/improve-codebase-architecture**の出番です。

• 見通しの立たない大規模な取り組み：新規プロジェクトや、1つのセッションでは大きすぎる大規模な機能開発 → /wayfinder。ここで最も認知負荷の高いフローです。現在地から目的地までの道筋がまだ見えない場合は、イシュートラッカー上に意思決定チケットの共有マップを作成し、1つずつ解決していきます。霧が晴れて道筋が明らかになるまでは、成果物ではなく意思決定を生み出します。**/grill-with-docs**が1つのセッション内で扱えるアイデアを明確にするのに対し、Wayfinderは1つのセッションでは扱えないアイデアのためのものです。また、時間がかかり情報量も多いため、スコープが明確な機能には使わず、まさにこのような大規模な取り組みに限って使ってください。

  マップが明確になったら、実装はせず、引き継ぎます。メインフローの**/to-spec**に合流し、マップ上で関連付けられた意思決定を実装可能な計画にまとめてから、通常どおり/to-ticketsと/implementに進みます。マップから直接/implementに進むと、この整理を飛ばして関連する詳細が失われるため、取り組みが本当に小規模だとわかった場合に限り、そのまま/implementに進んでください。

コードベースの健全性

機能開発ではなく、保守作業です。

• /improve-codebase-architectureは、エージェントが扱いやすいコードベースを保つため、空き時間にいつでも実行できます。ここから改善の機会が見つかり、その中から1つ選ぶと、メインフローの/grill-with-docsに持ち込めるアイデアが生まれます。候補を見つけるのが調査であり、選んだ候補を設計する作業台が、以下の**/codebase-design**です。

下位にある語彙

ほかのスキルの下位で動作し、それぞれが語彙の唯一の信頼できる情報源となる、モデルから呼び出される2つのリファレンスです。プロセスではなく言葉が問題なら、直接参照してください。または、上位のスキルから参照させてください。

• /domain-modeling：プロジェクトのドメイン言語を磨きます。曖昧な用語に異議を唱えたり、複数の意味を持つ単語（「account」が3つの役割を担っている場合など）を整理したり、変更が難しい決定をADRとして記録したりします。これは、GLOSSARY.mdを明確な用語集に保つために/grill-with-docsが推進する実践です。
• **/codebase-design**は、モジュールの形を設計するためのディープモジュールの語彙（モジュール、インターフェース、深さ、継ぎ目、アダプター、レバレッジ、局所性）です。明確な継ぎ目の背後に、多くの振る舞いを小さなインターフェースで隠します。/tddと/improve-codebase-architectureはいずれもこの語彙を使います。

フェーズの境界

フェーズとは、セッション内の作業のまとまりです。たとえば、質問を重ねる工程、実装、QAなどです。その2つのフェーズの境界では、5つの選択肢があります。このマップ全体で最も判断が曖昧なのは、どれを選ぶかです。

• 続行：そのまま続けます。コストも損失もありません。
• /clear：次の作業に必要な情報がここに何もない場合、ウィンドウを空にします。
• /handoffは、持ち運び可能なMarkdownファイルを作成します。対象は限定的で、新しいハーネス、新しいディレクトリ、同僚への引き継ぎ、またはフェーズの途中でのサイドタスクの分岐に限ります。得られるのは持ち運びやすさです。
• サブエージェント：範囲を明確に限定したタスクを別のウィンドウに送り、レポートを受け取ります。
• /compactは、このコンテキストを圧縮して、新しいセッションに引き継ぎます。ツリーの最初ではなく、最下部にあるデフォルトの選択肢です。

PHASE-BOUNDARIES.mdを読んで、順序立てられたツリーを確認してください。5つの質問、それぞれの分岐の根拠、そして一次情報を参照するコストを考えると、まず続行を候補から外すべき理由が説明されています。判断は境界で行ってください。フェーズの途中なら、続行するか、残りをサブエージェントに分割します。

単独で使うスキル

メインフローから完全に独立しています。

• /grill-me：/grill-with-docs と同じく徹底的にインタビューしますが、ステートレスです。ローカルには何も保存せず、GLOSSARY.md も作成しません。作業ディレクトリにいないとき（計画、設計、文章など、リポジトリを伴わないものを練り上げるとき）に使ってください。作業ディレクトリにいる場合は、代わりに /grill-with-docs を使ってください。同じインタビューを行い、その記録も残すため、こちらのほうが確実に優れています。
• /grilling はインタビューの基本機能そのものです。ラウンド、検討の最前線、事実の把握はエージェントの役割で、判断するのはあなたです。/grill-me と /grill-with-docs は利用方法を示す名前付きの入り口であり、/triage、/wayfinder、/improve-codebase-architecture は内部でこの機能を実行します。ラッパーを介さずインタビューだけを行いたい場合に限り、直接使ってください。
• /prototype は、設計上の問いをひとつ解決するための、小規模で使い捨てのプログラムです。この状態モデルでよさそうか、あるいはこの UI はどのような見た目にすべきか、といった問いに答えます。「使い捨て」とはコードの書き方に対する制約であり、破棄する約束ではありません。得られた答えは実際のコードに取り込まれ、プロトタイプ自体も main から分岐した prototype/<name> ブランチに一次資料として保持され、実装の課題から参照されます。これはメインフローのステップ 2 における寄り道ですが、設計上の問いを机上で解決しにくいときはいつでも使ってください。
• /research：バックグラウンドエージェントに調査作業を委任します。エージェントが一次資料に基づいて問いを調査し、引用を含む Markdown ファイルをリポジトリに残します。調査中も作業を続けられます。生成されたファイルは、メインフローの /grill-with-docs に持ち込むためのものです。調査は考える作業を支えるものであり、置き換えるものではありません。
• /to-questionnaire は、作業を妨げているものがあなたの頭の中やコードベースではなく、ほかの人の頭の中にある場合に使います。相手に記入してもらう質問票を作成します。これは /grill-me の逆です。対象についてあなたにインタビューする代わりに、送付すること（誰に送るか、何を回答してほしいか）についてあなたに質問し、情報の不足を埋めるための問いを作ります。返ってきた内容は /grill-with-docs または /to-spec に活用できます。
• /wizard は、人間にしか実行できない手順のためのものです。インフラのプロビジョニング、認証情報や CI シークレットの設定、使い慣れていないサードパーティ製ダッシュボードの操作、一度きりの移行や切り替えなどが該当します。各 URL を開き、各値を取得して .env と GitHub シークレットに書き込む、対話型の bash スクリプトを生成します。これにより、毎回エージェントに手順を説明し直す必要がなくなります。モデルから呼び出されるため、エージェントは自分では越えられない壁にぶつかった時点ですぐにこのスキルを使います。エージェント自身で実行できることは、エージェントが実行すべきです。人間が本当に関与する必要がある場合に使ってください。
• /wait-what は、メッセージが伝わらなかったときに使う修正手段です。会話の途中や、ほかのスキルを使っている最中に呼び出すと、エージェントが直前に述べた内容を、あなたが持っていなかった背景情報を補いながら、平易な英語で、GLOSSARY.md の用語を使って説明し直します。事後に使える手段です。一方、事前に使う /grill-with-docs は、最初に共通の言葉遣いをすり合わせておくことで、専門用語がそもそも出てこないようにするための予防策です。
• /teach：現在のディレクトリを状態を保持する作業スペースとして使い、複数のセッションにわたって概念を学びます。
• /writing-for-agents は、エージェントが読むドキュメント（スキル、AGENTS.md、参照先のドキュメント）の書き方に関するリファレンスです。

前提条件

/setup-matt-pocock-skills：最初のエンジニアリングフローを開始する前に実行し、課題トラッカー、トリアージ用ラベル、ほかのスキルが前提とするドキュメントの構成を設定してください。カスタムの課題トラッカーも利用できます。

オプションのフォーク境界ツール

• /to-goal は承認済みのエビデンスを、移植可能な実行契約にまとめます。
• /goal-crafter は、単独で、または承認済みのエビデンスに基づいて、検証可能な目標の作成を支援します。
• /execute-spec-in-fork は、範囲が限定された承認済みの作業を Codex App のフォークに移送し、その受領を検証します。
• /spec-executor は、範囲が限定された承認済みのソースを実行し、エビデンスを返します。SPEC READY は任意です。
• /roundtable は、すでに形成された提案を複数の視点から検証します。
• /resolving-merge-conflicts は、意図に基づいて競合を解決する、フォークで管理されるスタンドアロンのスキルです。

これらは個別に使用することも、生成された成果物を組み合わせて使用することもできます。オプションの計画、テスト、レビューのスキルは、フォーク所有のコアの実行時依存関係ではありません。