技能介绍

解决什么问题

团队在维护 Protobuf 定义和 gRPC 服务契约时，常遇到三类实际问题：一是大仓里多个模块各自维护 .proto 文件，缺少统一规则，导致风格漂移、命名不一致、字段选项使用随意；二是依赖升级或重构时，字段删改可能导致二进制不兼容，但评审时没有明确门禁；三是跨团队共享契约时，缺少自动化检查，问题往往在生成代码或集成阶段才暴露。

技能如何工作

这个技能聚焦于 规则驱动的静态检查与兼容性验证，而不是替代构建流程。它会借助 Buf CLI 的预置规则集对项目中的 .proto 文件执行 lint，覆盖常见的语法、包结构、命名、字段定义等可配置项，并进一步验证 gRPC 服务契约是否满足约定。

关键步骤包括：

初始化工作区配置，让项目具备可复用的 lint 与 breaking 基线。
执行 buf lint，按 Buf 规则集输出问题清单，便于在提交前修复。
使用 buf breaking 并结合 git 变更，对比当前 Protobuf 版本与基线，识别字段删除、类型调整、包路径变化等破坏性变更。

这样的组合适合放在本地预提交钩子或 CI 中，把契约问题提前拦截在代码合并之前。

适用边界与注意点

该技能遵循 Buf 的 lint 规则集，并不自动等同于你团队的私有规范。如果你的项目已有自定义规则文件，仍需在 buf.yaml 或相关配置中维护映射。buf breaking 的检测效果依赖清晰的 git 基线选择；在历史复杂或未打 tag 的仓库里，可能需要明确指定 against 参数，否则可能出现误报或漏报。

此外，该技能不做运行时行为校验，也不能替代对生成代码的测试。它是一个 面向 Protobuf 源码的守门员，适合与代码评审、生成代码检查、端到端集成测试组合使用。