brief

概要

情報量が豊富で視覚的な1ページのブリーフを作成してください。文章主体のドキュメントではなく、情報が詰まったダッシュボードのようなデザインにします。自己完結した単一のHTMLファイルで、変更の内容を把握し、差分を自分で読まなくても、承認またはマージするかどうかをすばやく判断できるものにしてください。

読者は多忙なマネージャーです。30秒しか時間をかけない場合も、10分かける場合もあります。どちらの場合でも得るものがあるブリーフにしてください。そのため、構成は厳密に優先度順とし、影響が大きく元に戻しにくい変更を先に、よくある定型的な編集を最後に配置します。目標は、明瞭さを犠牲にせず、最短時間で最大限の情報を伝えることです。丁寧に説明しつつ、重要なことを先に示してください。

このブリーフはレポートではありません。PRの作成者がレビュー担当者と席を共にして作業内容を説明するようなものです。すべての主張を実際のコードに結び付け、変更内容だけでなく、変更が必要になった理由も説明してください。多くの読者は差分を開きません。重要なコードを本文内に示してください。

2つのモード — 自動判定

このスキルでは、作業の状態に応じて2種類のブリーフを作成します。

• DRAFT — ワーキングツリーに差分があり（未コミット、またはコミット済みだが未プッシュ）、通常はproposed-pr-stack.mdにPRスタック案が記載されています。まだ実際のPRがないか、スタックのレビューが完了していません。ユーザーが作業をPRに分割する前に承認するかを判断する段階で読むブリーフです。
• FINAL — 実際のPRスタック（オープンまたはマージ済みのPRが1つ以上）があり、レビューが完了しています（PRのレビュー対応が完了しているか、すべての指摘事項がトリアージ済みです）。ユーザーがマージの合図を出そうとしている段階で読むブリーフです。

**モードの選び方：**存在するものを確認します。

1. このブランチ／スタックに実際のPRがありますか？（gh pr list --head <branch>を実行します。Graphiteを使用している場合はgt logを確認します。）
2. ある場合、レビューは完了していますか？（未対応のレビューコメントや再レビュー待ちの依頼がなく、すべての指摘事項が後続のコミットで修正済み、または明示的にトリアージ済みであることを確認します。）
3. **両方とも「はい」→ FINALモード。**それ以外は→ DRAFTモード。

ユーザーが特定のモード（「draft brief」／「final brief」）を明示的に指定した場合は、それに従ってください。指定がなければ自動で選び、返信の冒頭に選んだモードを記載してください（「FINALブリーフを作成します — スタックのレビューは完了しています。」）。

2つのモードの違いは、内容にあり、見た目の構成にはありません。以下のHTMLの骨組みはどちらにも適用します。PRごとのレビュー状況のピル、コミットの原因タグ、スキップした指摘事項の行といったモード固有の内容は、FINALモードの場合のみ、両モードに共通する同じPRスタックセクション内に表示します。

語り口 — 読み手を案内するように説明する

表やコールアウトを並べたページは素早く流し読みできますが、内容を深く理解するのは困難です。レビュー担当者は事実を得られても、それらをつなぐ流れが見えません。そこで、構成を整えるだけでなく、レポートを提出するのではなく、作成者が同僚に変更内容を説明するように、ブリーフ自体を読み物として仕上げてください。

• TL;DRは簡潔な1〜2文にします。出荷した（または提案している）ものと、特に注意して見るべき唯一の点を述べます。冒頭に説明段落は置きません。簡潔にまとめてください。
• 各セクションは、その後に続く内容を位置づける、平易な文章の1文で始めます。その下に、詳細な表、コールアウト、またはツアーの項目を配置します。
• コードツアー（ステップ5）はブリーフの中心であり、物語のように説明するセクションです。各項目では、まずそのコードが重要である理由を簡潔に説明し、続けて実際のコードを示します。
• 断片的で短い表現より、平易でつながりのある文章を優先します。

説明文は話の流れをつなぐために使い、長さを増やすためには使わないでください。流し読みする人は構成から必要な情報を得られ、冒頭から順に読む人は一貫した流れを追えます。

ステップ 1 — 資料を集める

トランクブランチ（通常は main）を特定します。そのブランチとの差分をすべて把握するため、次の情報を集めます。

