frontend-handoff

后端有一项变更，前端开发者首先需要知道一个答案：我必须修改代码吗？ 此技能会先给出一个结论，再用契约证据、负载示例和检查清单支撑结论，汇总成一段内容，方便他们粘贴到工单或聊天中。

先阅读变更，再做判断。根据分支名称推断结论，是会让此技能失去价值的一种错误。

交接内容应使用用户正在使用的语言：这包括章节标题、表格列标题，以及“Yes/No”之类的标签，而不只是正文。下面的模板仅以英文作为结构框架；其中的每个标题和标签都要翻译，不能只翻译填入的内容。代码、路由、字段名、枚举值和 HTTP 状态码保留源语言原样。

范围

仅提供背景信息。前端工作是单独的任务：此内容描述前端必须作出的判断，而不是前端需要实施的补丁。绝不编写前端代码。

步骤

1. 确定变更范围

交接内容需要包含两部分：意图（原本计划交付什么）和代码（实际交付了什么）。假设当前会话是全新的，且不记得构建过程，因此要从仓库中读取这两部分。

意图。 获取用户提供的任何信息：功能目录、规格文件路径、分支、PR、提交、变更文件或文字描述。功能目录包含的信息最丰富：阅读 SPEC.md 了解整个功能，然后阅读每个 tickets/NN-*.md；工单正文说明承诺实现的行为，已勾选的验收标准说明实际交付的内容。如果用户没有提供任何信息，询问一个问题，列出这些信息形式，然后继续。

代码。 确定一个固定基点并与其比较差异，方式与 /review-axes 相同：

• 已提交的工作 → 执行 git diff <fixed-point>...HEAD（三点）和 git log <fixed-point>..HEAD --oneline；固定基点是用户指定的基点，若用户未指定，则使用与默认分支的合并基点
• 未提交的工作 → 执行 git add -N .，让新文件也出现在差异中，然后执行普通的 git diff

差异为空意味着固定基点选错了：指出这一点并询问，而不要仅根据工单编写交接内容。

然后阅读契约本身的事实来源：路由定义、请求验证、响应序列化器和功能测试。任何断言响应正文的测试，其优先级都高于任何文字描述，包括规格文档中的描述。

完成标准：根据差异核对每个工单；每个已交付的行为都能追溯到代码，并在交接内容中注明差异未覆盖的工单属于本次未交付范围，不能默认为已交付。

2. 了解此仓库的响应结构

契约判断的准确性取决于你对响应结构的理解。阅读 GLOSSARY.md 和 CLAUDE.md，了解项目的领域术语；然后阅读序列化器／资源和一个通过的功能测试，确认：

• 标准成功响应封装（包装层键、分页／元数据的位置）
• 派生状态所在位置（由其他系统或聚合计算出的字段，以及哪些子对象有自己的状态）
• 错误响应封装，以及前端已知会据此分支处理的 HTTP 状态码
• 看似可互换、实际并不相同的领域状态（软删除与最终确定与取消）

完成标准：你能凭记忆写出响应结构，并指出此次变更可能影响的派生状态字段。

3. 分类契约

针对以下每一项，判断是否有变更，并保留证据：

• 新增、重命名或移除的路由
• 新增、重命名、移除或重新设置类型的字段，以及新改为可空的字段
• 新增、移除或重新定义的枚举值或状态值
• 前端会据此分支处理的 HTTP 状态码和错误消息
• 仅行为发生变化：路径和结构不变，但边缘情况下的响应不同

完成标准：契约表中的每一行都标明是或否，并附上证明结论的文件或测试。

4. 选择判定结果

只能选择一项，并以符合条件中最有力的一项为准：

• 必须更改：破坏性契约更改，或新增了前端必须使用、才能向用户提供的功能。
• 应该更改：契约不变，但当前前端行为已错误或浪费资源：后端规则已迁移、前端仍在镜像这些规则的本地逻辑；后端刚刚使之不再必要的变通方案；将非终态读取为终态的界面；在更改派生状态的变更后从不重新验证的缓存。
• 无需更改：契约不变，且当前前端行为仍然正确。

两项防护规则。如果契约不变时行为有变化，判定最高只能是应该更改：如果规范说明契约、架构或枚举没有变化，那么判定为“必须更改”就是错误的。与后端保持对称并非理由：只有用户可见行为或前端读取的契约，才能成为前端更改的依据。

完成标准：判定结果明确指出起决定作用的唯一条件。

5. 填写区块

填写下面的模板。对于不适用的部分，标记为 N/A，不要硬凑内容：虚构路由或字段比留空更糟。

6. 保存交接文档

如果判定结果是无需更改，则跳过保存：不创建文件，也不填写模板区块。在聊天中只回复判定结果和一句理由，然后结束。

否则，将填写好的区块保存到 .scratch/<feature-slug>/frontend-handoff.md；如果目录尚不存在，则创建目录（.scratch/ 的目录结构请参见 docs/agents/issue-tracker.md）。如果第 1 步中确定了功能文件夹，则据此生成 <feature-slug>；否则，将模板标题中的功能简名转换为 slug。如果该路径下已存在交接文档，则覆盖：它描述的是同一项更改，而非新更改。无需事先征求许可，直接保存。

7. 交付

先检查运行环境：printenv CLAUDECODE 在 Claude Code 中返回 1，在其他环境中返回空值。

• Claude Code：文件即为副本，不要重新输出。只回复判定结果和已保存的路径，不要添加其他内容。
• 其他环境：依次输出判定结果、完整区块，以及单独一行的已保存路径。

输出模板

## 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
- [ ] …

变通方案目录

后端更改经常会使前端变通方案不再必要。如果更改移除了变通方案的成因，则每项都应判定为应该更改：指出该变通方案，并说明其不再必要的依据：

• 为规避验证错误而重新发送未修改过的历史记录或完整集合
• 为通过验证而从更新负载中剔除字段
• 因某个状态看起来像终态而冻结的界面
• 在客户端重新计算后端现在会返回的规则
• 在变更后仍提供过时派生状态的缓存