发车前先盘点源码里的接口契约
写接口参考页的第一圈是盘点，不是落笔。在让 Claude Code 动笔之前，先要求它通读路由声明、控制器与类型定义，把接口清单完整列出来：路径、方法、鉴权方式、请求字段、响应结构、错误码、分页与幂等约定。清单越完整，后面的页面草稿越少返工。
盘点阶段只要结构，不要成段文字。可以明确要求 Claude Code 输出纯骨架：每个接口一行摘要、一张字段表、一组示例占位。这样即使中途发现漏了字段，补的也只是骨架节点，而不是整页重写。
- 把路由文件与类型定义放进工作目录，让模型自己去读，而不是靠你手动粘贴。
- 要求它标出每个字段的必填性、默认值、取值范围与废弃状态。
- 把跨接口复用的对象抽成公共小节，避免同一结构在多页重复描述。
- 让模型把源码里出现但文档里缺失的字段单独列为待补清单。
两条起草路线的逐项对照
第一种做法是整页直出：把源码和一份旧文档塞给 Claude Code，让它一次性产出整页参考页。第二种做法是骨架先行：先出接口清单与字段表，再分段补描述、示例与错误码，最后统一校对。两条路线都能交差，差别落在改动成本和审校负担上。
整页直出适合接口少、结构稳定的小项目，优势是起步快，一次就能看到完整观感。骨架先行适合接口多、迭代频繁的服务，优势是每次只回填一小段，页面结构始终可控，改动面被限制在单个接口。
- 上下文占用：整页直出需要模型同时记住全部接口，骨架先行每次只处理一个接口。
- 示例准确度：直出的示例容易出现字段拼写偏差，分段回填更容易和源码逐字段核对。
- 改动成本：接口加字段时，直出往往连带重排整页，骨架先行只替换对应字段表。
- 审校难度：直出产出的长段落不好定位问题，分段产出的短块可以逐块放行。
- 协作体验：骨架可以直接当作写作任务清单，多人分工时边界更清楚。
给 Claude Code 的提示词这样编排
提示词的顺序决定产出质量。建议固定成四段：角色与读者、输入边界、输出格式、自检要求。读者要写清是给外部开发者看还是给内部联调看，因为这会直接影响示例的写法与错误说明的详细程度。
输入边界要告诉模型哪些文件属于权威来源，哪些历史文档只能参考、出现冲突时以源码为准。输出格式建议直接给模板：标题、一句话用途、请求字段表、响应字段表、示例、错误码、注意事项。自检要求则让它在交稿前自己核对一遍字段覆盖率。
- 角色设定写明读者水平，例如“面向首次接入的后端开发者”。
- 示例统一用可直接粘贴运行的请求，参数值用真实业务语义，不要用占位拼音。
- 要求模型在存疑处标注“待确认”，而不是编造一个看似合理的默认值。
校对关口：签名、示例与错误码
草稿完成只是中段，真正决定可信度的是校对关口。建议按三个维度过一遍：接口签名是否与源码一致，示例是否能对上真实请求，错误码是否覆盖了分支处理。模型擅长成文，但取舍和事实判断仍需要人把关。
- 签名核对：字段名大小写、必填性、嵌套层级与枚举值逐项比对类型定义。
- 示例核对：把文档里的请求复制到测试客户端跑一遍，确认返回结构与描述一致。
- 错误码核对：把异常分支补齐，说明触发条件与建议的重试或兜底做法。
- 措辞核对：删掉含糊词，把“通常”“可能”改成明确的条件句。
校对中发现的偏差，不要直接改正文，而是把问题写成新的小任务交回 Claude Code，让它按同一模板重写该段。这样正文始终保持统一语气，修改记录也留在任务里。
推荐路线与接入配置
综合对照结果，我们的推荐很明确：选骨架先行那条路线。先让 Claude Code 产出接口清单与字段表，再分段回填描述、示例与错误码，最后逐块校对。它起步多花一点时间，却在字段变更、多人协作和长期维护上更省力，交付的参考页也更经得起读者逐条核对。
接入侧的配置很简单：在 SwiftRelay 这样的按量计费中转服务上创建令牌，Claude Code 与 Gemini CLI 直接填写裸域名 https://api.fastapirelay.com，使用 OpenAI 兼容 SDK 的场景则在地址后追加 /v1。起草与精修可以分别选择不同的模型，例如用 Claude Sonnet 5.5 产出分段草稿，用 Claude Haiku 4.5 快速整理接口签名清单。
按 token 计费的模式让文档冲刺的成本随用随走，不需要为一次整理预留长期投入。现在就注册 SwiftRelay，领取新账户的赠金，把你的接口参考页跑完第一圈。