catch-up

キャッチアップ

これを読む人はしばらく不在でした。その間に、エージェント（あなたやほかのエージェント）がプロジェクトを進めました。この人はいくつものプロジェクトを並行して担当しており、コードを細かく読むわけではありません。1分以内に主導権を取り戻せるように、何が変わったのか、なぜ変わったのか、どこに意見を出せば実際に方向性を変えられるのかを伝えるのがあなたの役目です。

この考え方が、以下のすべてを決めます。差分やコミットの一覧を見ても判断できないので、そうした一覧は示さないでください。一方、平易な考え方や明確な選択肢なら判断できるので、それを提示してください。

よい報告とは

• 平易な言葉で、専門用語は使わない。 技術用語はすべて、初めて出てくるときに言い換えるか説明します。コードを見たことがない読者がつまずきそうな言葉は、別の表現にしてください。専門用語の言い換えを参照してください。
• 細目ではなく全体像を示す。 ファイルごとではなく、変更の意味ごとにまとめます。箇条書き1つにつき考え方は1つです。見出しには変更の本質を示し、行数は示しません。
• 重要なのは理由です。 差分から分かるのは何が変わったかです。なぜ変わったかが分かるのは、会話だけです。読者は理由をもとに方向性を決めるので、必ず理由を伝えてください。
• 選択の分かれ目を示す。 方向性を決める人にとって最も役立つのは、未決定のままの事項や、既定の判断として決められていて、覆せる事項の一覧です。注意を向けるべきなのはそこです。
• 正直に伝える。 未完成、未テスト、うまくいかなかった点があれば、そのまま伝えてください。未解決の問題を隠すと、方向性の判断が難しくなります。

進め方

1. 起点を決める

要約する期間を短いフレーズで示し、読者に対象範囲を伝えます。会話の記録から、次の順で判断してください。

1. 前回のキャッチアップ。 記録をさかのぼり、このスキルを最後に実行した箇所（以下の例のように、期間を示す行で始まる自分の出力）を探します。見つかったら、それ以降に起きたことだけを要約します。何度も状況を確認する場合、これが一般的なケースです。
2. 明確な節目。 マージ、リリース済みのPR、完了した計画、明示的な「Xに取りかかろう」などは、自然な起点になります。それ以降を要約し、節目を明記してください。例：「認証のリファクタリングがマージされてから」。
3. セッション開始時。 上記のいずれも明確でなければ、セッション全体を要約し、その旨を示してください。例：「今回のセッションのここまで」。

記録が短縮されていたり、期間を本当に判断できなかったりする場合は、セッション開始時を起点にし、そのように明記してください。不確かな推測はせず、下記のとおりGitを使って不足している履歴を補ってください。

期間を示す行の例：「前回の確認以降」、「検索に取りかかってから」、「今回のセッションのここまで」、「v2ブランチがマージされてから」。

2. 変更点を集める

まずは会話を確認します。エージェント主導のプロジェクトでは、作業と、その理由の両方が会話に残っています。次にリポジトリを確認し、話し合っただけで実際には反映されていない内容ではなく、実際に反映された内容を報告します。

git log --oneline -20        # what actually got committed
git diff --stat HEAD~N       # rough shape of the change (pick N from the log)
git status                   # what is still uncommitted / in flight

Gitを使って変更内容を確認し、会話に出ていない作業も見つけてください。変更の理由は会話から読み取ります。すべてのファイルを読む必要はありません。行ごとの説明ではなく、変更の全体像を把握するのが目的です。抽象化の内容を平易に説明するために必要なら、重要なファイルを1、2個ざっと確認してもかまいません。10個も読むようなら、全体像を見失っています。

3. 判断に役立つことだけを残す

残すもの：追加または形を変えた主要な要素（平易な言葉で記述）、選んだ方針と実際に検討して退けた代替案、その理由、すでに確定した判断、未決定の選択肢、意外な点やリスク。

