用途 该技能面向“某次变更后功能坏了”的场景:找出引入问题的提交和根本原因,把问题转化为一个失败测试以防再次静默发生,完成修复,并写一份简短、不追责的复盘。它有两种模式:postmortem(默认)和 release notes。
Postmortem 模式 步骤 1:固定症状。收集具体信息,包括准确的报错或 traceback(Sentry 链接或日志行)、受影响的端点或页面、影响人群(全部用户、某个组织、某个角色)、开始时间,以及那段时间前后部署了什么。如果是正在发生的生产事故,第一步是缓解(回滚部署、关闭开关),并在调查前先确认这一步是否已完成。
步骤 2:复现。在猜测原因前先在本地复现。最好的形式是在能体现症状的最高层级写一个失败测试(端点缺陷用 API 测试)。若无法复现,列出本地与故障环境的差异(数据、配置、环境变量、版本、Celery 与同步),据此缩小范围。
步骤 3:找出变更。先用最快的办法:
git log --oneline --since="7 days ago" -- <suspect paths> git log -S "<field_or_function_name>" --oneline # commits that added/removed the string git log -p -L :<function_name>:<path/to/file.py> # history of one function
若仍未找到,且有好的提交与坏的提交,用失败测试做二分:
git bisect start <bad> <good> git bisect run pytest path/to/test_regression.py -x -q git bisect reset
同时检查迁移和依赖升级(requirements*.txt、poetry.lock、uv.lock 的差异);很多“什么都没改”的回归其实是库升级。
步骤 4:根因,然后修复。用一两句话机械化地陈述根因,例如“提交 abc123 把作废邮件移进了 post_save 信号;夜间任务的 bulk_update 不触发信号,所以该任务作废的发票从不发送邮件”,而不是笼统的“信号里有个 bug”。然后:保留复现测试(它是回归防线),确保修复前它是失败的;在根因处修复而非症状处,若正确修复较大,先发布小的安全修复并为正式修复建单;在其他地方查找同样的错误(grep 该模式),同一 bug 同样修复或建单;如果周边区域没有测试,先补充特征测试。
步骤 5:撰写复盘。简短、不追责(针对变更与缺口,而非个人),保存到 docs/postmortems/YYYY-MM-DD-<slug>.md,或团队存放复盘的位置。模板包含标题与日期、影响(受影响的人/事及持续时长)、发现方式(Sentry 告警/客户报告等)、根因(机械化解释并链接提交)、修复(PR 链接)、为何未被拦截(如批量路径无测试、信号副作用在评审中不可见)、预防(新增回归测试路径、工单编号等),仅在为生产事故时附时间线(部署、首次报错、回滚、修复的时间)。
Release notes 模式 确定范围:两个 tag(git tag --sort=-creatordate | head),或上次部署的 sha 到 HEAD。
git log --oneline --no-merges <from>..<to> 以及已合并的 PR 标题(gh pr list --state merged --search "merged:>=YYYY-MM-DD")。
按 New、Improved、Fixed、Breaking / action needed(消费者必须处理的 API 变更、带部署步骤的迁移、被移除的字段、新的环境变量)分组。除非被要求,跳过纯重构和仅测试的改动。每行按受众撰写:面向客户(通俗语言、不含内部细节)还是内部(Jira 编号、PR 链接、迁移说明)。先展示草稿,未经开发者同意不要发布到任何地方。
规则 没有修复前先失败的测试,不做修复。撰写中不点名、不追责个人。若根因仍只是猜测,明确说明并列出可确认它的证据。