xufang5219/agent-skills

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 でそれをトレーサーバレットチケットに分割し、各チケットはブロッキングエッジを宣言します。その後、チケットを次の2つの方法のいずれかで作業します：
     • /implement をチケットごとに実行し、各チケットの間に**/clear** でコンテキストをクリアします。ローカルトラッカーでは、.scratch/<feature>/issues/ の下にチケットごとに1つのファイルとして保管し、ブロッカー優先で手動で作業します。実際のトラッカーでは、エッジはネイティブのブロッキングリンクになり、ブロッカーが完了したチケットを取得できます。各チケットは自己完結型なので、最後のチケットのコンテキストは破棄可能です。
     • /implement-spec で仕様全体を1回の実行で実装します。チケットをタスクグラフとして読み取り、準備ができたフロンティア全体で実装サブエージェントを並行して実行し、すべてを1つの統合ブランチにまとめます。これは、自分で各チケットをドライブするよりも、ビルドをオーケストレーションしたい場合に使用します。
   • いいえ → 同じコンテキストウィンドウ内で、ここで**/implement** を実行します。

   どちらの場合も、コードは**/tdd** （一度に1つのレッド-グリーンスライス）をドライブし、/code-review （差分の2軸（スタンダード＋スペック）レビュー）で締めくくられます。/implement はチケットごとに両方を実行します。/implement-spec の実装者はそれぞれ/tdd をドライブし、統合ブランチに対して1回の/code-review を実行します。完全な仕様なしで具体的な振る舞いをテストファーストで構築したいだけの場合は、単独で**/tdd** を使用し、ブランチやPRを固定点に対してレビューしたい場合は、単独で**/code-review** を使用します。

   作業がプルリクエストとして上がると、/pr が本文を整形します。つまり、変更を示す最小限のビジュアル、機能することを示すbefore/afterの証拠、そして一方通行または双方向のドアの判断を提示します。これはモデル起動型なので、PRを作成するときにエージェントが自動的に使用します。

4. /retro でループを閉じます。ビルド後、特にうまくいかなかった場合は、セッションを振り返り、コードではなくエージェントの環境（ナビゲーションポインター、自動チェック、/code-review が実施するコーディング標準、ステアリングファイル、ツール）への変更を提案します。機械的なミスは決定論的なチェックに、判断事項はコーディング標準になります。次のビルドはより良い環境から始まります。

コンテキスト衛生

ステップ1〜3を1つの途切れのないコンテキストウィンドウに維持します（/to-tickets の後までコンパクト化やクリアをしないでください）。そうすることで、グリル、仕様、チケットがすべて同じ思考に基づいて構築されます。その後、各/implement はチケットから作業を開始し、新しい状態から始まります。/retro は、クリアする前に、振り返っているセッション内で実行します。クリア後は、代わりにそのセッションのログをポイントします。

この制限は**スマートゾーン、つまりモデルがまだ鋭く推論できるウィンドウ（最先端モデルで約150kトークン）です。/to-tickets の前にセッションがそれに近づいた場合は、劣化した状態でプッシュせず、最も近いフェーズ境界で/compact** して続行します（「フェーズ境界」を参照）。

オンランプ

作業を生成し、その後メインフローに合流する開始状況です。

• バグとリクエストが山積み → /triage。トリアージロールを通じてイシューを処理し、エージェント対応のイシューを生成します。これらは後で**/implement** がピックアップします。

  トリアージは自分が作成しなかったイシュー（バグレポート、受信した機能リクエスト、未加工で到着したもの）のみを対象とします。/to-tickets が生成したチケットはすでにエージェント対応なので、トリアージしないでください。

• 何かが壊れている → /diagnosing-bugs。難しいバグ（一目でわからないバグ、断続的な不安定なバグ、2つの正常な状態の間に忍び込んだリグレッション）に対応します。タイトなフィードバックループ（このバグですでに赤くなる1つのコマンド）が得られるまで理論化することを拒否し、その後リグレッションテストで修正します。修正が完了したら、同じセッションで**/retro** を実行して、何がバグを防いだかを尋ねます。実際の発見が、それをロックダウンする適切なシームがないことである場合、それは**/improve-codebase-architecture** の仕事です。

• 巨大で漠然とした取り組み：1セッションには大きすぎるグリーンフィールドプロジェクトや大規模機能構築 → /wayfinder。ここで最も認知的に要求されるフローです。現在地から目的地への道が見えていない場合、イシュートラッカー上に決定チケットの共有マップを作成し、1つずつ解決して、霧が押し戻されて道が明確になるまで、成果物ではなく決定を生成します。/grill-with-docs が1セッションで保持できるアイデアを具体化するのに対し、ウェイファインダーは保持できないアイデアのためのもので、より遅く密度が高いため、まさにその目的のために取っておき、明確にスコープされた機能には決して使用しないでください。

  マップが明確になったら、ビルドはせずに引き継ぎます。メインフローの**/to-spec** に合流し、マップのリンクされた決定を構築可能な計画に集約し、その後/to-tickets と/implement を通常どおり実行します。マップを直接/implement にループさせると、その集約をスキップしてリンクされた詳細を破棄するため、取り組みが本当に小さいことが判明した場合にのみ、直接/implement に進んでください。

コードベースヘルス

機能作業ではなく、単なるメンテナンスです。

• /improve-codebase-architecture は、エージェントが操作しやすいようにコードベースを維持するための空き時間に実行します。深化の機会を表面化します。1つを選択すると、メインフローの/grill-with-docs に持ち込めるアイデアが生成されます。これは候補を見つける調査です。選択したものを設計するベンチは、/codebase-design（以下）です。

語彙 (下層)

