ask-matt

Ask Matt

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

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

メインフロー：アイデア → リリース

ほとんどの作業がたどるルートです。アイデアがあり、それを形にしたい場合に使います。

1. /grill-with-docs は、対話を通じてアイデアを具体化します。作業ディレクトリ内で作業しているときは、いつでもここから始めてください。状態を保持し、学んだことを CONTEXT.md と ADR に記録します。（作業ディレクトリがない場合は、代わりに /grill-me を使います。こちらは「単独で使うスキル」で説明しています。どちらも同じ /grilling プリミティブを実行します。grill-with-docs は記録を残すため、記録先となるリポジトリがある場合はこちらのほうが適しています。）

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

   • /handoff で引き継いでから、そのファイルを使って新しいセッションを開始します。
   • /prototype で使い捨てのコードを書き、疑問に答えます。
   • 学んだことを /handoff で元に戻し、元のアイデアのスレッドから参照します。

3. 分岐：複数のセッションにまたがる開発ですか？

   • はい → /to-spec でスレッドを仕様書にまとめ、次に /to-tickets でトレーサーバレット方式のチケットに分割します。各チケットにはブロック関係のエッジを明記します。ローカルトラッカーでは .scratch/<feature>/issues/ 配下にチケットごとのファイルを1つずつ作成し、ブロッカーの解消順に手作業で進めます。実際のトラッカーでは、エッジがネイティブのブロックリンクになるため、ブロッカーがすべて完了したチケットを取得できます。チケットごとに /implement を開始し、その間に /clear でコンテキストを消去します。各チケットは自己完結しているため、最後のチケットのコンテキストは破棄できます。
   • いいえ → 同じコンテキストウィンドウ内で、そのまま /implement を実行します。

   どちらの場合も、/implement は内部で /tdd を実行し（一度に1つずつ、レッドからグリーンへのスライスで進めます）、各課題を実装します。その後、コミットする前に /code-review を実行し、差分を「標準」と「仕様」の2つの軸でレビューして完了します。完全な仕様書なしで、具体的な振る舞いをテストファーストで実装したい場合は /tdd を単独で使い、固定された基準に照らしてブランチや PR をレビューしたい場合は /code-review を単独で使ってください。

コンテキストの管理

ステップ1～3は、途切れない1つのコンテキストウィンドウで進めてください（/to-tickets が終わるまで、コンパクションも消去もしないでください）。そうすることで、対話、仕様書、チケットがすべて同じ思考をもとに作られます。その後、各 /implement は新たに開始し、チケットをもとに作業します。

この制限の目安となるのが**スマートゾーン**です。これは、モデルが鋭い推論を維持できるウィンドウ（最先端モデルで約15万トークン）を指します。/to-tickets の前にセッションがこの範囲に近づいたら、性能が落ちた状態で無理に続けないでください。最も近いフェーズの境界で /compact を実行してから続けてください（フェーズの境界を参照してください）。

開始点

作業を生み出し、メインフローに合流するきっかけとなる状況です。

• バグやリクエストが溜まっている → /triage。トリアージの各役割を通じてイシューを処理し、エージェントがすぐに取り組めるイシューを作成します。これを後で /implement が取り込みます。

  トリアージの対象は、自分が作成していないイシューだけです。バグ報告、寄せられた機能リクエストなど、未整理のまま届いたものが対象です。/to-tickets が作成したチケットはすでにエージェントがすぐに取り組める状態なので、トリアージしないでください。

• 何かが壊れている → /diagnosing-bugs。ひと目では原因が分からないバグ、断続的に発生する不安定なテスト、既知の正常な状態の間に紛れ込んだリグレッションなど、手強い問題に使います。まず、短いフィードバックループ（対象のバグで実際に失敗するコマンドを1つ）を用意するまで、仮説を立てることを拒みます。その後、リグレッションテストを追加して修正します。事後分析で、バグを確実に封じ込めるための適切な接点がないことが本当の発見だった場合は、/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：プロジェクトのドメイン用語を明確にします。曖昧な用語に異議を唱え、複数の意味で使われる単語（3つの役割を担う「account」など）を整理し、変更が難しい判断をADRとして記録します。CONTEXT.md を明確な用語集に保つために、/grill-with-docs が用いる実践的な手法です。
• /codebase-design は、モジュール（module）、インターフェース（interface）、深さ（depth）、接点（seam）、アダプター（adapter）、活用度（leverage）、局所性（locality）といった、深いモジュールを設計するための用語体系です。明確な接点に、小さなインターフェースの背後に多くの振る舞いを持たせるという、モジュールの形を設計します。/tdd と /improve-codebase-architecture は、どちらもこの用語体系を使います。

