该技能以 API Handoff 模式运行，目标是在后端 API 工作完成后，产出一份可直接复制使用的交接文档，让前端开发者或其 AI 助手获得完整的业务与技术上下文，从而正确、自信地构建界面与集成，而不必再向后端询问。
用途：当后端完成了端点、DTO、校验和业务逻辑后，使用本模式生成交接文档。若 API 较为简单（仅 CRUD、无复杂业务逻辑、校验规则直观），可跳过完整模板，直接提供端点、方法以及示例请求与响应 JSON，其余部分由前端自行推断。
使用方式：先收集上下文，确认功能名称、相关端点、DTO、鉴权规则和边界情况；然后在 .claude/docs/ai/<feature-name>/api-handoff.md 创建或更新交接文件，若在反馈后重跑则递增迭代后缀（-v2、-v3 等）；接着按模板填写各节；最后复核载荷是否符合实际 API 行为、鉴权范围是否准确、枚举与校验是否反映后端逻辑。输出为单个 markdown 块，内容紧凑，不写空话或重复内容。运行时无聊天输出，只在交接文件中写入最终 markdown，不在聊天中回显；若平台要求确认，则引用文件路径而非粘贴内容。
文档结构包括：业务上下文（2 至 4 句说明解决的问题、使用者、重要性及前端需理解的领域术语）；端点（每个端点列出 METHOD 与路径、用途、鉴权、请求 JSON、成功响应、错误响应与备注，涵盖边界情况、限流、分页、排序等非显而易见信息）；数据模型与 DTO（字段类型、可空性、枚举、业务含义，附前端类型示例）；枚举与常量（值、含义、显示标签）；校验规则（前端应镜像的必填、最小最大值、格式、条件规则）；业务逻辑与边界情况（逐条列出非显而易见的行为或约束）；集成说明（推荐流程、乐观 UI 是否安全及原因、缓存与失效触发、实时机制如 websocket 事件或轮询间隔）；测试场景（正常路径、校验错误、未找到、权限拒绝等，可作为验收标准）；待解决问题与 TODO（未决事项、待产品决策或需前端输入的内容，若无则省略该节）。
规则要求：只产出交接 markdown，不输出聊天内容；表述精确，给出类型、约束和示例而非模糊描述；必要时包含真实示例载荷；主动暴露非显而易见的行为；记录后端做出的权衡或假设；保持可扫读，使用标题、表格、项目符号和代码块；除非与集成直接相关，不写后端实现细节（文件路径、类名、内部服务）；若有未完成或待定内容，须明确说明。
适用场景：后端完成一组 API 端点、DTO、校验与业务逻辑后，需要交给前端进行界面与集成开发时；或用户要求生成 API 交接文档时。限制：文档只写入交接文件，不在聊天中展示；若信息不完整应显式标注为 TBD，不编造；对于简单 API 可不使用完整模板。