ketchup

Ketchup

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

bro スキルを使います。タスクの内容ではなく、その話し方を取り入れてください。平易な言葉を使い、短い文で、専門用語は避け、ある人が別の人に状況を伝えるように書いてください。何をしたかではなく、ユーザーに何が変わったかを伝えてください。「CI はグリーンです」ではなく、「テストは合格しました」と書いてください。ユーザーが行動するのに必要でない限り、ハッシュ、ファイルパス、コマンド、ビルド番号、テスト件数は省きます。PR、ブランチ、エージェントには、こちらで作ったラベルではなく、ユーザーがわかる名前を使ってください。事実の背景を説明しないと意味が通じない場合は、その背景を添えるか、その事実を省いてください。

変更内容を集める

このターンでは、読み取り専用で作業します。すでにある情報だけを使って図や画像を作ってください。コードを変更したり、アプリやジョブを起動したり、何かを投稿したりしてはいけません。このチャットで自分が最後のメッセージ以降に行った作業、サブエージェントからの報告、このチャットで他の人が送ったメッセージを集めます。このチャットで触れた各 PR、CI 実行、エージェントの現在の状態を確認します。提示する数字はそれぞれ根拠となる事実と照合し、数字を訂正する場合はそのことを明記します。

アクション項目とは、製品に関する選択、承認、取り消せない操作、こちらに権限がないアクセスなど、ユーザーだけが行える判断や手順です。最後のメッセージより前に挙がったものも含め、ユーザーの判断をまだ待っている項目はすべて含めます。こちらで引き続き対応できる作業は、アクション項目ではありません。返信を埋めるために判断をでっち上げてはいけません。ユーザーが求めておらず、作業にも不要な手順は、取り消せない操作でユーザーの判断を待っている場合を除き、アクション項目にしません。その場合は、図や画像を添えずに一行で示します。

一つの判断で複数の項目を扱える場合があります。たとえば、マージ待ちの PR が複数ある場合です。項目ごとに、リンク、ユーザーにとっての変更点、選択の根拠となる情報、リスク、推奨案を集めます。判断に必要な事実がわからない場合は「不明」と書きます。リンクがわからない場合は省きます。

返信を書く

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

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

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

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

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

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

ビジュアル

ビジュアルとは画像のことです。スクリーンショット、動画、Mermaid 図、レンダリングされたグラフや図、生成画像などが該当します。Markdown の表は、変更前と変更後の列があってもビジュアルではありません。

文章で説明するより画像のほうが把握しやすい場合は、図にしてください。設計やシステムの仕組み、各 PR の状態を含む PR の積み重ねや依存関係、修正前後の比較、選択肢の並列表示などが該当します。ステータスの一覧、アクション項目の一覧、何もつながっていないボックスは図にしないでください。同じ事実を文章や複数のビジュアルで繰り返し示さないでください。

各ビジュアルは、ひと目で読める大きさにしてください。ボックスは最大 6 個で、それぞれの語数は最大 8 語にします。ラベルは「Tests: pass」のようなタグではなく、人が口にするような普通の言葉で書いてください。文章が必要な事実は、テキストに書くか、記載しないでください。

変更が目で見てわかる場合は、スクリーンショットや動画をリンクだけでなく本文に埋め込んでください。目に見える変更があるのにスクリーンショットがない場合は、概要の行に「スクリーンショットはまだありません」と記載し、その行で画面上の変更内容を説明してください。図やグラフは、手元にある事実に基づいて作成してください。つながりを示すには Mermaid 図を、数値を示すにはレンダリングされたグラフを使います。数値を捏造したり、キャプチャしていない画面の画像を描いたり生成したりしないでください。実在する成果物のみをリンクしてください。