在日常API文档的编写工作中，错误码说明往往是最容易被忽略却又极易引发问题的环节。你会发现，借助AI生成一份能直接交付的文档，难度远超出最初的预期。尤其是豆包这类大模型，经常在生成过程中“忽略”HTTP状态码、遗漏具体的触发场景描述，或者把客户端建议写成无关痛痒的空话。最终的结果就是：文档难以对外交付，前端和测试团队看完后频频摇头。

事实上，这类问题是有清晰解决路径的。核心思路可归纳为三个步骤：首先，利用角色指令固定输出结构；其次，通过分项反问的方式引导AI自查；最后，借助正反例对比来堵住逻辑层面的漏洞。以下将对每一步进行详细拆解。

第一步：用“角色+规则”锚定强制输出结构

在开启新对话时，直接输入一条预设的“角色+规则”指令。这个指令需要写得尽可能具体，不仅要明确AI的身份，还要对字段维度和输出格式作出硬性要求。

具体示例如下：

“你现在是某大厂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的判断也越准确。

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

第三步：采用“负向排除法”堵住逻辑漏洞

即使经过了结构锁定和分项反问自查，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挑出问题，而不允许它自由修改。因为一旦放开修改权限，它可能“补”出一个新的误导性问题。只输出问题点，更便于你在下一步进行有针对性的修正。