API交接文档生成Skill：一次生成结构化交接文档，让前端不再追问后端
- 它是什么：一个面向后端开发者的 AI 技能，把已完成的 API 工作自动整理成一份可直接交给前端（或前端 AI）的结构化 Markdown 交接文档。
- 核心痛点：接口做完了但没人写文档，前端只能反复提问“这个字段能空吗”“403 什么时候返回”“状态枚举有哪些”，沟通成本高、集成反复返工。
- 关键差异：它不是普通的接口导出工具，而是把业务上下文、枚举语义、验证规则、边界情况、集成流程、测试场景一次性写清楚——这些恰恰是 Swagger 自动生成不出来、但前端最需要的内容。
- 使用方式：说一句“创建交接”“记录API”或“前端交接”即可触发，文档自动写入
.claude/docs/ai/<功能名称>/api-handoff.md，支持-v2、-v3版本迭代。 - 适合谁：后端开发者、全栈工程师、需要把接口交给外部团队或前端 AI 编程助手的项目组。
该技能叫什么？如何一键安装 AI 技能提升开发效率？
技能中文名：API交接文档生成Skill 技能英文名：backend-to-frontend-handoff-docs 技能ID：12083
它解决的是一个非常具体的“最后一公里”问题：后端把端点、DTO、验证和业务逻辑都写完了，功能在技术上已经完成，但交接给前端时信息是断层的。前端拿到的往往只有一堆接口路径和几个示例 JSON，而真正决定 UI 怎么做的信息——某个状态值代表什么、哪个字段可以为空、哪些错误码需要单独提示、软删除数据是否默认排除——全部散落在后端开发者的脑子里。
这个技能的作用就是把后端开发者脑子里的那部分上下文“挤”出来，固定成一份可复制粘贴的交接文件，让前端或前端的 AI 助手在不追问后端的前提下，自信地把 UI 和集成写完。
安装思路与步骤
该技能本质上是一份带 name 与 description 元信息的技能定义文件（SKILL.md），触发条件写得很明确：当后端 API 工作完成、需要为前端集成记录文档时使用，或用户说“创建交接”“记录API”“前端交接”“API文档”时触发。
安装时按下面的思路操作：
- 准备前提：你使用的是支持自定义技能（Skill）的 AI 编程助手环境，并且本地已有一个可写的工作目录（技能默认会把文档写到项目下的
.claude/docs/ai/目录）。 - 导入技能：把该技能的定义文件按你所使用平台的技能管理方式导入（通常放入平台的技能目录，或在技能管理入口导入）。具体的目录路径、命令与安装入口以官方说明为准。
- 确认元信息：安装后确认技能名称与描述已正确加载，尤其是触发关键词是否包含“创建交接”“记录API”“前端交接”“API文档”。
- 验证是否生效：在对话中输入类似「用 API交接文档生成Skill 为订单审批接口创建交接」的指令，观察是否没有聊天讲解、直接生成 Markdown 文档并写入
.claude/docs/ai/<功能名称>/api-handoff.md。如果能生成文件且内容结构包含“业务上下文 / 端点 / 数据模型 / 枚举与常量”等小节，说明安装成功。
提示：如果你所在平台的安装方式、目录结构与本机路径不同，请以官方说明为准，不要照搬上面的路径示例。
该技能的主要功能和特点
- 生成完整交接文档，而非零散接口说明：单次输出一个 Markdown 块，包含业务上下文、端点清单、数据模型/DTO、枚举与常量、验证规则、业务逻辑与边界情况、集成备注、测试场景、开放问题共 9 个部分。
- “无聊天输出”模式：技能被触发后只写文件、不做讨论、不做解释，不会在对话里刷一大段内容打断你的工作流。平台需要确认时，只引用文件路径而不是粘贴全文。
- 按功能归档，支持版本迭代：文档统一写入
.claude/docs/ai/<功能名称>/api-handoff.md；根据前端反馈重新生成时自动加后缀（-v2、-v3……），接口改动历史可追溯。 - 强调“非显而易见信息”：明确要求写出权衡、假设、陷阱，例如“用户每天只能提交一次”“软删除项目默认排除”——这是普通接口文档最容易漏掉、又最影响前端判断的部分。
- 自带双重检查环节：生成前会核对请求/响应负载是否匹配真实 API 行为、鉴权范围是否准确、枚举与验证是否反映后端逻辑。
- 区分复杂 API 与简单 API：如果是直白的 CRUD、没有复杂业务逻辑、验证规则清晰，可以跳过完整模板，只给端点、方法与示例请求/响应 JSON，避免为简单接口过度产出。
- 保留专业边界：规则中明确要求不写后端实现细节（文件路径、类名、内部服务），除非与集成直接相关；不完整或待定的事项必须显式标注，而不是含糊带过。
- 可扫描性优先：输出统一使用标题、表格、项目符号和代码块，方便前端快速定位，也方便直接丢给 AI 助手作为上下文。
如何使用该技能？
第一步：完成后端 API 工作
技能的使用时机是“端点、DTO、验证、业务逻辑都完成之后”。如果接口还在设计阶段，生成出来的文档会缺少验证规则和边界情况，价值会大打折扣。
第二步：准备上下文输入
触发时把以下信息一并给出，生成质量会明显更高：
- 功能名称（会成为文件目录名，建议用简短英文或拼音，如
order-approval） - 相关端点列表
- DTO / 请求响应结构
- 身份验证与角色权限规则
- 实施过程中发现的约束、边界情况、踩过的坑
- 来自任务或用户故事的业务背景
第三步：用触发语调用
推荐几种可直接参考的输入示例：
- 「创建交接：订单审批 API，涉及提交、审批、驳回三个端点」
- 「用 API交接文档生成Skill 记录一下这套优惠券接口，前端下周要接」
- 「前端交接：用户资料接口已完成，鉴权用 Bearer Token，管理员可改他人资料」
第四步：读取输出文件
技能不会在聊天里回显内容，而是把文档写入 .claude/docs/ai/<功能名称>/api-handoff.md。你只需要打开这个文件，检查内容是否符合预期。
输出的大致形态如下（节选）：
# API交接：订单审批
## 业务上下文
财务团队需要对超过 5000 元的订单做人工审批，避免异常支出。
审批状态会直接影响订单能否发货，前端需在列表与详情页同时展示状态。
## 端点
### POST /api/orders/{id}/approve
- **目的**：将待审批订单标记为已批准
- **身份验证**：需要 `finance:approve` 权限
- **请求**：
{
"comment": "string — 审批意见，最长 200 字，可为空"
}
- **响应**（成功）：200，返回审批后的订单摘要
- **响应**（错误）：403 无审批权限；404 订单不存在；422 订单已审批过
- **备注**：同一订单重复审批会返回 422，前端应禁用按钮而非依赖报错
第五步：根据反馈迭代
前端接入过程中如果发现文档有歧义或接口有调整，重新触发一次技能即可，新版本文档会自动带 -v2 后缀，避免覆盖旧版本造成信息丢失。
第六步：对照“测试场景”做验收
文档中的测试场景章节（快乐路径、验证错误、未找到、权限拒绝）可以直接当作前端的验收标准或测试用例清单，减少联调阶段的口径不一致。
同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| API交接文档生成Skill | 面向“交接”的 AI 生成式文档 | 9 大结构化小节，含业务上下文、枚举语义、边界情况、集成备注、测试场景 | 需在支持 Skill 的 AI 助手环境中导入，触发即用 | 后端完成后交付前端、交付外部团队、给前端 AI 提供上下文 | 优势：能写出自动工具写不出的语义与坑点，支持版本迭代；不足：依赖后端提供真实上下文，脱离代码细节仍需人工核对 |
| OpenAPI / Swagger 自动生成 | 接口契约描述标准 | 从注解或代码生成接口路径、参数、Schema | 需接入注解或编写 YAML，配置成本中等 | 大型项目、需要机器可读契约与 SDK 生成的场景 | 优势：标准化、可与代码同步、生态成熟；不足：几乎不描述业务语义、枚举显示含义、集成流程与陷阱 |
| 手写 Markdown / 文档模板 | 人工整理的交接文档 | 内容自由、可完全定制 | 零门槛，但纯人力成本 | 接口数量少、团队有写作习惯 | 优势：灵活、可读性好；不足：耗时且质量取决于个人，人员流动后容易失效，版本迭代靠自觉 |
| Notion / Confluence 文档页 | 团队知识库 | 富文本协作、评论、权限管理 | 需团队账号与规范约束 | 跨部门协作、需要长期沉淀知识 | 优势：协作与检索体验好；不足：与代码脱节、更新滞后，无法直接作为 AI 上下文被消费 |
该技能的典型应用场景与实际体验情况
场景一：后端开发者向内部前端团队交付
角色与痛点：后端小张完成了订单审批的三个端点，前端在群里连续追问“重复审批返回什么”“comment 能不能为空”“状态枚举有几种”。这些答案都在代码里，但没有一处写下来。
使用方式：小张直接用一句“创建交接：订单审批 API”触发技能，把端点、DTO、枚举、验证规则贴进去，几秒后拿到一份完整文档，丢到群里。
实际体验：上手几乎没有学习成本，因为触发词就是日常说话方式。效果上最明显的改善是“提问量下降”——文档里明确写了 422 重复审批并建议前端禁用按钮，前端不再靠试错确认。注意点是：如果后端提交的上下文过于潦草，生成内容也会随之空泛，这一步不能偷懒。
场景二：让前端 AI 助手直接读懂接口
角色与痛点：前端开发者用 AI 编程助手生成页面，但助手不了解后端语义，常常把枚举写成硬编码字符串，把必填字段当成可选。
使用方式：把生成的 api-handoff.md 作为上下文提供给前端 AI，文档中的 DTO 和枚举表直接成为类型定义依据。
实际体验：由于文档专门保留了 TypeScript 形状示例和状态枚举表，AI 生成的类型几乎不需要返工。需要注意的是，文档里“开放问题 / 待办事项”章节要一并交代清楚，否则 AI 容易对未定事项做出主观假设。
场景三：外包或跨团队协作交付
角色与痛点：接口交给外部团队，对方没有权限看代码，也无法随时找到后端提问，交接全靠邮件里零散的信息。
使用方式：用该技能生成文档后作为正式交付物附件，包含业务上下文、集成推荐流程与测试场景。
实际体验：文档中“业务上下文”和“集成备注（推荐流程、缓存、实时事件）”这两节在跨团队场景下价值最高，能显著减少来回澄清。注意点是技能明确规定不写后端实现细节，所以对方若需要数据库层面说明，仍需另行补充。
场景四：接口频繁迭代，需要版本留痕
角色与痛点：接口上线后按前端反馈调整了三版，旧文档被覆盖，出问题时无法确认“当时约好的是什么”。
使用方式：每次反馈后重新触发技能，生成 -v2、-v3 文档，保留历史。
实际体验：迭代后缀机制很轻量，但确实解决了“文档版本混乱”这一高频痛点。建议在每版开头手动补一行变更摘要，可读性会更好。
该技能能为用户带来的价值
- 把隐性知识变成显性资产：边界情况、权衡和假设原本只存在后端开发者脑中，现在被固定进文件，人员变动或上下文丢失时依然可查。
- 显著压缩交接沟通成本：枚举含义、验证规则、错误码、重复操作行为一次性说清，减少群聊追问与联调阶段的来回确认。
- 降低前端的理解门槛：不需要读懂后端代码，只需要一份可扫描的 Markdown，就能知道 UI 该怎么校验、状态该怎么展示、错误该怎么提示。
- 提升 AI 辅助开发的准确率：结构化的 DTO、枚举与集成备注，可以直接成为前端 AI 生成的类型与交互逻辑的依据，减少“看起来对但字段类型错”的返工。
- 可量化的长期收益：每个功能接口交接都能省下一轮问答，接口迭代有版本可追溯，测试场景可直接复用为验收清单，随着项目累积，收益是复利式的。
- 零打扰的工作流体验：无聊天输出的设计让它更像一个“按一下就产出文件”的工具，而不是又一个需要对话纠缠的助手。
常见问题 FAQ
Q1：这个技能怎么安装？需要写代码吗？ 不需要写代码。它的本质是一份带元信息的技能定义文件，按你所使用平台的技能管理方式导入即可，导入后通过“创建交接”“记录API”“前端交接”“API文档”等说法触发。具体目录、命令与安装入口请以官方说明为准。
Q2：使用它需要付费吗？ 技能本身不涉及额外计费逻辑，实际成本取决于你所使用的 AI 助手平台的计费方式，具体价格与额度以官方说明为准。
Q3：它和 Swagger / OpenAPI 有什么区别，我是不是可以不用 Swagger 了？ 不是替代关系。OpenAPI 擅长描述“接口契约长什么样”，是机器可读的标准；这个技能擅长描述“前端该怎么做”——业务上下文、枚举的显示含义、验证规则的 UX 镜像、边界情况与集成流程。两者可以并存：契约用 OpenAPI，交接用这份文档。
Q4：为什么它生成完不跟我说话，只写了个文件？
这是设计上的“无聊天输出”模式，目的是不做讨论、不做解释，直接把文档落盘，避免长篇内容打断对话。如果平台需要确认，它只会引用文件路径。你打开 .claude/docs/ai/<功能名称>/api-handoff.md 就能看到全文。
Q5：我们的接口很简单，只有增删改查，会不会过度产出？ 不会。技能内置了“简单 API 快捷方式”：如果接口是直白的 CRUD、没有复杂业务逻辑、验证规则清晰，可以跳过完整模板，只提供端点、方法和示例请求/响应 JSON，由前端自行推断其余部分。
Q6：适合谁用？前端还是后端？ 主要面向后端开发者——因为文档需要真实的 API 行为、约束和边界情况，这些只有实现者最清楚。前端是主要受益方，尤其是用 AI 编程助手做集成的团队。