代码变更说明不是把提交记录改写得更长，而是把 diff 转成评审者能判断的四件事：改动目的、影响范围、行为变化和验证方式。让AI客户端读取提交差异、相关需求和测试结果后生成初稿，再由作者确认事实，尤其要区分“已验证”和“建议验证”。
使用墨刀AI客户端前，先把仓库、需求编号和已有验证记录放在同一工作上下文，了解客户端本地项目分析与桌面任务入口。没有运行记录时，不要让文档声称测试已通过。
先确定变更说明的最小结构
| 区块 | 回答的问题 | 证据 |
|---|---|---|
| 目的 | 这次改动解决哪个问题？ | 需求编号、缺陷或决策记录 |
| 范围 | 哪些文件、接口和页面受影响？ | diff、依赖关系、配置变化 |
| 行为 | 用户或调用方看到什么变化？ | 前后状态、兼容性说明 |
| 验证 | 做过什么检查，还缺什么？ | 命令、结果、未完成项 |
先固定比较范围，避免让AI解释错版本
最常见的偏差不是摘要写得不好，而是传给AI的diff根本不对应本次评审。整个主分支的历史、暂存区文件和当前功能分支差异，回答的是不同问题。生成前先记录基础提交与目标提交，并说明是否包含尚未提交的修改。
若本次评审对象是当前功能分支相对origin/main的已提交改动，可以先在仓库中导出下面三份材料。运行前确认origin/main确实是团队本次评审的目标分支，且本地该引用已更新；否则换成实际的目标分支或提交编号。
git diff --name-status origin/main...HEAD
git diff --stat origin/main...HEAD
git diff origin/main...HEAD三点比较会取origin/main与HEAD的共同祖先来比较当前HEAD，适合查看分支上积累的变化；它不包含工作区、暂存区和未跟踪文件。把输出分别保存为changed-files.txt、change-stat.txt和change.diff，并记录两端提交编号。需要说明尚未提交的工作时，另行提供对应差异，不能把它与已提交结果混为一份。比较语义可参照Git diff官方说明。
change-review/
changed-files.txt
change-stat.txt
change.diff
requirements/ORDER-214.md
api/order-response.md
verification/results.md
output/change-summary.mdresults.md只放已有记录：执行对象的提交编号、环境、命令、结果摘要和日志位置。缺少结果时留空并注明未执行，比只写一句“单测正常”更容易核对。接口契约用于解释字段含义；它与代码冲突时，先列冲突，不能默认文档一定代表实际实现。
提示词要约束事实来源
可以要求：只引用本次 diff、关联需求和已有运行记录；每条行为变化附文件或测试证据；无法确认的内容列入“待确认”；不要把重命名写成业务变化。对接口字段修改，还要列出旧客户端是否仍能读取，以及需要谁确认兼容。
请读取changed-files.txt、change-stat.txt、change.diff、requirements/ORDER-214.md、api/order-response.md和verification/results.md，生成供代码评审使用的output/change-summary.md。首先写明比较范围和未包含的文件类型。
按照“解决的问题、用户可见变化、调用方影响、已记录的验证、待处理事项”组织正文。每条行为结论附文件路径及函数名或差异片段；将直接看到的修改与沿调用关系推断的影响分开。代码重排、格式化和重命名单列，不能夸大成新增功能。
重点检查订单状态字段变化是否影响接口返回、页面标签、筛选条件、导出任务和旧客户端。仅把当前资料能证明存在的调用方写入影响表；未提供的消费方列为待确认。分别描述向后兼容、数据迁移和部署先后关系，没有依据时不要补结论。
验证段逐条引用results.md，保留提交编号、环境和日志位置。新增了测试代码不等于测试已运行，没有执行记录不得填“通过”。请给出仍应补查的具体对象，不修改源码、不执行命令、不代替提交或合并操作。
如果第一次只得到“优化订单状态，提升稳定性”，继续追问：“把每个概括词替换为可观察的前后变化；无法给出前后值的句子，改列待确认。”这能把摘要从宣传语言拉回评审者关心的事实。
用一个接口字段改动案例复核
假设订单接口把“状态”拆成“支付状态”和“履约状态”。AI应指出返回结构、前端映射、筛选条件和测试夹具的影响，而不是只写“优化订单状态”。评审者再查看一个成功订单、一个退款中订单和一个旧版本客户端请求，确认摘要没有遗漏。
在这个例子中，“已支付但尚未发货”不能再用一个状态值同时表达支付与履约。可以要求AI对照以下目标表达，但是否已达到目标，要回到实际差异和契约确认：
| 检查对象 | 说明中应写清楚的变化 | 需要找到的依据 |
|---|---|---|
| 接口响应 | 是否新增payment_status与fulfillment_status；旧status是否保留 | 序列化代码、响应契约与兼容测试 |
| 订单列表 | 展示单个标签还是两个标签，未知值如何显示 | 页面映射函数与状态样例 |
| 筛选请求 | 原筛选参数继续支持还是有替代参数 | 请求构造与服务端校验 |
| 导出与外部消费方 | 是否读取旧字段、需要谁确认升级 | 调用代码或接口负责人记录 |
如果diff中出现新字段，但删除旧字段的操作并不存在，就不能写“接口已完成字段替换”。更准确的说法是“接口新增两个状态字段，旧字段在当前差异中仍保留；已识别的订单列表改用新字段展示”。而旧客户端是否兼容，还要检查新字段取值、旧字段计算和返回约束，不仅看字段名称还在不在。
一份能直接用于评审的说明应该长什么样
下面是订单改动可采用的文档片段。把每处文件、编号和状态换成本次仓库中的证据后，就能成为评审说明；不需要把整个diff复制进去。
问题：ORDER-214要求分开展示订单的支付状态与履约状态，避免“已支付”遮盖待发货信息。
行为变化：订单响应增加payment_status和fulfillment_status。订单列表分别显示支付与履约标签。旧status的保留方式与支持期限需引用接口契约确认。
影响范围：核对订单响应构造、列表标签映射、筛选请求和导出消费方。说明中逐项附本次实际修改的文件及函数，未提供消费方资料的项目保留负责人确认项。
验证记录：对照results.md填写执行提交、环境、结果和日志。只有用例文件变更而没有运行输出时，记为“已增加用例，执行记录待补”。
合并前关注：确认退款中的支付状态含义、未知状态的展示和旧客户端兼容；需要前后端分批发布时，写明可先部署的一方及回退条件。
作者审读时，重点找三种偷换：把“新增字段”写成“全部调用方已迁移”，把“增加测试”写成“测试通过”，把“代码可推断的影响”写成“线上用户已经得到的效果”。逐句纠正这些问题，通常比让AI把文档润色得更长有用。
代码评审说明与面向用户的更新说明分开写
评审者需要兼容性、依赖和验证证据；普通用户更关心操作发生什么变化。前者可以保留文件路径、提交号和失败记录，后者只摘出用户能感知的变化，例如“订单列表分别展示支付与发货进度”。同一份材料可形成两种输出，但不能把待评审的实现直接写成已经发布的功能。
发布说明前保留原始diff链接和验证命令，正文只给读者需要的结论。若代码变更影响原型或接口文档，可把相应页面编号写入说明，便于产品和研发回溯。进入工作区整理变更说明、原型和评审意见。
