# 交付改动

> 把一个 Jira ticket 做成测试过、可以评审的改动。

开发与评审 · /zh/deliver-a-change/ · 2026-11-05

## 1. 读懂 ticket

**Prompt**

```text
用已连接的 Jira MCP 或已认证的 acli 读 [Jira 编号或链接]，描述、验收标准和评论都要读到。
访问不了就告诉我，我把详情贴给你。读仓库说明，梳理受影响的流程。
给出最小的改动方案，以及能证明它正确的检查。业务规则、权限或数据上不清楚的，列成问题。
先不要改代码。
```

- 带上[上手项目](/zh/new-project/)整理好的项目背景，和已经定下的[分支计划](/zh/branching-strategy/)。
- 简单的改动，给个简短方案就够了。涉及业务规则、权限或数据的改动，先和需求负责人讨论。

* **PR-1** (中风险; 由代码评审检查): **一个 PR 只做一件事。** 拆分能让验证、上线或恢复更容易时，就拆；光看行数，判断不了好不好评审。

**Jira 连接参考**

用已连接的 [Jira MCP](https://developer.atlassian.com/cloud/rovo-mcp/) 或已认证的 [Atlassian CLI](https://developer.atlassian.com/cloud/acli/reference/commands/jira-workitem-view/)。

```sh
acli jira workitem view ENG-123 --fields '*all' --json
```

> **示例: ENG-123 · 导出筛选后的订单**
>
> 商户管理员可以把当前筛选出的订单导出为 CSV。文件在后台生成，生成好了通知管理员。Fix Version：2.8.0。
>
> - 包含订单号、日期和总额。
> - 不包含客户联系方式，也不包含其他商户的订单。
> - 结果为空时，文件里只有表头。
> - 导出重试后，只生成一个文件、发一次通知。
> - 定时导出不在范围内。

## 2. 实现改动

**Prompt**

```text
在 [ticket 分支] 上为 [Jira 编号] 实现已确定的改动，每条验收标准都要有测试。
更新因这次改动而不再准确的文档和 agent 说明。计划和笔记不要放进仓库。
告诉我改了哪些文件、加了哪些测试，以及已确定的行为或风险有没有变化。
先不要 push 或开 PR。
```

- **REL-2** (中风险; 由代码评审检查): **文档跟它描述的行为在同一个 PR 里改，** 这样发布收尾只需要核对，不用重写。
- **API-1** (高风险; 由代码评审检查): **后端改动保持向后兼容。** 现有客户端照常工作，包括所有仍允许运行的已安装 App 版本。可以新增字段和接口；等没有受支持的客户端依赖它们之后，才能修改或删除。

  注意: 已安装的移动端版本收不回来，用户也不会马上更新。哪些版本仍受支持，由强制更新设置决定。

* 检查每条验收标准都有测试，diff 只动这个 ticket 相关的文件。
* 让 agent 只用[合成数据，并在获准的权限范围内工作](/zh/security/#limit-the-agents-access)：生产环境和破坏性操作都要等你同意。
* 无关的缺陷单独建 ticket 跟进，不要在这次改动里顺手修。
* 实现过程中，如果新发现会改变已约定的行为或风险，先和需求负责人确认，再继续。
* 新增文档要在[文档索引](/zh/release-mgmt/#r-rel-7)里登记。
* 按改动涉及的内容，落实对应防护页中的要求：[访问与数据](/zh/security/)、[数据库变更](/zh/migrations/)、[资金与奖励](/zh/value-abuse/)、[后台任务与外部调用](/zh/jobs/)，或[短信与付费接口](/zh/otp/)。

## 3. 验证结果

场景：agent 说 ENG-123 已经做完，测试全部通过。

**较差的 prompt**

```text
很好，测试都过了。开 PR 吧。
```

**更好的 prompt**

```text
用合成数据，对照 ticket 的验收标准验证这次改动。
跑完该跑的检查，再把受影响的流程实际走一遍。如果是修 bug，展示回归测试在修复前失败、修复后通过。
每条验收标准都要给出证据，附上跑过的命令、测试的 commit，以及没验证到的地方。检查失败就修根因，不要削弱防护。
先不要 push 或开 PR。
```

原因：agent 写的测试，可能和实现共享同一个错误假设。逐条对照验收标准核查证据，才能判断行为是否符合预期。见[代码评审](/zh/code-review/#r-ai-3)。

- 对照 ticket 检查证据；AI agent 验证不了的部分，自己去看。
- 改动防护措施，要写明理由，并得到评审人同意。

ENG-123 要让 AI agent 验证这些：

| 预期行为   | 证据                             |
| ------ | ------------------------------ |
| CSV 正确 | 订单号、日期和总额与筛选出的合成订单一致；没有客户联系方式。 |
| 商户隔离   | 其他商户的订单、下载和任务都访问不到。            |
| 管理员权限  | 同一商户的非管理员用户不能导出或下载。            |
| 空结果    | 空导出只有表头。                       |
| 重试     | worker 重启后，导出照常完成，只有一个文件、一次通知。 |
| 现有行为   | 界面上的筛选照常可用。                    |

## 4. 开一个可评审的 PR

**Prompt**

```text
检查 [Jira 编号] 的最终 diff，看有没有缺陷、无关改动和意外的文件。发现了就停下来告诉我。
diff 干净的话，push [ticket 分支]，向 [目标分支] 开 PR。描述里写清楚为什么要做这个改动，链接 ticket 和验收标准。
每条标准给出证据，附上检查结果和测试的 commit，写明哪些没有验证，以及怎么撤销这个改动。
不要合并。
```

- **CI-1** (高风险; 由 CI 检查): **待评审的改动必须在 CI 里运行测试和 lint。** 本地通过，不代表共享的构建环境也能跑通。
- **PR-2** (中风险; 由代码评审检查): **说明改动的原因。** 链接 ticket 和验收标准，让评审人能判断结果对不对。
- **PR-5** (中风险; 由代码评审检查): **写明哪些没有验证，以及原因。** 批准人要知道缺口在哪，才能做判断。

_PR 描述示例_

```text
ENG-123：导出筛选后的订单

为什么：商户管理员需要把正在查看的订单导出为 CSV。
证据：用两个商户的合成用户，检查了字段、筛选、空结果、重试、商户隔离和管理员权限。
检查：[CI 运行] · [命令和结果] · commit [SHA]。
缺口：生产数据量下的性能未验证。
跟进：[Jira 链接]，负责人 [姓名]；发布前解决。
恢复：暂停导出队列，然后重新部署上一个版本；新增的 exports 表保留。
```

下一步：把 PR、证据和写明的缺口交给[代码评审](/zh/code-review/)。