技术文档的产出效率直接影响研发协作与开发者体验。很多团队已经尝试用大模型生成API参考或产品使用说明，但结果往往出现参数描述空洞、字段类型错乱、示例与真实响应不一致等问题。根本原因并不在模型能力，而在提示词没有把工程约束、术语边界和输出结构讲清楚。要让大模型写出能直接进入评审流程的文档，需要围绕接口定义、业务场景和质量校验设计专门的提示词体系。
API文档提示词的核心约束设计
API参考文档不同于普通说明文字，它必须严格反映接口的真实行为。字段是否可空、默认值是什么、错误码在何种条件下返回，这些信息都来自代码和接口定义，而不是模型根据语言习惯推测。因此提示词里首先要明确输入素材的边界：可以指定OpenAPI规范、接口代码片段或数据库表结构作为唯一事实来源，并要求模型不得自行补充来源之外的信息。
在设计提示词时，可以采用角色加任务加输出契约的结构。角色部分告诉模型它的职责是技术文档工程师而非营销文案；任务部分明确处理哪个接口或哪组接口；输出契约则详细列出文档必须包含的模块，例如概述、认证方式、请求参数、响应字段、错误码和调用示例。每个模块还可以继续细化，比如参数表必须包含字段名、类型、必填性、默认值、取值范围和说明六列。
除了正向要求，负面清单同样重要。很多生成结果之所以不可用，是因为模型添加了“提升体验”“保证稳定”这类模糊表达，或者把可选参数写成必填。可以在提示词中直接禁止使用哪些词汇、禁止虚构字段、禁止改变术语拼写。下面是一个可复用的API文档生成提示词模板，输入OpenAPI片段即可得到结构化草稿。
你是一名资深API文档工程师。请根据以下接口定义生成参考文档草稿。
接口定义：
{{openapi_spec}}
输出要求：
1. 每个接口包含概述、请求方法、路径、请求参数表、响应字段表、错误码说明。
2. 参数表必须包含字段名、类型、必填、默认值、说明。
3. 说明中不得出现“可能”“大概”等模糊词。
4. 对每个响应字段给出JSON示例。
5. 使用中文技术写作风格，术语与输入保持一致。
负面清单：
- 不要添加接口定义中不存在的字段。
- 不要将可选参数描述为必填。
- 不要在说明中承诺稳定性或性能指标。
在实际使用中，这个模板的价值在于把接口定义当作不可变输入，让模型的自由度限制在语言组织和格式整理上。如果接口定义本身不完整，应当先修复定义，而不是让模型在文档阶段补齐。否则后续接口变更时，文档与实现会产生更大的偏差。
产品文档提示词的情景化表达策略
产品文档的目标读者通常不是开发者，而是运营人员、业务用户或实施顾问。他们关心的不是某个参数的JSON类型，而是完成一个业务目标需要经过哪些步骤、有哪些前置条件、出现错误时如何排查。因此产品文档的提示词需要从功能描述和用户任务出发，而不是从接口定义出发。
一个有效的做法是提供用户故事或场景描述作为输入。例如可以告诉模型：某企业管理员需要批量导入员工信息，文档要说明支持的文件格式、字段映射规则、导入失败后的处理方式。提示词中要明确受众的技术水平，并要求把专业术语转换为业务语言，但保留关键名词的准确性。比如“OAuth令牌”可以描述为“用于身份验证的访问凭证”，但不能简化成“登录密码”。
产品文档还要注意操作流程的可执行性。可以要求模型按步骤编号输出，每一步包含操作位置、操作动作和预期结果。对于可能出错的步骤，单独设置“注意事项”小节。为了避免模型编造界面元素，提示词应要求只基于提供的功能说明和界面截图文字描述来写作，不猜测按钮名称和菜单路径。以下是一个产品文档提示词的示例。
请根据下面的功能说明，为业务用户撰写使用文档。
功能说明：
{{function_spec}}
受众：企业后台运营人员，不具备编程背景。
输出要求：
1. 用分步骤形式描述操作流程，每步包含执行动作和预期结果。
2. 步骤中出现的按钮、菜单、输入框名称必须与功能说明一致。
3. 对于可能失败的操作，增加注意事项说明原因和解决方法。
4. 避免使用API、SDK、请求头等开发术语。
5. 不使用“简单”“轻松”等主观评价词。
负面清单：
- 不要新增功能说明中未提及的界面元素。
- 不要使用“点击这里”等指代不清的表述。
- 不要在操作步骤中插入营销性描述。
通过这种约束，模型生成的产品文档会更接近实际帮助中心的内容，而不是把接口说明换个说法。产品文档的提示词还需要反复迭代，尤其是当用户反馈某一步看不懂时，可以把真实问题作为补充输入，让模型重新组织对应步骤。
从接口定义到文档草稿的提示词工作流
单次提示词很难同时完成字段提取、语言润色和格式校验。更稳定的做法是把工作拆成三个阶段。第一阶段用提示词让模型从OpenAPI或代码注释中提取结构化信息，输出为中间格式；第二阶段基于中间格式生成面向读者的文档正文；第三阶段再让模型对照原始定义做覆盖校验。
第一阶段的核心是保证提取无遗漏。输入可以是完整的OpenAPI YAML文件，要求模型输出每个接口的参数清单和响应字段清单。这里不需要生成漂亮句子，只关心数据是否完整。第二阶段再对每个字段生成说明，此时可以加入术语表和风格指南，让语言统一。第三阶段则要模型扮演审校角色，检查文档中的字段数量、类型和示例是否与原始定义一致。
下面展示一个简化的OpenAPI片段，作为工作流输入示例。
openapi: 3.0.0
info:
title: User Service
version: 1.0.0
paths:
/users/{id}:
get:
summary: 获取用户详情
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: 成功
content:
application/json:
schema:
type: object
properties:
id:
type: string
name:
type: string
email:
type: string
第一阶段可以要求模型输出一个表格，只包含参数名、类型、是否必填和来自原始定义的位置。第二阶段再基于这个表格生成参数说明和响应示例。第三阶段执行时，把生成的文档和上面的OpenAPI片段同时交给模型，要求它指出哪些字段在文档中缺失，哪些字段类型描述错误。这样分阶段处理，每一步都容易验证，也方便在中间环节插入人工修改。
常见问题与质量校验提示词
大模型生成技术文档时最常见的三类问题是术语漂移、参数遗漏和过度承诺。术语漂移是指同一个概念在不同段落中出现不同写法，例如前面写“用户ID”，后面写成“用户标识”或“userId”。参数遗漏则是文档只描述了主要参数，忽略了可选参数或错误响应中的字段。过度承诺表现为使用“保证数据安全”“绝对可靠”等词汇，这在工程文档中既不准确也容易引发法律风险。
针对术语漂移，可以在提示词中嵌入术语表，并明确要求：所有出现该概念的位置必须使用术语表中的原词，不得替换。术语表可以放在提示词末尾，用表格形式列出中文术语、英文术语和允许缩写。针对参数遗漏，要求模型在文档最后附上覆盖矩阵，将接口定义中的每个字段与文档中的表格行一一对应。如果某个字段没有对应说明，就标记为“未覆盖”。
校验提示词可以把审校任务单独拆出来，让模型以批评者视角检查上一轮输出。与生成阶段不同，校验阶段不要求模型改写，只要求列出问题。这种分工可以减少模型为了保持行文流畅而忽略细节的倾向。下面是一个可用于最终校验的提示词模板。
请检查上一轮生成的API文档草稿，重点核对以下内容： 1. 请求参数表的字段数量是否与接口定义一致。 2. 响应字段是否覆盖了200和错误状态码。 3. 每个字段的示例值是否符合类型要求。 4. 是否存在未定义的字段或虚构参数。 5. 描述中是否包含“保证”“绝对”“100%”等过度承诺词汇。 输出格式： - 遗漏字段列表 - 错误类型列表 - 建议修改的段落原文
这套校验机制并不复杂，但能显著降低人工审校成本。技术写作者可以把精力集中在业务逻辑是否讲清楚、示例是否贴近真实使用等更高层次的问题上。提示词设计的本质，就是把重复性的结构检查交给模型，把判断和决策留给人。