name: protobuf-developer description: Protobuf schema development guidelines. This skill should be used when writing, reviewing, or refactoring Protocol Buffer definitions to ensure consistency, backwards compatibility, and adherence to style guides.

Protobuf Developer

This skill provides best practices and rules for developing Protocol Buffer schemas (proto3).

When to Apply

Reference these guidelines when:

Defining new gRPC services and message types.
Modifying existing .proto files.
Refactoring message structures.
Ensuring backwards compatibility for evolving APIs.
Configuring Protobuf management, linting, and code generation using Buf.

Google AIP References

The following references are based on Google API Improvement Proposals (AIPs). Use these when designing resource-oriented APIs.

Important: When implementing these patterns, you must modify the protobuf package name and resource type domains to match the current application context (e.g., use package imrenagi.com.v1; instead of package google.example.v1;).

Resource Design

Reference	When to Use
AIP-121: Resource-Oriented Design	Designing a new API or service; need to structure resources and collections consistently.
AIP-122: Resource Names	Defining the `name` field for resources; need the correct URI path format for identifiers.
AIP-123: Resource Types	Annotating messages with `google.api.resource`; need to define resource type patterns.
AIP-124: Resource Association	Referencing resources from other messages; using `google.api.resource_reference`.
AIP-126: Enumerations	Defining enum types; need `_UNSPECIFIED` zero-value and naming conventions.
AIP-127: HTTP/gRPC Transcoding	Adding `google.api.http` annotations; need to map gRPC methods to REST endpoints.
AIP-128: Declarative-Friendly Interfaces	Building APIs consumed by infrastructure-as-code tools like Terraform.
AIP-129: Server-Modified Values	Handling fields computed or modified by the server (e.g., `create_time`, `update_time`).

Standard Methods

Reference	When to Use
AIP-130: Methods	Understanding the general structure and naming of RPC methods.
AIP-131: Get Methods	Implementing a method to retrieve a single resource by name.
AIP-132: List Methods	Implementing a method to list resources with pagination.
AIP-133: Create Methods	Implementing a method to create a new resource.
AIP-134: Update Methods	Implementing a method to update an existing resource with field masks.
AIP-135: Delete Methods	Implementing a method to delete a resource.
AIP-136: Custom Methods	Implementing non-CRUD actions (e.g., `:cancel`, `:move`, `:archive`).

Field Conventions

Reference	When to Use
AIP-140: Field Names	Naming fields; need snake_case conventions and standard suffixes.
AIP-141: Quantities	Defining numeric fields for counts, sizes, or quantities.
AIP-142: Time and Duration	Using `google.protobuf.Timestamp` and `google.protobuf.Duration`.
AIP-143: Standardized Codes	Defining status codes, language codes, or other standardized values.
AIP-144: Repeated Fields	Using repeated fields for lists; understanding pluralization and ordering.
AIP-145: Ranges	Defining start/end or min/max field pairs for ranges.
AIP-146: Generic Fields	Using `google.protobuf.Any` or `google.protobuf.Struct` for dynamic data.
AIP-147: Sensitive Fields	Marking fields containing PII or secrets.
AIP-148: Standard Fields	Using common fields like `name`, `display_name`, `title`, `description`.
AIP-149: Unset Field Values	Distinguishing between unset and default values with optional fields.
AIP-203: Field Behavior	Annotating fields with `REQUIRED`, `OUTPUT_ONLY`, `IMMUTABLE`, etc.

Operations & Patterns