フェーズの境界

フェーズとは、セッション内の作業のまとまりです。検討、実装、QAなどが該当します。フェーズ間の境界では、5つの選択肢があり、どれを選ぶかが、この全体像の中で最も判断の難しいポイントです。

• Continue：そのまま続けます。コストも損失もありません。
• /clear：次の作業にここでの内容が関係ない場合に、ウィンドウを空にします。
• /handoff：持ち運び可能な Markdown ファイルを作成します。用途は限定的で、新しいハーネス、新しいディレクトリ、同僚、またはフェーズの途中でサイドタスクを分岐する場合にのみ使います。これにより、内容を持ち運べます。
• サブエージェント：範囲を絞ったタスクを専用のウィンドウに送り、レポートを受け取ります。
• /compact：このコンテキストを圧縮し、その内容を引き継いだ新しいセッションを開始します。最初に選ぶものではなく、ツリーの末端にあるデフォルトです。

順序立てられたツリーについては、PHASE-BOUNDARIES.md をご覧ください。5つの質問、それぞれの分岐の理由、そして一次資料のコストを考慮すると、まず除外すべき選択肢がContinueである理由が説明されています。判断は境界で行ってください。フェーズの途中では、そのまま続けるか、残りの作業をサブエージェントに分割してください。

単独で使うもの

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

• /grill-me：/grill-with-docsと同じ、容赦のないインタビューですが、ステートレスです。ローカルには何も保存せず、CONTEXT.mdも作成しません。作業ディレクトリにいないとき（計画のブラッシュアップ、設計、文章など、配下にリポジトリがないもの）に使ってください。作業ディレクトリにいる場合は、代わりに/grill-with-docsを使ってください。同じインタビューを実行し、記録も残すため、こちらのほうが確実に優れています。
• **/grilling**はインタビューの基本機能そのものです。ラウンド、未解決の論点、事実の確認はエージェントの役割で、判断するのはあなたです。/grill-meと/grill-with-docsは、その機能を呼び出すための2つの名前付き手段であり、/triage、/wayfinder、/improve-codebase-architectureは内部でこの機能を実行します。ラッパーなしでインタビューだけを行いたい場合に限り、直接使ってください。
• **/resolving-merge-conflicts**は、進行中のマージまたはリベースのコンフリクトを、各側の一次ソースをたどって意図に基づき、行を選ぶのではなく、ハンクごとに解決し、その後に操作を完了します。--abortは決して実行しません。どのフローにも属さない単独のツールです。すでにコンフリクトの途中にいるときに使ってください。
• /prototypeは、設計上の疑問を1つ解決するための、小規模な使い捨てプログラムです。この状態モデルは適切か、UIはどのような見た目にすべきか、といった疑問に答えます。使い捨てとは、コードの書き方に関する制約であって、破棄するという約束ではありません。回答は実際のコードに取り込まれ、プロトタイプ自体も、実装イシューから参照される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**は、メッセージが伝わらなかったときに使う修正手段です。他のスキルの実行中を含め、会話の途中で使うと、エージェントが直前に述べたことを、あなたに不足していた文脈を補い、CONTEXT.mdの用語を使って平易な英語で説明し直します。これは事後に使うものです。事前に対処するのが/grill-with-docsです。早い段階で共通の言葉遣いに合意しておけば、そもそも専門用語が出てくるのを防げます。
• /teach：現在のディレクトリをステートフルな作業スペースとして使い、複数のセッションにわたって概念を学びます。
• **/writing-for-agents**は、エージェントが読むドキュメント（スキル、AGENTS.md、参照先として指定されたドキュメント）の書き方に関するリファレンスです。

前提条件

/setup-matt-pocock-skills：最初のエンジニアリングフローの前に実行して、他のスキルが前提とするイシュートラッカー、トリアージラベル、ドキュメントのレイアウトを設定します。カスタムのイシュートラッカーも使用できます。