frontend-handoff

バックエンドの変更が入ったとき、フロントエンド開発者が何よりも先に知りたいのは、自分のコードに手を加える必要があるか？です。このスキルは、まず判定を示し、次に契約上の根拠、ペイロードの例、チェックリストで裏付けます。チケットやチャットに貼り付けられる、ひとまとまりのブロックとしてまとめます。

変更を判断する前に、その内容を読んでください。ブランチ名から判定を推測するのは、このスキルの価値を損なう失敗の典型です。

引き継ぎは、ユーザーが使っている言語で書いてください。これには、セクション見出し、表の列見出し、「はい／いいえ」のようなラベルも含まれ、本文だけではありません。以下のテンプレートは構造のひな形として英語で書かれているだけなので、記入済みの内容だけでなく、見出しとラベルもすべて翻訳してください。コード、ルート、フィールド名、列挙値、HTTP ステータスは、ソースの言語のまま変更しないでください。

範囲

コンテキストの提示のみです。フロントエンドの作業は別のタスクです。このブロックでは、フロントエンド側が何を判断する必要があるかを説明し、修正案は示しません。フロントエンドのコードは決して書かないでください。

手順

1. 変更内容を特定する

引き継ぎには、変更の両面が必要です。つまり、意図（何をリリースする予定だったか）とコード（実際に何がリリースされたか）です。ビルドのことを覚えていない新しいセッションから始めることを想定し、リポジトリから両方を読み取ってください。

意図。 ユーザーが提示したもの（機能フォルダー、仕様書のパス、ブランチ、PR、コミット、変更ファイル、または文章による説明）を確認してください。機能フォルダーが最も多くの情報を含みます。まず機能全体について SPEC.md を読み、次に tickets/NN-*.md をすべて読んでください。チケット本文には約束された動作が記載され、チェック済みの受け入れ条件はリリースされた内容を示しています。何も提示されていない場合は、これらの形式を挙げて1つだけ質問し、その後は作業を続けてください。

コード。 /review-axes と同じ方法で、固定点を定めて差分を確認してください。

• コミット済みの作業 → git diff <fixed-point>...HEAD（3点ドット）と git log <fixed-point>..HEAD --oneline。固定点には、ユーザーが指定したものを使います。何も指定されていない場合は、デフォルトブランチとのマージベースを使います。
• 未コミットの作業 → 新しいファイルが表示されるように git add -N . を実行し、その後、通常の git diff を実行します。

差分が空の場合は、固定点の指定が誤っています。その旨を伝えて確認を求め、チケットだけを根拠に引き継ぎを書かないでください。

次に、契約そのものの信頼できる情報源を確認してください。ルート定義、リクエストのバリデーション、レスポンスのシリアライザー、機能テストを読みます。レスポンスボディを検証するテストは、仕様書を含むあらゆる説明より優先されます。

すべてのチケットを差分に照らして確認できたら完了です。それぞれのリリース済み動作をコードまでたどり、差分に含まれないチケットは、リリース対象外として引き継ぎに明記してください。リリース済みだと暗黙に扱ってはいけません。

2. このリポジトリのレスポンス形式を把握する

契約の判断は、レスポンスの形をどれだけ理解しているかに左右されます。プロジェクト固有の用語を把握するため、GLOSSARY.md と CLAUDE.md を読み、その後、シリアライザー／リソースと、成功する機能テストを1つ読んで、以下を確認してください。

• 標準的な成功レスポンスの形式（ラッパーキー、ページネーション／メタデータの配置）
• 派生状態の所在（他のシステムや集計値から計算されるフィールド、および独自のステータスを持つサブオブジェクト）
• エラーレスポンスの形式と、フロントエンドが分岐処理に使うことが確認されている HTTP コード
• 互換性があるように見えても異なるドメイン状態（ソフト削除済み、確定済み、キャンセル済みなど）

レスポンス形式を記憶から書けて、変更によって値が変わり得る派生状態フィールドを挙げられたら完了です。

3. 契約を分類する

以下の項目ごとに、変更あり／変更なしを判定し、根拠を確認してください。

• 追加、名称変更、削除されたルート
• 追加、名称変更、削除、型変更、または新たに null 許容となったフィールド
• 追加、削除、または再定義された列挙値やステータス値
• フロントエンドが分岐処理に使う HTTP コードとエラーメッセージ
• 動作のみの変更：パスと形式は同じで、エッジケースのレスポンスが異なるもの

