运维工程师用 AI 写技术文档：提示词与文档示例

对负责服务器、发布流水线、监控告警和故障处理的运维或 SRE来说，告警多、脚本杂、变更文档和故障复盘写起来费时，夜间排障时更需要快速理清思路。文档是开发中最容易被拖延的部分，没有文档，新人上手和跨团队协作的成本都会很高。下面以运维工程师的真实场景为例，演示用 AI 写技术文档的完整流程：把代码、接口定义或口述设计交给 AI，让它按模板生成文档初稿，再由你补充设计决策和注意事项。

典型场景

运维工程师完成了“完成两台数据库服务器的磁盘扩容”相关的开发，需要给开发团队写接口文档和使用说明。代码已经写完，但文档迟迟没动，大家只能来问。

工具选择

编辑器里的编程助手（GitHub Copilot、Cursor、通义灵码等）可以读取代码生成注释和文档；对话助手适合根据接口定义写说明；文档可以放在 README、Wiki 或 API 文档工具中。

如果项目使用 OpenAPI 规范，可以让 AI 根据代码生成 OpenAPI 描述，再用文档工具自动渲染。

案例：一次完整的使用过程（虚构）

设想一个虚构场景：阿杰刚接手一部分新工作，既要完成“处理 2 起磁盘告警和 1 起证书过期隐患”，又要准备“推进日志集中采集”。面对需要写技术文档的任务，阿杰的做法是：先让 AI 按固定结构起草，再对照自己掌握的事实逐项修改，涉及服务器 IP、账号口令、证书私钥和内部拓扑的部分一律用代号替换。这样既节省了时间，也守住了准确性和隐私的底线。

操作步骤

确定读者：使用接口的开发、测试还是业务同事
提供代码或接口定义，以及你想强调的约束
让 AI 按模板生成：用途、参数、返回、错误码、示例
补充 AI 不知道的内容：设计原因、限制、注意事项
请一位读者试读，根据疑问修订

提示词模板（可直接复制）

提示词的关键是把背景、要求和输出格式写清楚：

【背景】最近在处理“更新 Nginx 配置模板”，同时要准备“推进日志集中采集”。
请根据下面的接口代码生成接口文档，读者是调用这个接口的其他团队开发者。

接口用途：按主机组查询“告警记录”记录
（粘贴接口代码或定义）

文档结构：
1. 接口说明（一句话用途）
2. 请求方式和路径
3. 请求参数表：参数名 / 类型 / 是否必填 / 说明 / 示例
4. 返回字段表
5. 错误码说明
6. 请求和返回示例（JSON）
7. 注意事项（分页、频率限制等）

代码中无法确定的信息请标注“待补充”，不要猜测。

示例输出（仅供示意）

示例输出如下（虚构内容，仅演示 AI 大致会给出什么样的结果）：

查询记录
按主机组分页查询“告警记录”记录。
GET /api/v1/records
参数类型必填说明示例
category string 是主机组 web
start_date date 否起始告警日期 2026-10-01
page int 否页码，默认 1 1
错误码：400 参数错误；403 无权限；429 请求过于频繁（频率阈值：待补充）
返回示例
{"total": 2, "items": [{"id": 1, "category": "web", "amount": 120}]}

参数	类型	必填	说明	示例
category	string	是	主机组	web
start_date	date	否	起始告警日期	2026-10-01
page	int	否	页码，默认 1	1

这样的输出只是起点。真正用到“更新 Nginx 配置模板”这类工作里之前，还需要对照原始资料逐条检查，并补上 AI 不知道的背景。

避坑指南

AI 会根据代码推断行为，但不知道设计意图，“为什么这样设计”要你来补。
示例数据用虚构值，不要贴真实的服务器 IP、账号口令、证书私钥和内部拓扑。

给运维工程师的特别提醒

排障时把日志片段、时间线和最近变更一起提供，让 AI 帮你列排查顺序。另外，涉及删除、重启、改权限的命令，必须先确认影响范围并做好回滚准备，不能照抄执行。

一个容易被忽略的习惯：让 AI 写的命令先在测试环境执行，并要求它说明每个参数的作用。

还可以这样用

README：为项目生成安装、配置、运行和常见问题说明。
代码注释：为复杂函数生成文档字符串。