protobuf

Protocol Buffers When You Need This Skill Creating or editing .proto files Setting up buf.yaml or buf.gen.yaml Designing gRPC or Connect services Adding protovalidate constraints Troubleshooting buf lint or breaking change errors Core Workflow 1. Match Project Style Before writing proto code, review existing .proto files in the project. Match conventions for naming, field ordering, structural patterns, validation, and documentation style. If none exists, ask the user what style should be used or an existing library to emulate. 2. Write Proto Code Apply universal best practices from best_practices.md : For service templates, see assets/ . 3. Verify Changes Always run after making changes: buf format -w && buf lint Check for a Makefile first—many projects use make lint or make format . Fix all errors before considering the change complete. Quick Reference Task Reference Field types, enums, oneofs, maps quick_reference.md Schema evolution, breaking changes best_practices.md Validation constraints protovalidate.md Complete service examples examples.md , assets/ buf CLI, buf.yaml, buf.gen.yaml buf_toolchain.md Migrating from protoc migration.md Lint errors, common issues troubleshooting.md Project Setup New Project Create directory structure: proto/ ├── buf.yaml ├── buf.gen.yaml └── company/ └── domain/ └── v1/ └── service.proto Use assets/buf.yaml as starting point Use assets/buf.gen.*.yaml for code generation config Code Generation Templates Template Use For buf.gen.go.yaml Go with gRPC buf.gen.go-connect.yaml Go with Connect buf.gen.ts.yaml TypeScript with Connect buf.gen.python.yaml Python with gRPC buf.gen.java.yaml Java with gRPC Proto File Templates Located in assets/proto/example/v1/ : Template Description book.proto Entity message, BookRef oneof, enum book_service.proto Full CRUD with batch ops, pagination, ordering Common Tasks Add a new field Use next sequential field number Add appropriate semantic validation Document the field Run buf format -w && buf lint Remove a field Reserve the field number AND name: reserved 4 ; reserved "old_field_name" ; Run buf breaking --against '.git#branch=main' to verify Add semantic validation See protovalidate.md for constraint patterns: Required fields: (buf.validate.field).required = true String formats: .string.uuid , .string.email , .string.uri Numeric bounds: .int32.gt , .uint32.lte Repeated bounds: .repeated.min_items , .repeated.max_items Verification Checklist After making changes: buf format -w (apply formatting) buf lint (check style rules) buf breaking --against '.git#branch=main' (if modifying existing schemas)