契約の表の各行について、はい／いいえの判定と、それを裏付けるファイルまたはテストを示せたら完了です。

4. 判定を選ぶ

該当する条件のうち、最も強いものを1つだけ選びます。

• 変更必須：互換性を損なう契約変更、またはユーザーが利用できるようにするためにフロントエンドが取り込む必要のある新機能です。
• 変更すべき：契約は同一ですが、現在のフロントエンドの動作が誤っているか無駄になっています。移動したバックエンドのルールを再現するローカルロジック、バックエンドの変更によって不要になった回避策、終端状態ではない状態を終端状態として扱う画面、派生状態に影響する変更後も再検証しないキャッシュなどが該当します。
• 変更不要：契約は同一で、現在のフロントエンドの動作も引き続き正しい状態です。

ガードレールが2つあります。契約を変更せずに新しい動作を追加する場合、判定は変更すべきまでです。仕様に契約、スキーマ、列挙型の変更がないと記載されているなら、「変更必須」は誤りです。また、バックエンドとの対称性は理由になりません。フロントエンドの変更が妥当なのは、ユーザーに見える動作、またはフロントエンドが読み取る契約に基づく場合だけです。

判定を決定づけた条件が1つだけ明記されていれば完了です。

5. ブロックに記入する

以下のテンプレートに記入します。内容を無理に膨らませるのではなく、該当しないセクションには N/A と記入します。実在しないルートやフィールドを作り出すより、空欄のほうが適切です。

6. 引き継ぎ資料を保存する

判定が変更不要の場合、保存は不要です。ファイルもテンプレートブロックも作成せず、チャットでは判定の行と理由を示す1文だけを返して終了します。

それ以外の場合は、記入済みのブロックを .scratch/<feature-slug>/frontend-handoff.md に保存します。ディレクトリが存在しない場合は作成してください（.scratch/ の構成については docs/agents/issue-tracker.md を参照）。<feature-slug> は、手順1で指定された機能フォルダーがあればそこから導きます。なければ、テンプレートのタイトルにある短い機能名をスラッグ化します。そのパスに引き継ぎ資料がすでにある場合は上書きします。同じ変更についての資料であり、新しい変更ではありません。事前に許可を求めず保存してください。

7. 提出する

最初に実行環境を確認します。printenv CLAUDECODE は、Claude Code では 1 を返し、それ以外では空になります。

• Claude Code：ファイルが提出物となるため、内容を再掲しないでください。判定の行と保存先パスだけを返し、それ以外は何も書きません。
• それ以外：判定の行、ブロック全体、最後に保存先パスを1行で返します。

出力テンプレート

## Frontend context: <short feature name>

### Verdict
**<Must change | Should change | Nothing required>**: <one sentence>.

### What the backend changed
- …

### API contract
| Item | Changed? | Detail |
|------|----------|--------|
| Routes | Yes/No | … |
| Envelope / fields | Yes/No | … |
| Enums / statuses | Yes/No | … |
| HTTP codes / known errors | Yes/No | … |

### New behaviour under the same contract
- Before: …
- Now: …

### Frontend impact
| Area | Change needed? | Action |
|------|----------------|--------|
| Types / envelope parsing | … | … |
| Screens & states (e.g. states treated as terminal) | … | … |
| Request payload construction (POST/PUT/PATCH) | … | … |
| Cache, lists, invalidation | … | … |
| 4xx handling | … | … |
| Flows out of scope | No | … |

### Payload / response examples
\`\`\`json
{ … }
\`\`\`

### What the frontend should stop assuming
- …

### Checklist
- [ ] …

回避策一覧

バックエンドの変更によって不要になることの多い、フロントエンドの回避策です。変更によって原因が取り除かれた場合、それぞれ変更すべきとなります。回避策の名前と、不要になったことを示す根拠を明記してください。

• バリデーションエラーを避けるために、未変更の履歴やコレクション全体を再送信する
• バリデーションを回避するために、更新ペイロードからフィールドを取り除く
• 終端状態に見えるだけの状態が原因で画面が停止する
• バックエンドが返すようになったルールをクライアント側で再計算する
• 変更後も古い派生状態を返し続けるキャッシュ