ask-matt

Ask Matt

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

スキルの内容を説明したり、手順を省略するよう勧めたりする前に、そのスキルの SKILL.md を読んでください。ここにある概要は、全体を把握するためのものにすぎません。

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

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

ほとんどの作業がたどる経路です。アイデアを形にしたいときに使います。

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つの統合ブランチに反映します。チケットごとの作業を自分で進めるより、ビルド全体を調整したい場合に使ってください。
   • いいえ → 同じコンテキストウィンドウ内で、その場で /implement を実行します。

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

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

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

コンテキストの衛生管理

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

この制限の目安は**スマートゾーン**です。最先端モデルでは約150kトークンに相当するウィンドウ内で、モデルは鋭い推論を維持できます。/to-tickets の前にセッションがこの範囲に近づいたら、性能が落ちた状態で無理に続けないでください。最も近いフェーズの区切りで /compact を実行し、その後続けます（「フェーズの区切り」を参照）。

導入経路

作業のきっかけとなる状況から始め、メインフローに合流します。

• 何かが壊れている → /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：プロジェクトのドメイン用語を明確にします。曖昧な用語に異議を唱えたり、複数の意味で使われている言葉（3つの異なる役割を担う「アカウント」など）を整理したり、変更が難しい決定をADRとして記録したりします。GLOSSARY.md を整理された用語集に保つため、/grill-with-docs が実践する分野です。
• /codebase-design は、モジュールの構造を設計するためのディープモジュールの語彙（モジュール、インターフェース、深さ、境界、アダプター、レバレッジ、局所性）です。明確な境界の背後に多くの振る舞いを隠し、小さなインターフェースで提供する設計を扱います。/tdd と /improve-codebase-architecture は、どちらもこの語彙を使います。

フェーズの境界

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

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

順序付きのツリー、5 つの質問、各分岐の根拠、そして一次情報源のコストを踏まえると、まずContinueを除外すべき理由については、PHASE-BOUNDARIES.md をお読みください。判断は境界で行います。フェーズの途中では、そのまま続けるか、残りをサブエージェントに分割してください。

単独で使う場合

メインの流れとは完全に切り離されています。

• /grill-me： /grill-with-docs と同じ徹底したインタビューですが、ステートレスです。ローカルには何も保存せず、GLOSSARY.md も作成しません。作業ディレクトリにいないとき（計画、設計、文章など、リポジトリを伴わないものを練るとき）に使います。作業ディレクトリにいる場合は、代わりに /grill-with-docs を使ってください。同じインタビューを行い、記録も残すため、こちらのほうが明らかに優れています。
• /grilling はインタビューの基本機能です。ラウンドや検討範囲、事実の確認はエージェントが担当し、判断はあなたが行います。/grill-me と /grill-with-docs は、この機能を使うための名前付きの方法であり、/wayfinder と /improve-codebase-architecture も内部でこれを実行します。ほかの機能を介さずにインタビューだけを行いたい場合に限り、直接使ってください。
• /prototype は、設計上の疑問を 1 つ解決するための、小規模な使い捨てプログラムです。たとえば、この状態モデルで問題ないか、あるいはこの UI をどう見せるべきかを確かめます。「使い捨て」とは、コードの書き方に関する制約であって、破棄するという約束ではありません。得られた答えは実際のコードに反映され、プロトタイプ自体は、メインブランチから分岐した prototype/<name> ブランチ上で一次情報源として保持され、実装イシューから参照されます。これはメインフローのステップ 2 にある寄り道ですが、紙上では決着しにくい設計上の疑問があるときはいつでも使ってください。
• /research：調査作業をバックグラウンドエージェントに委任します。エージェントは一次情報源に基づいて質問を調査し、引用元を明記した Markdown ファイルをリポジトリに残します。調査中も作業を続けられます。生成されたファイルは /grill-with-docs でメインフローに持ち込むためのものです。調査は思考を支えるものであり、置き換えるものではありません。
• /wait-what は、メッセージが伝わらなかったときに使う修正手段です。会話の途中で、ほかのスキルの使用中にも実行できます。エージェントは、あなたに足りなかったコンテキストを補いながら、先ほどの説明を平易な英語で、GLOSSARY.md の用語を使って言い直します。事後にも使えますが、最初から防ぐには /grill-with-docs が適しています。早い段階で共通の言葉遣いに合意しておけば、専門用語が飛び交うのを防げるからです。
• /teach：現在のディレクトリを状態を保持するワークスペースとして使い、複数のセッションにわたって概念を学びます。
• /writing-for-agents は、エージェントが読むドキュメント（スキル、AGENTS.md、参照先として指定されたドキュメント）の執筆ガイドです。

前提条件

/setup-repo：最初のエンジニアリングフローの前に実行し、課題管理ツール、トリアージ用ラベル、ドキュメントの構成、コーディング規約を設定してください。これらはほかのスキルが前提とするものです。実行時には、標準的な回答があらかじめ入力された状態で /setup-matt-pocock-skills、続いて /setup-coding-standards を実行します。設定の一部だけを行いたい場合は、各基本機能を個別に利用できます。カスタムの課題管理ツールも利用できます。