他のスキルの下で動作する2つのモデル起動型リファレンスで、それぞれがその語彙の唯一の情報源です。プロセスではなく言葉が問題である場合に直接使用するか、上記のスキルにそれらを呼び出させるようにします。

• /domain-modeling：プロジェクトのドメイン言語を具体化します。曖昧な用語に挑戦し、過負荷な単語（「account」が3つの仕事をしている）を解決し、元に戻すのが難しい決定をADRとして記録します。これは/grill-with-docs がGLOSSARY.md をクリーンな用語集に保つために駆動するアクティブな規律です。
• /codebase-design は、モジュールの形状を設計するための深いモジュール語彙（モジュール、インターフェース、深さ、シーム、アダプター、レバレッジ、ローカリティ）です。つまり、クリーンなシームで小さなインターフェースの背後に多くの振る舞いがある状態です。/tdd と/improve-codebase-architecture はどちらもこれを話します。

フェーズ境界

フェーズとは、セッション内の作業の塊です：グリル、実装、QAなど。2つのフェーズの境界では、5つのオプションがあり、それらを選択することはこのマップ全体で最も曖昧な決定です：

• Continue（続行）：そのまま進む。コストなし、損失なし。
• /clear：次に何も関係ない場合、ウィンドウを空にします。
• /handoff は、ポータブルなMarkdownファイルを書き出します。狭い用途です。新しいハーネス、新しいディレクトリ、同僚、またはフェーズ途中でのサイドタスクのフォーク専用です。得られるものはポータビリティです。
• Subagent（サブエージェント）：厳密にスコープされたタスクを自身のウィンドウに送り、レポートを取得します。
• /compact は、このコンテキストを圧縮し、それを使って新しいセッションをシードします。ツリーの最初の選択肢ではなく、最下部のデフォルトです。

順序付けられたツリーについては、PHASE-BOUNDARIES.md を読んでください。5つの質問、各ブランチの背後にある推論、そして一次情報源のコストがContinue を最初に除外すべきものにする理由が説明されています。境界で決定を行ってください。フェーズ途中では、続行するか、残りをサブエージェントに分割します。

スタンドアロン

メインフローから完全に外れています。

• /grill-me：/grill-with-docs と同じ執拗なインタビューですが、ステートレスです。ローカルに何も保存せず、GLOSSARY.md も作成しません。ワーキングディレクトリで作業していない場合（計画、設計、文章などを具体化する場合で、リポジトリがない場合）に使用します。ワーキングディレクトリにいる場合は、代わりに/grill-with-docs を使用してください。同じインタビューを実行し、証跡を残すため、厳密に優れています。
• /grilling はインタビュープリミティブそのものです：ラウンド、フロンティア、事実はエージェントの仕事であり、決定はあなたのものです。/grill-me と/grill-with-docs は2つの名前付きエントリポイントであり、/triage、/wayfinder、/improve-codebase-architecture はすべて内部でこれを実行します。ラッパーなしでインタビューが必要な場合にのみ、直接使用してください。
• /prototype は、1つの設計上の質問に答える小さな使い捨てプログラムです：この状態モデルは正しく感じられるか、またはこのUIはどのように見えるべきか。使い捨てはコードの書き方の制約であり、それを破棄するという約束ではありません。答えは実際のコードに組み込まれ、プロトタイプ自体は実装イシューからポイントされたprototype/<name> ブランチ（mainから分岐）に一次情報源として保持されます。これはメインフローのステップ2での迂回ですが、設計上の質問が紙の上で決着しにくい場合にはいつでも使用してください。
• /research：読み物の作業をバックグラウンドエージェントに委任します。一次情報源に対して質問を調査し、引用付きのMarkdownファイルをリポジトリに残します。エージェントが読んでいる間、作業を続けてください。生成されたファイルは、調査が思考を駆動し、それに取って代わるものではないため、メインフローの/grill-with-docs に持ち込むためのものです。
• /to-questionnaire は、あなたの頭の中やコードベースではなく、他の誰かの頭の中にあるものがあなたをブロックしている場合に登場し、その相手に記入してもらうためのアンケートを作成します。これは/grill-me の逆です。あなたを対象に関してインタビューする代わりに、送信先（誰に送るのか、何を返してもらう必要があるのか）についてあなたにインタビューし、ギャップに質問を向けます。返ってきたものは、/grill-with-docs または/to-spec の材料になります。
• /wizard は、人間にしかできないステップのためのものです。つまり、インフラストラクチャのプロビジョニング、認証情報やCIシークレットの設定、馴染みのないサードパーティダッシュボードのクリック操作、1回限りの移行やカットオーバーの実行などです。各URLを開き、各値をキャプチャし、それを.env とGitHubシークレットに書き込むインタラクティブなbashスクリプトを生成するため、その手順を毎回エージェントに再説明する必要がなくなります。モデル起動型なので、エージェントがあなただけが通過できる壁にぶつかった瞬間にこれを使用します。エージェントが自分で実行できるのであれば、そうすべきです。これは人間が本当にループ内にいる場合のためのものです。
• /wait-what は、メッセージが伝わらなかった場合の修正手段です。会話の途中で、他のスキル内で使用すると、エージェントはGLOSSARY.md の語彙を使用して、あなたが欠落していたコンテキストを含めて、平易な英語で、今言ったことを言い直します。これは事後的に機能します。/grill-with-docs は事前の治療法です。早い段階で合意された共有言語こそが、専門用語がそもそも現れるのを防ぐからです。
• /teach：現在のディレクトリをステートフルなワークスペースとして使用して、複数のセッションにわたってコンセプトを学習します。
• /writing-for-agents は、エージェントが消費するドキュメント（スキル、AGENTS.md、ポイントされたドキュメント）を作成するためのリファレンスです。

前提条件

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