• トランクとの差分と統計情報 — git diff <trunk>..HEAD --stat と、重要なファイルの完全な差分。
• ブランチ／スタック上のコミット — git log <trunk>..HEAD --oneline に加え、コミットメッセージ全文（git log <trunk>..HEAD --format=fuller または git log <trunk>..HEAD --format=%B）も確認し、作成者が記した説明文を拾い出せるようにします。多くのコミットは件名だけですが、それで問題ありません。本文は任意として扱います。ただし、コミットに意味のある本文（Why: の段落、根拠、トレードオフに関する注記）がある場合、その変更部分についての作成者自身の説明なので、概要に含めます。
• 未追跡ファイル（特に DRAFT モード）— 新規ファイルには最も重要なコードが含まれていることが多く、見落としやすいものです。git status --porcelain を実行してから、ファイルを直接読みます。
• 提案された PR スタックがある場合 — 現在の会話コンテキスト、または proposed-pr-stack.md（リポジトリのルートと .briefs/ を確認）にある場合があります。存在しない場合は、スタックのセクションを省略します。作り上げてはいけません。
• 実際の PR スタックがある場合（FINAL モード）— gh pr list --head <branch> と、PR ごとに gh pr view <num> --json title,body,state,commits,reviews,reviewDecision を実行します。Graphite を使っている場合は、gt log short も実行します。
• レビューのスレッド（FINAL モード）— gh pr view <num> --comments と、インラインのレビューコメントを確認するために gh api repos/{owner}/{repo}/pulls/{num}/comments を実行します。コミットメッセージと指摘事項を相互参照し、指摘事項からコミットへの対応関係をまとめます。

コードツアーに表示するファイルを選ぶ際は、生成ファイルを除外します。 これらはノイズになるだけで、解説に役立ちません。よくある例を以下に示します。リポジトリに応じて調整してください。

• **/*.api.md、**/api-report* — 生成された API サーフェスレポート
• apps/docs/content/reference/**、生成されたリファレンスドキュメント
• yarn.lock、package-lock.json、pnpm-lock.yaml
• 自動生成される **/CHANGELOG.md
• スナップショットファイル、スキーマダンプ、バンドル済みアセット — 「DO NOT EDIT」ヘッダーや、リポジトリに再生成コマンドがあるもの

これらも簡潔なファイル一覧には含めてもかまいませんが、ツアーの対象や注目ポイントにはしないでください。

既存の概要ファイルはすべて無視します。 .briefs/ には以前の実行や別の作業で作成された概要がすでに存在する場合があります。これらは入力として使用してはいけません。古かったり、内容が現状にそぐわなかったりする可能性があります。読まないでください。

ステップ 2 — 変更を重要度で分類する

何かを書く前に、見つけた変更を重要度の段階に分けます。この順序がページ構成を決めます。

ティア 1 — 重要度が高い（最初に扱い、見落としようがない形で示す）：

• 新規または変更されたサービスエンドポイント／API ルート／ルートハンドラー／サーバーアクション — 新たな機能範囲を追加するもの。
• 認証、認可、アクセス制御、セッション、シークレット、CORS — 誰が何をできるかに関わるもの。
• データベーススキーマの変更 — 新しいテーブルやカラム、型の変更、制約、インデックス、削除。
• 新しい外部依存関係、変更された設定／環境変数、破壊的または取り消し不能なもの。

ティア 2 — 機能を支える中核ロジック： ビジネスロジック、データフロー、API レスポンスの形式、ステートマシン、レビュー担当者が実際に理解する必要がある関数。

ティア 3 — 通常の変更： UI の微調整、リファクタリング、テスト、ドキュメント、書式設定。

該当する項目がないティアがある場合は、該当なしであることを明記します（「認証またはスキーマの変更はありません」など）。重要度の高い変更がないこと自体も、有益な情報です。

ステップ 3 — スキーマの変更は行単位で扱う

ほとんどの差分において、スキーマの変更は最も危険でありながら、最も簡単に見過ごされてしまうものです。スキーマのソース（schema.prisma、db/schema.ts、マイグレーションファイル、モデル定義）が変更されている場合、要約してはいけません。変更を一つずつ確認してください。

