对软件工程师来说，接口文档不难，但琐碎。AI 适合承担“第一稿”和“查漏”的角色：你提供接口代码，它给出接口文档的结构化版本；你再用专业判断修改。关键是控制好一个风险——文档与实现不同步。

什么时候适合用 AI

  • 适合：接口代码比较多、需要快速形成接口文档初稿，或者需要换个角度查漏补缺的时候。
  • 谨慎：材料涉及未公开或敏感信息、结论需要专业资质背书，或者容易出现“文档与实现不同步”的情况。
  • 不适合：需要现场判断、当面沟通或承担最终责任的环节——这些仍由软件工程师本人完成。
  • 预期：AI 负责“快”和“全”，你负责“准”和“对”。把节省下来的时间用在复核和沟通上，整体质量才会提升。

推广步骤

  • 先找一个试点任务：接口文档重复度高、风险可控，适合作为第一个试点。
  • 统一提示词和模板：由一位熟练的同事整理共享提示词库，避免每个人各写各的。
  • 明确红线：哪些信息不能输入、哪些结果必须复核，写成一页纸规则。
  • 组织一次分享：用真实（脱敏）案例演示前后对比，比讲概念更有说服力。
  • 定期复盘：每月收集问题和好用的写法，更新模板。

团队共享提示词

角色：资深软件工程师，熟悉需求变化快、代码要可维护的工作环境。
背景：【一句话说明项目/对象与目的】
输入：【接口代码】
产出：接口文档，长度约【】字，语气【正式/友好/简洁】。
约束：
- 只基于输入信息；凡是推测，标注“推测”并说明依据；
- 特别注意避免：文档与实现不同步；
- 不要使用夸张、绝对化表述。
参考样例：【贴一份你认可的旧版本，说明好在哪里】
步骤：先给大纲让我确认，我回复“继续”后再写完整内容。

团队复核清单

  • 输入的接口代码已脱敏，不含不该外传的信息
  • 已告诉 AI 这份接口文档的读者和用途
  • 输出中的数字、日期、名称都已回到原始材料核对
  • 已专门检查：文档与实现不同步
  • 标注为【待确认】的内容都已补齐或删除
  • 语气和格式符合单位或行业惯例
  • 涉及专业判断、承诺或责任的内容，由本人或有资质的人确认
  • 好用的提示词和最终版本已存档

延伸阅读

说明：文中示例人物与场景均为虚构；AI 输出可能有误，请结合专业判断复核，并遵守所在单位关于 AI 工具与数据的规定。