应根据接口文档完备性选择是否提供参考样例：文档含标准示例则直接引用；仅有字段列表需提供最小可行样例锚定关键维度；内部系统则至少提供两个覆盖认证、参数组织与响应解析的样例。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当你需要Claude生成符合特定API规范的调用示例时，不放参考样例大概率会得到通用但错位的代码——它可能用错HTTP方法、漏掉必要头字段、把query参数写进body，或者把JSON结构套成表单格式。真实接口文档往往藏在字段命名、嵌套层级、认证方式这些细节里，光靠文字描述，Claude无法稳定还原。
要不要放参考样例？先看这3种情况
方法一：接口文档本身已含标准调用示例 → 不必额外提供
直接在提示词中引用原文链接或粘贴该示例，并加一句“请严格遵循此示例的请求方式、参数位置与数据结构”。Claude能识别这是权威范本，会优先对齐而非自由发挥。
方法二：你手头只有接口字段列表（如Swagger JSON/YAML）→ 必须提供1个最小可行参考样例
哪怕只写一行：【输入】POST /v1/orders → {“user_id”: “u_123”, “items”: [{“sku”: “A001”, “qty”: 2}]} → 【输出】201 Created + {“order_id”: “ord_789”}。这能锚定动词、路径、主体结构三个关键维度，避免Claude擅自改成GET或把items拍平成字符串。
方法三：目标接口是内部系统，无公开文档 → 至少提供2个不同场景的参考样例
例如一个成功创建订单的完整curl，再加一个带错误处理的Python requests调用。两个样例必须覆盖认证方式（Bearer token还是API key）、参数组织逻辑（全部query？部分body？）、以及响应解析习惯（是否检查status_code？是否提取data字段？）。缺少任一维度，Claude生成的代码在真实环境里大概率跑不通。
参考样例怎么写才真正起作用
第一步：明确标注每个样例的“角色”
在样例前加短标签，如【成功创建】、【400错误响应处理】、【分页查询】。Claude会把标签当作分类依据，后续生成时自动匹配同类任务。
第二步：保留真实字段名和值类型，但脱敏敏感内容
把真实的API key替换成YOUR_API_KEY，用户ID替换成user_abc123。不要改成“xxx”或“123”，否则Claude可能误判为整数类型而删掉引号。
第三步：每个样例必须包含完整的协议层信息
不只是JSON body。要写出HTTP方法、完整URL（含base path）、headers（特别是Content-Type和Authorization）、以及典型响应状态码和body片段。如果接口要求签名，哪怕只写一行注释“HMAC-SHA256签名基于timestamp+body生成”，也比完全不提强得多。
注意：样例中出现的字段名，必须和你在【输入输出】部分定义的完全一致。比如样例里写的是product_id，就别在约束里写成productId——Claude不会自动做下划线转驼峰。
不放样例时的替代方案（仅限极简单场景）
如果接口确实只有1个GET端点、无认证、参数全在query里、返回纯JSON数组，可以用结构化指令代替样例：
【请求方式】GET
【基础地址】https://api.example.com
【路径】/search
【必填参数】q（字符串）、page（整数）
【可选参数】limit（默认10）
【响应结构】{“results”: […], “total”: 123}
这种写法有效，但一旦增加header、body、认证或嵌套参数，就必须补上参考样例。
