branch-api-diff-design

Installation
SKILL.md

Branch API Diff Design Skill

语言规范

  • 默认输出语言:zh-CN
  • 所有技术分析、风险评估、工时评估使用中文
  • 所有错误 message 必须为 en-US
  • 严禁输出中文错误 message
  • 输出必须结构化、可直接用于技术评审

使用场景

当出现以下情况必须使用本 Skill:

  • 分支准备合并至 master
  • 涉及接口变更
  • 涉及参数变更
  • 需要做风险与工时评估

执行步骤

Step 1

git fetch origin

Step 2

git diff --name-status origin/master...HEAD

分析优先级

必须按顺序分析:

  1. controllers
  2. validator
  3. services
  4. models
  5. response/ErrorCode.php
  6. config
  7. 其他文件

重点目录

  • modules/*/controllers/
  • modules/*/validator/
  • modules/*/services/
  • modules/common/models/
  • response/ErrorCode.php
  • config/

输出结构(强制)

接口变更分析文档

仅允许输出以下三部分,禁止追加背景、数据库、错误码、部署方案、合并建议等无关章节。

一、接口改动变更说明

必须逐个接口输出,且每个接口必须包含以下信息:

  1. 模块 / 控制器 / 方法
  2. 准确 URL(含路由路径)
  3. HTTP Method(若代码中可判定)
  4. 变更类型:新增 / 修改 / 删除
  5. 参数变化:新增 / 删除 / 必填改动 / 类型改动 / 默认值改动 / 校验规则改动
  6. 响应变化:顶层结构、data 字段、字段类型、字段语义、错误码变化
  7. 兼容性结论:兼容 / 不兼容

先输出汇总表:

| 模块 | 控制器 | 方法 | URL | Method | 变更类型 | 参数变化 | 响应变化 | 兼容性 |

再按接口输出详细对比:

1. <controller>/<action>

  • URL: /api/xxx/xxx
  • Method: GET/POST
  • 变更类型:修改
  • 参数变化:

旧版本参数

{}

新版本参数

{}
  • 响应变化:

旧版本响应

{ "code": 0, "msg": "", "data": {} }

新版本响应

{ "code": 0, "msg": "", "data": {} }
  • 兼容性结论:明确说明是否影响现有调用方

如果无法从 diff 中直接推导 URL / Method,必须基于 Yii2 控制器路由规则做出最合理推断,并明确标注“推断”。

二、工时评估(资深后端模型)

必须对每个接口单独评估,按资深后端开发 7.5h = 1 人日计算。

Complexity Points 计算

基础类型

  • 新增接口:3
  • 修改接口:2
  • 小范围 bug 修复:1
  • 删除或不兼容修改:4

参数复杂度

  • 1-3 个字段:+1

  • 4-10 个字段:+2

  • 10 或复杂校验:+3

输出变更

  • data 扩展字段:+1
  • 结构变化:+2
  • 错误码体系变化:+2

权限复杂度

  • 普通鉴权:+1
  • 权限模型变化:+2

数据库复杂度

  • 查询:+1
  • 写入/事务:+2
  • 表结构变更:+4
  • 多表复杂关系:+3

外部依赖

  • 跨模块:+1
  • 支付/RPA/客户端协议:+3

不确定性

  • 需求模糊:+2
  • 灰度或兼容复杂:+2

工时映射

CP 1-2:2h
CP 3-4:4h
CP 5-6:8h
CP 7-8:12h
CP 9-10:16h
CP 11+:24h+

输出表格

| 模块 | 控制器 | 方法 | URL | 变更摘要 | CP | 估时(h) | 人日(7.5h) | 说明 |

最后输出:

  • 总工时(h)
  • 折算人日
  • 是否建议拆分任务(仅从开发工作量角度)

三、风险评估(仅影响范围)

只允许评估“影响范围”,不要展开性能、权限、部署、数据一致性等维度。

输出表格:

| 模块 | 控制器 | 方法 | URL | 风险等级 | 影响范围 | 受影响对象 | 说明 |

评估口径:

  • 风险等级仅允许:低 / 中 / 高
  • 影响范围仅描述波及面,例如:仅后台前端、特定客户端、全部调用方、下游服务
  • 受影响对象必须尽量具体,例如:运营后台、H5、APP、第三方回调、定时任务
  • 若为不兼容修改,必须明确指出需要联动改造的调用方

强制校验清单

  • 只输出三部分内容
  • 每个接口都要给出准确 URL 或显式标注“推断 URL”
  • 每个接口都要给出参数变化与响应变化
  • 工时统一按资深后端 7.5h = 1 人日
  • 风险评估仅讨论影响范围

End

Related skills
Installs
9
First Seen
Mar 2, 2026