Reference	When to Use
AIP-151: Long-Running Operations	Operations taking > 2 seconds; using `google.longrunning.Operation`.
AIP-152: Jobs	Modeling user-managed background tasks or recurring operations.
AIP-153: Import/Export	Implementing bulk data import or export operations.
AIP-154: ETags	Adding optimistic concurrency control with ETags.
AIP-155: Request IDs	Supporting client-provided request IDs for idempotency.
AIP-156: Singleton Resources	Modeling resources with only one instance (e.g., settings, config).
AIP-157: Partial Responses	Allowing clients to request specific fields with read masks.
AIP-158: Pagination	Implementing `page_size` and `page_token` for list methods.
AIP-159: Reading Across Collections	Listing resources across multiple parents (using `-` wildcard).
AIP-160: Filtering	Adding filter expressions to list methods.
AIP-161: Field Masks	Using `google.protobuf.FieldMask` for partial updates.
AIP-162: Resource Revisions	Tracking historical versions or revisions of resources.
AIP-163: Change Validation	Validating changes before applying (dry-run mode).
AIP-164: Soft Delete	Implementing soft-delete with `Undelete` and retention periods.
AIP-165: Purge	Implementing bulk deletion of soft-deleted resources.

Batch Operations

Reference	When to Use
AIP-231: Batch Get	Retrieving multiple resources by name in a single request.
AIP-233: Batch Create	Creating multiple resources in a single request.
AIP-234: Batch Update	Updating multiple resources in a single request.
AIP-235: Batch Delete	Deleting multiple resources in a single request.
AIP-236: Policy Preview	Previewing the effect of policy changes before applying them.

Compatibility & Versioning

Reference	When to Use
AIP-180: Backwards Compatibility	Understanding what constitutes a breaking change; evolving APIs safely.
AIP-181: Stability Levels	Marking APIs as alpha, beta, or stable.
AIP-182: External Dependencies	Managing dependencies on external proto definitions.
AIP-185: Versioning	Structuring package names with version suffixes (v1, v2).

Style & Documentation

Reference	When to Use
AIP-190: Naming Conventions	Naming messages, enums, fields, and services consistently.
AIP-191: File Structure	Organizing proto files within a package.
AIP-192: Documentation	Writing comments and documentation in proto files.
AIP-193: Errors	Returning structured errors with `google.rpc.Status`.
AIP-194: Retry	Documenting retry behavior and idempotency.
AIP-200: Precedent	Understanding when to follow existing patterns vs. innovation.
AIP-202: Field Formats	Using format annotations for UUIDs, emails, URIs, etc.
AIP-205: Beta Blocking Changes	Managing breaking changes in beta APIs.
AIP-210: Unicode	Handling Unicode strings and normalization.
AIP-211: Authorization	Documenting authorization requirements.
AIP-213: Common Components	Using shared proto definitions across services.
AIP-214: Expiration	Modeling time-to-live or expiration for resources.
AIP-215: Isolation	Designing multi-tenant or isolated resource APIs.
AIP-216: States	Modeling resource lifecycle states.
AIP-217: Unreachable Resources	Handling references to resources that may not exist.

Buf References

Use these references when configuring Buf for linting, breaking change detection, and code generation.

Reference	When to Use
Protobuf Management with Buf	Setting up Buf for a new project; understanding `buf.yaml` and core commands.
Linting	Configuring lint rules; resolving conflicts between Buf linter and AIP standards.
Breaking Change Detection	Running `buf breaking` to prevent backwards-incompatible changes.
Directory Structure	Organizing proto files and packages for Buf modules.
Code Generation	Configuring `buf.gen.yaml` for Go, gRPC-Gateway, and OpenAPI code generation.

How to Use

Read the Rules: Before starting a new feature or refactor, browse the relevant rule files.
Follow the Examples: Use the provided "Correct" code patterns as templates.
Ensure Consistency: Apply the same patterns across all proto files.

Each rule file contains:

Brief explanation of the rule
"Incorrect" examples (Bad patterns)
"Correct" examples (Recommended patterns)
Additional context and references

Name	protobuf-developer
Description	Protobuf schema development guidelines. This skill should be used when writing, reviewing, or refactoring Protocol Buffer definitions to ensure consistency, backwards compatibility, and adherence to style guides.

protobuf-developer

SKILL.md