关键在于用真实代码、错误码、测试用例和Git记录驱动Claude复现技术对齐过程：从Controller和异常处理器提取错误码四栏表；字段说明强制五栏格式并绑定业务动作；显式列出隐性约定并关联验证用例；基于commit message生成可发布的兼容性说明。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
让claude生成的接口文档脱离模板感、具备真实项目现场的颗粒度和决策痕迹，关键在于注入具体上下文、强制结构约束、嵌入人工校验锚点——不是让它“写一份文档”，而是让它“复现一次联调前的技术对齐过程”。用真实代码+真实错误码反推文档骨架
把Controller类完整代码（含@RequestMapping、@RequestBody、@ResponseBody）和全局异常处理器（如GlobalExceptionHandler）一起喂给Claude，指令中明确要求：“从代码中提取所有HTTP状态码、自定义错误码（如ERR_ORDER_NOT_FOUND）、对应异常类名（如OrderNotFoundException），生成错误码对照表，每行必须包含【错误码】【HTTP状态】【触发条件】【前端应如何处理】四栏。”
这一步必须带真实错误码，否则Claude会虚构ERR_001这类无意义编号。它能从throw new BizException("ERR_PAYMENT_TIMEOUT", "支付超时")这种写法里精准识别出错误码字符串，但无法凭空判断ERR_PAYMENT_TIMEOUT是否真在生产环境被使用过。
直接复制粘贴你的实际异常抛出语句，比描述“请列出常见错误”有效十倍。
字段解释必须绑定业务动作
方法一：用五栏硬约束锁定输出
在提示词开头写死格式要求：“每个请求参数和响应字段必须按【字段名】【类型】【是否必填】【取值说明】【业务含义】五栏展开；其中【业务含义】严禁出现‘表示’‘用于’等模糊动词，必须写明该值触发的具体系统行为，例如：status=2时→风控服务自动冻结该账户30分钟→同步触发短信通知模板ID:SMS_BLOCK_002。”
【取值说明中未写明枚举值或正则规则的字段，Claude会默认留空或写‘字符串类型’，导致前端无法做表单校验】
方法二：用对比样例锚定认知
粘贴你团队已通过CR的字段说明作为唯一标准：“正确示范：page_no:【整数】|必填|≥1且≤1000|分页起始页码，从1开始计数；当page_no=1时，ES查询将启用缓存策略，命中率提升40%。”
错误示范不需另写，Claude看到“正确示范”里的“ES查询将启用缓存策略”这种带技术副作用的描述，自然放弃“页码序号”这类空泛表达。
补全被代码隐藏的隐性约定
第一步：指出三类典型隐性约定
在指令中逐条列出你项目里实际存在的、但代码里不会显式声明的规则，例如：“① 所有POST接口的body必须携带x-request-id头，缺失则返回400；② status字段为空字符串时，后端按status=0（待处理）处理；③ 分页参数page_size最大值为50，超过则静默截断。”
第二步：要求Claude将这些规则写进“调用约束”章节
指令追加：“在文档末尾新增‘调用约束’章节，用表格列出上述规则，每行包含【约束项】【约束值】【违反后果】【生效接口】四列；【生效接口】必须填具体路径，如‘/api/orders/create’，不可写‘所有POST接口’。”
第三步：强制关联测试用例
“从你提供的单元测试文件中，提取覆盖上述约束的test方法名（如testCreateOrderWithMissingRequestId），将其填入【生效接口】所在行的第五列‘验证用例’。”
这一步逼Claude去读测试代码，而非凭空编造。它若找不到对应test方法，就会如实反馈缺失，而不是假装存在。
用Git提交记录生成变更说明
把最近三次涉及该接口的git commit message（含merge request标题）提供给Claude，指令为：“基于以下commit历史，生成本次接口变更的‘向后兼容说明’，必须包含：① 哪些字段新增/废弃/语义变更；② 废弃字段的下线时间窗口（如‘v2.5.0起不再接收，v2.6.0起完全移除’）；③ 兼容期内旧字段与新字段的映射关系（如‘old_status字段值0→new_status=‘PENDING’’）。”
不要只给commit hash，要给message原文。Claude能从“feat(order): add payment_timeout_ms field for async payment”里提取出新增字段名和业务意图，但无法从“fix #1234”这种信息中推理出任何内容。
这一步生成的内容可直接贴进版本发布日志，无需二次加工。
