ketchup

Ketchup

/ketchup の前にユーザーが最後に書いたメッセージ以降、このチャットで何が変わったのかをユーザーに伝え、それぞれの変更が今どうなっているかだけでなく、その意味も理解できるようにします。そのうえで、ユーザーがこの返信だけで対応できるよう、返事や判断を待っている項目をすべて並べます。通知とサブエージェントの結果は、ユーザーからのメッセージではありません。ユーザーは自分の最後のメッセージまでのことは覚えていても、その後のことは覚えていないものとします。

タスクの内容ではなく、/bro の話し方を使います。平易な言葉、短い文、専門用語を避け、誰かが別の人に近況を伝えるように書きます。どのように作業したかではなく、ユーザーにとって何が変わったのかを伝えます。「CI がグリーン」ではなく「テストは合格しています」と書きます。ユーザーが対応するために必要でない限り、ハッシュ、ファイルパス、コマンド、ビルド番号、テスト件数は省きます。PR、ブランチ、エージェントには、独自に付けたラベルではなく、ユーザーがわかる名前を使います。事実を理解するのに背景が必要なら、その背景を説明するか、その事実を省きます。

変更点を確認する

このターンでは読み取り専用を守ります。すでに得ている情報だけを使って状況を伝えます。コードを変更したり、アプリやジョブを起動したり、何かを投稿したりしないでください。該当するメッセージ以降の自分の作業、サブエージェントの報告、チャット内のほかの人からのメッセージを集めます。このチャットで扱った各 PR、CI 実行、エージェントの現在の状況を確認します。記載する各数値は根拠となる事実と照らし合わせ、数値を訂正する場合はそのことも伝えます。

アクション項目とは、製品に関する選択、承認、取り消せない操作、こちらにはないアクセス権など、ユーザーだけが行える判断や手順です。以前のメッセージで出たものも含め、ユーザーの返事をまだ待っている項目はすべて記載します。こちらで引き続き対応できる作業は、アクション項目ではありません。返信を埋めるために判断をでっち上げてはいけません。ユーザーが依頼しておらず、作業上も必要ない手順は、取り消せない操作でユーザーの判断を待っている場合を除き、アクション項目にしません。取り消せない操作で判断を待っている手順は、説明を一行だけにして、視覚的な強調は付けません。

複数の項目をまとめて一つの判断として提示できます。たとえば、マージ待ちの一連の PR をまとめて扱えます。各項目について、リンク、ユーザーにとっての変更点、判断の根拠、リスク、おすすめの対応を集めます。判断に必要な事実がわからない場合は「不明」と記載します。リンクがない場合は記載しません。

返信を書く

説明ではなく、判断が必要な点に文字数を使います。何が起きたかは、画像を除いて100語未満に収め、起きたことが少ない場合はさらに短くします。ユーザーに何ももたらさなかった作業は省きます。各項目は30語程度にします。返信の長さは項目数に応じて増やします。2項目なら、画像を除いて合計150語を大きく下回る長さにし、30項目なら、はるかに長くなります。語数制限に合わせるために項目を省いたり、短くしたりしてはいけません。項目の代わりに件数だけを示したり、リンクだけを載せたりしてはいけません。リンクは補足情報として役立ちますが、返信だけで判断できるようにします。

最初に、ユーザーの対応が必要なことを短く示すか、何もないと伝える一文を書きます。詳細はアクション項目に記載します。何も起きておらず、ユーザーの対応も不要なら、その旨だけを伝えて終わります。

次に、起きたことを示します。まず画像を載せます。作業で作成されたスクリーンショットや動画をインラインで埋め込み、その後に変更を説明する図があれば載せます。続いて、ユーザーが依頼した内容ごとに、結果と、完了・進行中・失敗・未確認のいずれかを短い箇条書きでまとめます。声に出して自然な言い方にします。「インデックスがなく検索が遅くなっていました」のように書き、「検索の確認：完了」や「検索が遅い：インデックスが不足」のようには書きません。途中で見つけて修正したバグがあれば、その名前を挙げます。各行は、単独で読んでも正しい内容にします。ユーザーの対応待ちのものを完了としないでください。また、アクション項目に記載する内容は省きます。要約の下には、ユーザーが知っておくべきことや対応すべきことが変わる場合に限り、短い行を最大3つ記載します。最後に、自分で続けられる作業が残っていれば、それを1行で示します。

次に、アクション項目を列挙します。マージ、承認、選択など、ユーザーが決める必要のあることを尋ね、推奨案も示します。最初に行うべき手順は推奨案に含めます。先に済ませる必要があることや、元に戻せないことも同様です。判断に関係する各PR、issue、エージェントの番号またはリンクを、選択肢を比べる場合はその選択肢とあわせて記載します。

判断内容に合わせて形式を調整します。1項目についての判断なら、箇条書きは1つにします。判断内容、推奨案、ユーザーにとっての変更点、推奨の根拠、リスクを記載し、項目名は1回だけ示します。複数の項目が同じ判断に関わる場合は、判断内容と推奨案を最初に1度だけ示し、その下に項目ごとの箇条書きをリスクの高い順に並べます。それぞれの項目について、リンクと名前、ユーザーにとっての変更点、推奨の根拠、リスクを記載します。項目ごとの推奨案が全体の判断と異なる場合に限り、その項目の推奨案を明記します。リスクが低い場合も、各項目のリスクを記載します。たとえば、「低リスク：色だけが変わります」のように書きます。待つことで生じる損失が単なる遅延を超える場合、たとえば期限やデータの損失がある場合に限り、待つことの不利益を記載します。

複数の選択肢から選ぶ判断では、検討したすべての選択肢を示します。それぞれについて、ユーザーが得られるものと、その代償を記載し、該当する場合は現在の状況も示します。これらの代償が判断に伴うリスクとなるため、別途リスクの行は追加しません。上のスクリーンショットで選択肢を示している場合は、それぞれのスクリーンショットの下に、その選択肢の利点と代償を記載します。

ビジュアル

ビジュアルとは、スクリーンショット、動画、Mermaid 図、/visualize によるチャートや図、または生成画像のことです。Markdown の表は、変更前と変更後の列があってもビジュアルではありません。

文章で説明するより画像のほうが理解しやすい場合は、図にしてください。たとえば、デザインやシステムの仕組み、各 PR の状態を含む PR の積み重ねや依存関係、修正前後の比較、選択肢の比較などです。ステータスの一覧、対応項目の一覧、つながりのないボックスは決して図にしないでください。同じ事実を、文章とビジュアルの両方で重複して示さないでください。

ひと目で読めるよう、各ビジュアルは小さく保ってください。ボックスは最大 6 個で、各ボックスの語数は最大 8 語です。ラベルには「Tests: pass」のようなタグではなく、人が口にする自然な言葉を使ってください。文が必要な事実は、文章で説明するか、記載しないでください。

変更が目に見える場合は、リンクだけでなくスクリーンショットや動画を本文に埋め込んでください。目に見える変更があるのにスクリーンショットがない場合は、概要の行に「No screenshot yet」と記し、画面上で何が変わったかもその行に記載してください。図やチャートは、手元にある事実から作成してください。つながりの説明には Mermaid 図を、数値の可視化には /visualize のチャートを使います。数値を決して捏造せず、実際に撮影していない画面の画像を描いたり生成したりしないでください。実在する成果物のみリンクしてください。