Impact Analysis 是一个用于“在写代码之前找到爆炸半径”的技能。它帮助开发者在变更开始前,跨所有相关仓库追踪一个改动所触及的一切,例如模型、字段、端点、序列化器、Celery 任务、信号、消费者等,最终产出一份开发者和评审者都能信任的简短报告。
用途与工作流程
该技能的核心用途是在变更实施前评估影响范围,避免部署后才发现问题。其流程分为四步:
第一步:确定变更内容。获取具体要变更的对象列表,包括模型名、字段名、端点路径、序列化器字段、函数或任务名、设置、环境变量等。这些信息应从工单/PRD 中读取,或向开发者询问。模糊的输入(例如“计费相关的东西”)只能得到模糊的报告,因此需要推动获取具体名称。
第二步:找到所有仓库。读取仓库地图(../repo-map.md 或 docs/repo-map.md),其中列出了同级仓库以及谁消费了什么。如果没有地图,则列出当前仓库的同级文件夹,将所有 git 仓库视为在范围内,并建议之后运行 repo-map。
第三步:追踪。搜索每一个仓库,而不仅仅是当前仓库。对于每个变更项,查找以下内容:
在 Django 仓库内部:
- 直接引用:在 *.py、模板和 fixtures 中执行 grep -rn "<ModelName>|<field_name>"。
- 通过关联使用该字段的 ORM 查询:<field_name>、<related_name>、values("…")、order_by("…")、F("…")。
- 暴露该字段的序列化器(包括 fields = "all" 这种隐式暴露的情况)。
- 信号:模型上的 post_save/pre_save/m2m_changed 接收器,以及 save() 覆盖。
- 读取或写入该字段的 Celery 任务、管理命令、定时任务。
- 管理后台(list_display、list_filter、search_fields)、表单、过滤器(django-filter FilterSets)。
- 引用该列的原始 SQL 和 .extra()。
- 引用该字段的迁移和数据迁移。
- 覆盖该字段的测试,以及应该覆盖但未覆盖的测试。
仓库外部:
- 前端和移动端仓库:端点路径和 JSON 字段名(grep -rn "void_reason|/invoices/")。
- 其他服务:调用该端点的 HTTP 客户端、共享数据库读取(报表、ETL、BI)、Webhook、消息队列负载。
- 基础设施:环境变量、设置、功能标志、定时计划。
数据方面:
- 受影响表的行数(如果可以获取;询问开发者或检查开发数据库)。这对迁移很重要。
- 不满足新约束的已有行。
第四步:报告。在聊天中撰写报告,如果存在 PRD 或工单文件,则追加到其中。报告格式包括:变更的一行描述、风险等级(低/中/高)及一行原因、直接引用、间接引用、其他仓库、数据、测试(已覆盖/未覆盖)、推荐路线。例如推荐路线可能为:characterization-tests(报表导出)→ safe-change → django-migrations → cross-repo-change。
规则
- 每个发现都有文件和行号。如果怀疑某事但找不到,列在“未验证”下,而不是丢弃。
- 搜索名称的 snake_case、camelCase 和 URL 形式;前端代码经常重命名字段。
- 不要在此修复任何内容。该技能只报告。
适用场景
适用于在 Django 等后端项目中进行变更前的影响评估,尤其是跨多个仓库(前端、移动端、其他服务、报表)的复杂系统。适合需要确保变更不会静默破坏下游消费者、定时任务、信号或数据完整性的场景。
限制
该技能只执行分析和报告,不修改代码。其准确性依赖于仓库地图的存在和变更项的具体性。如果输入模糊或缺少仓库地图,报告质量会下降。数据行数等信息可能需要手动获取。该技能不提供自动修复或部署功能。