AI Coding Agents
Code Review
Protobuf compatibility in agent-generated changes
September 26, 2026 - 2 minute read
Protobuf compatibility depends on schema history, not just whether the current .proto file compiles. A coding agent can rename a field, reuse a deleted number, or change generated code in ways that pass local tests while breaking a client on an older release. The review has to model mixed versions and rollback.
Google's Proto Best Practices advises teams not to reuse field numbers and to reserve numbers for deleted fields. Those rules give an agent concrete constraints for schema work.
Give the agent the schema history
Scope the task with the changed message, affected services, generated language targets, and supported client versions. Include the previous released schema and the command that regenerates code. A repository snapshot may omit a consumer maintained elsewhere, so list known external owners explicitly.
Ask the agent to classify each change as additive, behavior-changing, or removal-related. Adding a field is usually easier to roll out than changing the meaning of an existing field. A rename keeps the wire number but can still affect JSON names, reflection, generated APIs, and code that addresses fields by name.
Factory's Droid Exec can run a bounded compatibility task and produce a machine-readable report. Use an isolated worktree and require the generation command to finish with no unrelated output changes.
Record whether each consumer uses binary encoding, JSON mapping, or both. A wire-compatible edit can still break a boundary that depends on generated names.
Test Protobuf compatibility both ways
Compile the old and new schemas with the supported toolchain. Serialize representative messages with the old generated client and read them with the new client. Then reverse the direction. Include unknown fields, default values, enum values, nested messages, and any JSON conversion used at system boundaries.
Inspect deletions carefully. Reserve the removed field number and name rather than making either available for new meaning. Do not change a field between singular and repeated forms or rely on a language-specific type conversion without checking the official compatibility guidance.
Generated files should match a clean regeneration from the declared compiler and plugin versions. Review the schema diff separately from generated noise. If the toolchain version changes, keep that upgrade distinct or explain why it is required for the schema change.
Plan the Protobuf compatibility rollout
Deployments rarely update every producer and consumer at once. Record which side can ship first, how long mixed versions may coexist, and what happens during rollback. A compatibility test should run in CI for the supported version window rather than only during the initial migration.
Factory's automated code review can inspect the pull request for correctness problems. Repository-specific guidelines can direct the review toward field reuse, generated-file drift, and missing cross-version tests. Keep the compiler and compatibility suite as deterministic gates.
The pull request should include the old and new schema references, regeneration command, tested language targets, cross-version results, and rollout order. That evidence lets service owners evaluate the contract without reconstructing it from a large generated diff.