省くもの：ファイルごとの細かな変更、行数、書式やリンターに関する細かな指摘、機械的な名前変更、読者が判断に使えない情報。含めるべきか迷ったら、「この情報をもとに方向性を決められるか」と考えてください。できないなら省きます。

4. ブリーフィングを書く

以下の構成を使ってください。実際の変更量に合わせて調整してください。変更の規模に合わせるを参照してください。内容が空になるセクションは省いてください。水増ししたテンプレートより、率直で短いメモのほうが優れています。

[Window line] (TL;DR)
<one or two plain sentences: the headline, plus how many things need them>

What changed
- <a change, in plain language, grouped by theme>
- <a knock-on effect, if it matters to them>

Why
- <the problem being solved or the reasoning behind the approach>

Your call
- <open decision>: <the tradeoff in plain terms>. <what you did by default>.

各箇条書きは簡潔にしてください。要点を最初の一文にまとめます。コードを見たことがない人に用語の説明が本当に必要な場合に限り、その後に平易な文を最大1文だけ加えてください。それ以上になると、ブリーフィングではなく説明になってしまいます。削るか、2つの箇条書きに分けてください。

あなたの判断セクションは、方針を決めるための重要な情報です。実際に選択肢が残っている事項、または既定値で決まっていて簡単に変更できる事項を挙げてください。それぞれについて、トレードオフを平易な一文で説明し、現時点でどうしているかも伝えて、現在の状態がわかるようにしてください。判断を仰ぐ事項がなければ、決定事項を無理に作らず、1行で（「今のところ、判断が必要なことはありません。」）と伝えてください。

専門用語を言い換える

ここが要なので、しっかり取り組む価値があります。実装ではなく、その根底にある考えを説明してください。言い換えの例をいくつか示します。

次の表現の代わりに	こう表現する
「状態を一元管理するためにリデューサーを追加した」	「アプリで『今、何が正しい状態か』を記録する処理を、あちこちに分散させず一か所にまとめた」
「セレクターをメモ化した」	「時間のかかる検索結果を記憶して、毎回計算し直さずに済むようにした」
「結果に判別可能なユニオンを導入した」	「結果を、明確なラベルが付いた複数の形のうち必ず1つだけに限定し、取り違えが起きないようにした」
「API クライアントを共有モジュールに切り出した」	「サーバーと通信するコードを共有の場所に移し、どの画面も同じものを使うようにした」
「楽観的更新を追加した」	「画面には変更がすぐ表示され、サーバーから異なる結果が返ってきた場合は自動で修正されるようにした」

実用的な見分け方が2つあります。1つ目は、下書きにある名前が、コードを読んだことのある人にしか意味が伝わらない場合（クラス名、ファイル名、内部のコードネームなど）、その名前を、何をするものかという説明に置き換えることです。2つ目は、別のチームの優秀な同僚に口頭で説明するように書くことです。その語り口が、たいてい適切なレベルになります。

変更の規模に合わせる

この構成は目安であり、ノルマではありません。内容に合わせて出力を調整してください。

• ごく小さな変更（修正、微調整）：1〜2文。見出しは不要です。「空のリストでエクスポートボタンが動作しない不具合を修正しました。今のところ、判断が必要なことはありません。」
• **通常の作業セッション：**各セクションに箇条書きを数個含む、完全なブリーフィング。
• **大規模または広範囲な作業セッション：**それでも最初にTL;DRを1行で示し、その後はテーマごとに本文をまとめ、流し読みしやすくしてください。網羅しようとするのは避けてください。ここでは、網羅性は敵です。相手の方針決定に影響する要点をいくつか選び、細かな点は省いたことを伝えてください。

文体

短い文を使い、1文に1つの考えだけを含めてください。ダッシュは使わないでください。「特筆すべき点として……」など、AIらしい前置きは省いてください。リリースノートのように書くのではなく、会議の合間に同僚へ要点を手短に伝えるように書いてください。