API错误码说明提示词优化指南：AI检查遗漏技巧

在API文档的实际编写中，错误码说明往往是投入精力最少却故障率最高的模块。你很快会发现，指望AI直接生成一份可直接交付的文档并不现实。以豆包为代表的模型，经常在生成过程中遗漏HTTP状态码、跳过触发场景的定义，或者把客户端建议写成空洞的套话。最终文档无法验收，前端与测试团队频频反馈。

这个问题完全可以通过系统化流程解决。核心方法可提炼为三步：先用角色指令锁定输出结构，再用分项反问迫使模型自我校验，最后通过正负例对照封堵逻辑漏洞。下面逐一拆解。

先用角色+规则锚定强制结构输出

开启新对话时，直接输入一条预先编写好的“角色+规则”指令。指令必须足够具体，不仅要指定身份，还要明确字段维度和格式约束。

举例：

“你现为某大厂API平台组资深文档工程师，负责输出符合OpenAPI 3.0规范的错误码说明。所有输出必须包含且仅包含以下5个字段：①错误码（如ERR_USER_NOT_FOUND）；②HTTP状态码（如404）；③触发条件（精确到参数校验/权限/资源状态等层级）；④错误响应示例（JSON格式，含code/message字段）；⑤客户端处理建议（动词开头，如‘重试前检查token有效期’）。”

这一步的作用：把模型的“自由发挥空间”压缩至最低。字段被明确锁死之后，AI若想跳过一个字段，就必须强行违反指令，这在大多数情况下不会发生。如果后续检查发现某字段缺失，说明角色绑定并未生效，此时需重启对话，重新输入该指令。

再用分项反问法触发自查

结构框架确定后，AI并不保证每个字段都写得合格。尤其是“触发条件”和“客户端处理建议”两项，极易被写成泛泛的空话。这时需要借助“分项反问”驱动其自我审查。

两种常用提问策略：

方法一：将AI刚生成的错误码条目粘贴回来，然后追加提问：“请逐项核对：这一条是否提供了HTTP状态码？若未提供，请补全并说明依据（如401必须对应未认证，不可填200）。” 此做法的价值在于，让AI在“自我审查”过程中重新建立状态码与错误场景的对应关系，而非仅机械填空。

方法二：针对“客户端处理建议”易空洞的问题，单独聚焦提问：“这条错误码的客户端处理建议是否可执行？请判断：建议是否含具体动作动词？是否指向明确对象（如‘刷新access_token’而非‘检查权限’）？若任一否，请重写。” 注意，不能只问“有没有建议”，而要提供可对照验证的标准。标准越清晰，AI的判断越准确。

【关键提醒：不要只问“有没有建议”，要定义可验证标准】

最后用负向排除法堵住逻辑漏洞

即便经过结构锁定和分项自查，AI仍可能在字段内容的逻辑一致性上出错。例如，它可能写了一个HTTP 504的超时错误，却没有说明超时阈值或是否该降级处理。这种问题靠“正面引导”通常纠正不干净，更有效的方法是“负向排除法”——即用正反样例让AI自行发现缺陷。

具体操作分三步：

第一步，提供一个正确样例，并标注哪些地方做对了：“正确示例→ERR_INVALID_PARAM：400；触发条件：name字段为空字符串或长度超过32字符；响应示例：{‘code’:‘ERR_INVALID_PARAM’,‘message’:‘参数name格式不合法’}；客户端处理建议：校验前端表单非空及长度限制。” 这个样例的作用是让AI明确“好”的标准。

第二步，提供一个典型错误样例，并点明问题所在：“错误示例→ERR_TIMEOUT：504；触发条件：后端服务调用超时；响应示例：{‘code’:‘ERR_TIMEOUT’,‘message’:‘请求超时’}；客户端处理建议：稍后重试。（问题：未说明超时阈值、未区分是网关超时还是下游服务超时、建议未提示是否应降级）。” 这个样例的作用是让AI看到“坏”的样子，并理解问题根源。

第三步，把待检内容发给AI，并下达指令：“请对照以上正误样例，指出本条缺失的字段或表述缺陷，仅输出问题点，不重写全文。” 这一步的精髓在于：只让AI挑毛病，不允许它自由修改。因为一旦放开修改权限，它可能“补”出一个新问题。只输出问题点，更便于你进行下一步精准修正。

来源：互联网