個々の変更ごとに 1 行を設けます。テーブル／モデル、正確なフィールド名、変更前 → 変更後、NULL 許容性、デフォルト値、インデックス／制約への影響、実際に生じる影響（「既存の行のバックフィルが必要」「この削除でデータが失われる」「データが入っているテーブルでは、デフォルト値なしの NOT NULL 追加は失敗する」）を記載します。レビュー担当者がこのセクションだけでスキーマの差分全体を監査できるようにしてください。

ステップ 4 — コードツアーを計画する

ここが概要の要となる部分で、最も適切に仕上げるべきセクションです。コードツアーは、変更箇所を作者が同僚に説明するときのように順を追って巡る、番号付きの「立ち寄りポイント」の並びです。基本となる考え方は Graphite Code Tours に由来しています。レビュー担当者に PR の説明、コメント、散在する差分の間を行き来させるのではなく、物語を実際のコードに沿った一続きの経路として示します。各立ち寄りポイントでは、短い説明文と、説明対象となる具体的なコードの差分を組み合わせます。これにより、レビュー担当者は変更を理解するためにコンテキストを切り替える必要がありません。

計画のルール：

• ファイル単位ではなく、理解しやすい順に並べます。 あるファイルで新しい型を定義し、別のファイルで使用する場合は、定義を先に、使用箇所を後にします。機能の流れに沿ってください。
• 大きな変更では、セクション見出しの下に立ち寄りポイントをまとめます。 立ち寄りポイントが 12 個ある平坦なリストはたどりにくくなりますが、同じ 12 個を 3 つのセクション見出し（「バックエンドサービス」「ワークフローの接続処理」「管理 UI」）の下にまとめると、すぐに全体を見渡せます。Graphite Code Tours の UI では、この階層構造（親セクションの下に子の立ち寄りポイントをネストする形式）が使われているため、概要も同じ構造にします。小規模な変更（立ち寄りポイントが合計 6 個以下）なら、単一の平坦なリストでもかまいません。
• すべてのファイルを巡る必要はありません。 重要なファイル、つまりリスクの高い領域、コアロジック、微妙な点を含む箇所を扱います。一般的な変更では 5～10 個の立ち寄りポイントを目安にし、必要ならグループ化します。小さな変更なら少なく、広範囲に及ぶ変更なら、グループ化したうえで多めにします。グループ化されていない立ち寄りポイントが 20 個も並びそうなら、ツアーではなくファイル一覧になっています。優先順位を付け直すか、グループ化してください。
• 1 つの立ち寄りポイントにつき、焦点となるアイデアは 1 つです。 通常は 1 つのファイルまたは関数を中心にしますが、同じアイデアに関する小さな変更を 3 つまとめてもかまいません（例：「index.ts、types.ts、public.ts での型の再エクスポート — 新しい Foo 型を接続するだけです」）。
• 各立ち寄りポイントには、説明だけでなく実際のコードを示します。 意味のある変更箇所（多くの場合 5～30 行）を選びます。周辺の不要な部分は取り除いてください。新規ファイルのみの場合は、ファイル全体ではなく、意味のある部分を示します。
• 「何を」だけでなく「なぜ」を説明します。 ページ上のコードから、何が変更されたかは分かります。説明文では、その理由、解決する問題、対応するエッジケース、採用しなかった代替案を補足します。差分を見れば分かることしか説明できないなら、その立ち寄りポイントを設ける意味はありません。
• 定型的な変更は省きますが、触れたことは示します。 import の変更ごとに立ち寄りポイントを設ける必要はありません。まとめの立ち寄りポイントで「残りの変更は型の再エクスポートとテスト用フィクスチャです」のように簡潔に触れてください。

ステップ 5 — 1 ページの HTML を作成する

自己完結型の .html ファイルを 1 つ作成します。CSS はすべて <style> ブロック内に記述し、外部リクエスト、JS フレームワーク、取得するフォントは使用しません。ディスクからそのまま開ける必要があります。

構成上の優先事項

ページは情報量が多くなりますが、順序は厳守してください。この順序は変更できません。 特定の変更を別の順序で説明したほうが読みやすいと思っても、順序を入れ替えないでください。順序を入れ替えた過去の概要（PR スタックをコードの解説より後に置いたものや、単一 PR の概要でメタ情報グリッド内に PR 番号を隠したもの）は、いずれもレビュー担当者に受け入れられませんでした。最初の画面だけを読むレビュー担当者にも、タイトル、モード、TL;DR、PR スタック、重要度の高い注意事項が見える必要があります。 それ以降の内容はスクロールして確認できるようにします。

セクションは、次の順序を厳守してください。

1. ヒーロー — スリムで簡潔に。 最初のビューポートの約1/4以内に収めます。
   • タイトル行：ブランチ名／スタック名＋視覚的に目立つモードピル — 塗りつぶしの色付き背景、白い文字、本文より大きな文字（例：DRAFT はアンバー、FINAL · review clean は緑、FINAL · 2 findings open は赤）。読者が部屋の反対側からでも現在のモードを把握できるようにします。落ち着いたタグ風のチップでは不十分です。
   • 1～2文の TL;DR。 ここに長い説明段落は置きません。レビュアーが最も知る必要のあることを1つだけ伝えます。
   • コンパクトな横並びのメタ情報欄：トランク、変更ファイル数、+/−、コミット数、生成タイムスタンプ。
2. PR スタック — 目立つ位置、ページ上部に配置し、内容を自己完結させます。 スタック（提案中または実在するもの）がある場合はここに置き、視覚的に区別します。4列のメタグリッドに埋もれさせてはいけません。このセクションにはPR ごとのコミット／指摘履歴も含めます — ページ下部に別の「PR の変遷」セクションは設けません。各 PR についてレビュアーが知る必要のあること — 何であるか、何が含まれるか、どのような経緯をたどったか — はすべてそのカードにまとめます。縦に並べた PR カードが適しています。各カードは次の要素を含む小さな複合ブロックです。
   • ヘッダー行。 順番（1/3）、PR 番号／スラッグ、1行の概要、サイズ（例：+312 / −44 · 8 files）、ステータスピル（open／merged／draft）。FINAL モードでは、レビュー状態ピル（review-clean／2 findings／1 skipped）も表示します。
   • コミットタイムライン — カードの本文。 PR 上のすべてのコミットを時系列順に並べた縦リストです。各行には短縮 SHA、等幅フォントの件名、そして（FINAL モードでは）原因タグ — ベースラインには initial、後続のコミットには review finding／user steering／other（CI 修正、スタック再構成に伴う修正、仕上げ） — を表示します。コミットメッセージとレビューのスレッドを照合して後続コミットの原因を特定し、すべての後続コミットに原因を付けます。
   • 作成者が説明を書いている場合は、コミットの説明も表示します。 コミットの件名行の下に、コミットメッセージ本文（件名の後の行）を、控えめな色の小さなテキストで表示します。改行は保持しますが、コードとしては表示しません。これは作成者自身による変更内容の説明であり、差分だけではわからない 理由 が含まれていることもよくあります。本文が空、または定型文だけの場合は省略します — 件名を言い換えただけの Why: の1行、AI 帰属情報のトレーラー、Co-Authored-By の行などが該当します。基本は情報を絞ることです。情報を補う本文だけを展開し、それ以外は件名のみの行にします。コミット数が多く、意味のある本文が少ない PR では、自然と数行だけを展開したコンパクトなリストになります。
   • スキップされたレビュー指摘（FINAL モード）。カード内の独立した視覚的に目立つ行として表示します — 警告色を使い、指摘の概要とスキップした理由を記載します。PR の履歴の一部なので、別の付録ではなく PR のカードに含めます。
   • PR が1つだけの場合も、このセクションを表示します — メタ情報欄に隠れた数値ではなく、タイムライン全体を含む PR カードを表示します。レビュアーが探し回らなくても、「これは PR #22、open、review-clean、コミット3件、指摘 X に対応した後続コミット1件」と把握できるようにします。
   • まだ PR がなく、かつ提案中のスタックも本当にない場合は、このセクションを省略し、TL;DR にその旨を1度だけ記載します（「作業ツリーのみ — スタックはまだ提案されていません。」）。その場合、作業ブランチ上のコミットは TL;DR の下に、同じ行形式を使った1つのタイムラインブロックとして記載し、コミット本文が失われないようにします。
3. 重要な変更点のコールアウト。 色付きコールアウトを小さなグリッドに並べます — エンドポイント、認証、スキーマ、依存関係、設定、破壊的操作など。各コールアウトは1～2行で、対象領域、変更内容、注意点を記載します。重要な変更がない場合は、その旨を示す中立的なコールアウトを1つ表示します — 変更がないことも情報です。
4. エンドポイント監査（変更によって複数のルート／サーバーアクション／API サーフェスが追加または変更される場合）。コールアウトではなく専用のテーブルを使用し、列は Route / Inputs / Success behavior / Failure behavior / Side effect / Auth とします。エンドポイントごとに1行設けます。バックエンドの変更では新しいサーフェスが通常、最も重要な変更点となるため、このセクションはスキーマの解説より上に配置します。変更対象のエンドポイントが0件または1件の場合は、このセクションを省略します — （3）のコールアウトで十分です。
5. スキーマの解説（該当する場合）。ステップ3の行ごとのテーブルを使用します。
6. コードツアー。 ステップ4の見どころを掲載します。見どころが約6件を超える場合は、セクション見出しの下にグループ化します（ステップ4を参照）。各見どころは次の要素を含む小さな複合ブロックです。
   • 見どころ番号＋短く内容を表すタイトル（例：3. Row-locking the delete path）。番号があればレビュアーが特定の見どころを参照しやすく、内容を表すタイトルがあれば目次をひと目で確認しやすくなります。
   • 等幅フォントのファイルパスと、任意で「依存先／呼び出し元」タグ。
   • このコードが何をするか、なぜ重要かを説明する1～3文。
   • インラインコードまたは差分スニペット — 下記の表示ルールを参照してください。コードを含まないコードツアーの見どころは載せる価値がありません。コードを追加するか、別の箇所の説明文に統合してください。
   • 任意：ライフサイクル／フロー図。複数ステップの状態遷移（購入 → 付与 → 消費、キュー → 拡充 → 公開、下書き → レビュー → 承認）を導入する変更に使用します。インライン CSS を使い、矢印でつないだボックスの横並びとして表示します — SVG や JS は使用しません。ブリーフ1件につき図は最大1つとし、独立したセクションではなく、関連するコードツアーの見どころの中に配置します。
   • コードツアーの見どころが8件以上あるブリーフでは、固定表示のツアー目次を追加します。 左側に position: sticky の列（または狭いビューポート向けに上部に固定するミニナビゲーション）を設け、すべての見どころのタイトルを #anchor リンクで一覧表示します。グループごとの見出しの下で子項目をインデントして、グループを区別します。JS は使わず、固定表示の CSS と名前付きアンカーだけを使用します。これにより Graphite のツアーが移動しやすくなります。これがないと、長いブリーフでは順番にスクロールし続ける必要があります。
7. ファイル一覧。 ページの一番下にコンパクトに配置します。ファイルごとに1行、簡潔な説明を付けます。生成ファイルもここに記載できます。

インラインコードと差分のレンダリング（JavaScript とフォントなし）

ツアーの各ステップには、疑似コードや要約ではなく、実際のコードを表示してください。構文ハイライトライブラリは使わず、シンプルな手作りの方法を使います。

• スニペットは、等幅フォントのスタックを指定した <pre><code> で囲みます。
• 差分スニペットでは、各行の先頭の +／-／ 文字に基づいて、各行を <span class="add">、<span class="del">、または <span class="ctx"> で囲みます。CSS で各クラスに、行全体に広がる淡い緑／赤／中立色の背景を設定します。
• 必要に応じて、@@ のハンクヘッダー行を <span class="hunk"> で囲みます（控えめな色）。
• コンテキストとして表示する差分ではないソースコード（関数やクラス）には、行ごとのクラスを付けず、中立色のパネル背景と等幅フォントを指定した単一の <pre><code> ブロックを使います。
• ファイルパスはスニペットの上に表示し、スニペット内には入れないでください。スニペットは適度な長さ（ステップごとに 5～30 行）にしてください。関数が長い場合は、意味のあるハンクを表示し、省略した部分は説明文でつないでください（「…引数の検証は省略…」など）。
• Graphite Code Tours のように、ハンクの間には変更のない領域を示すマーカーを使ってください。同じファイル内の、連続していない複数のハンクが一つのステップに含まれる場合は、スタイルを適用した ↕ 12 lines unchanged のようなマーカーを、独立した行に挿入します（控えめな色、破線の境界線、小さめの文字）。これにより、一つのステップで長いファイルの両端を連続しているかのように見せずに表示でき、レビュー担当者に非表示のコード行数を正確に伝えられます。
• 長いトークンの折り返し：コードブロックに white-space: pre-wrap; word-break: break-word; を指定し、長い行でレイアウトが崩れないようにします。

ビジュアルの仕上がり

これはマネージャーの目に触れるため、ありきたりではなく、意図の伝わる見た目にしてください。明確な文字の階層、目的を持った色使い（優先度、重大度、レビュー状況、追加／削除）、コードとパスに使う等幅フォント、そして適切な余白のリズムを意識します。ページの最大幅は 1100～1200px 程度を目安にしてください。汎用的な AI 生成風の見た目は避けます。frontend-design スキルが利用可能なら、その原則を活用してください。

ヒーロー部分はスリムに保ち、カードで埋め尽くさないようにしてください。視覚的な重心は主に、PR スタックとコードツアーに置きます。

ステップ 6 — 保存して開き、セルフチェックする

リポジトリのルートにある .briefs/ ディレクトリにファイルを保存します。命名規則：

• DRAFT モードの場合は draft-brief-<slug>.html。
• FINAL モードの場合は final-brief-<slug>.html。

<slug> にはブランチ名か変更内容を表す短いスラッグを使い、他の作業のブリーフとファイル名が重複しないようにします。ブリーフがコミットされないよう、.briefs/ がバージョン管理の対象外になっていることを確認してください。追跡対象の .gitignore を編集するのではなく、ローカルで未コミットの除外ルールを使うのが望ましいです。その後、ユーザーのブラウザーでブリーフを開きます。

引き継ぐ前に、ブリーフが目的に沿っているか確認します：

• 最初の画面に表示される範囲だけを読んだレビュー担当者が、影響の大きい変更をすべて挙げ、PR スタックを確認できますか？
• モードのピルは、DRAFT と FINAL の違いが一目でわかるほど目立っていますか？
• TL;DR は段落ではなく、1 文か 2 文に収まっていますか？
• PR Stack セクションは（PR が 1 件だけでも）含まれており、影響の大きい変更のコールアウトより前にありますか？
• 各 PR カードでは、作成者がコミットメッセージ本文を書いている場合はそれを表示し、書いていない場合は空の本文ブロックを出さずにいますか？
• セクションの順序（Hero → PR Stack → High-stakes → Endpoint Audit → Schema → Code Tour → File Index）を正確に守っていますか？
• Code Tour の各項目には、説明だけでなく実際のコード（差分またはソース）が表示されていますか？
• ツアーはファイル名順ではなく、理解しやすい順に並んでいますか？
• スキーマの変更をすべて、行ごとに説明していますか？
• （FINAL）各 PR カード内で、すべてのフォローアップコミットの原因が示され、スキップされたすべての指摘が警告色の独立した行として表示されていますか？いずれも別の進化セクションではなく、カード上にありますか？
• 存在しないスタック／レビューセクションをあると主張していませんか？または、存在するものを省略していませんか？
• スタック全体の孤立チェック。 各 PR カードについて、新たに追加されたトップレベルの関数／コンポーネント／エクスポートを列挙し、それぞれが同じ PR の差分内に少なくとも 1 つの呼び出し元を持つことを確認します。孤立した項目（PR N で追加され、PR N+1 で初めて使われるもの）があれば、追加した PR のカード上に警告色の行として表示します。これは、その PR が「先回りして」コードを追加したことを意味します。そのシンボルは、初めて使われる PR に移動する必要があります。スタックの Mermaid／依存関係グラフが描画されている場合は、孤立ノードは PR 内の他の要素から入るエッジを持たないノードとして現れるため、明示的に指摘してください。
• 余分な部分はありませんか？あれば簡潔にします。

最後に、ブリーフの準備ができたこと、保存場所、選択したモードをユーザーに伝えます。