Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

protobuf-dev

/protobuf-dev

Zapewnia wiedzę o programowaniu w Protocol Buffers: wytyczne stylu, zgodność wsteczna, wzorce projektowe i wykrywanie systemu budowania (buf, Bazel) przy tworzeniu i przeglądzie plików .proto.

Repozytorium
claude-toolbox ↗
Licencja
MIT
Ostatnia zmiana repozytorium
24.09.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 24.09.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Zapewnia wiedzę o programowaniu w Protocol Buffers: wytyczne stylu, zgodność wsteczna, wzorce projektowe i wykrywanie systemu budowania (buf, Bazel) przy tworzeniu i przeglądzie plików .proto.

Oryginalny opis (EN)

Expert knowledge for Protocol Buffer development. Includes style guidelines, backward compatibility, design patterns, and build system detection (buf, Bazel). Use when creating, modifying, or reviewing .proto files or proto build rules.

Jak działa

  1. 1. Build System Detection
  2. 2. Proto File Style
  3. 3. Documentation: The Fine-Print Contract
  4. 4. Backward Compatibility
  5. 5. Design Patterns
  6. 6. Linting
  7. 7. Formatting
  8. 8. JSON Serialization Gotchas
Sekcje z nagłówków SKILL.md, w oryginale · 446 linii, 1 765 słów
Podgląd SKILL.md
---
name: protobuf-dev
description: Expert knowledge for Protocol Buffer development. Includes style guidelines, backward compatibility, design patterns, and build system detection (buf, Bazel). Use when creating, modifying, or reviewing .proto files or proto build rules.
---

# Protocol Buffer Development Skill

Use this skill when the user **creates, modifies, or reviews `.proto` files or proto build rules**.

## 1. Build System Detection

Detect the project's build system and use the appropriate commands. **Do not assume one build system over another.**

### buf (default)

Use when a `buf.yaml` or `buf.gen.yaml` is present:

```bash
buf lint
buf format -w
buf generate          # generate code from protos
buf breaking --against '.git#branch=main'
```

### Bazel Projects

Use when `BUILD`, `BUILD.bazel`, or `WORKSPACE` files are present:

```python
load("@rules_proto//proto:defs.bzl", "proto_library")

proto_library(
    name = "example_proto",
    srcs = ["example.proto"],
)
```

Multi-language targets follow this pattern:

```python
load("@rules_proto//proto:defs.bzl", "proto_library")
load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library")
load("@rules_cc//cc:defs.bzl", "cc_proto_library")

proto_library(
    name = "example_proto",
    srcs = ["example.proto"],
)

cc_proto_library(
    name = "example_cc_proto",
    deps = [":example_proto"],
)

go_proto_library(
    name = "example_go_proto",
    importpath = "example.com/path/to/example_proto",
    protos = [":example_proto"],
)
```

## 2. Proto File Style

### Required File Structure

```protobuf
edition = "2024";

package mycompany.myservice.v1;

// Language-specific options
option go_package = "example.com/path/to/package/name_proto";
option java_package = "com.example.myservice.v1";

// Imports (sorted alphabetically)
import "google/protobuf/timestamp.proto";

// Messages and enums (alphabetically ordered)
```

### Naming Conventions

| Element        | Style                  | Example            |
|----------------|------------------------|--------------------|
| Message names  | PascalCase             | `UserProfile`      |
| Field names    | snake_case             | `user_name`        |
| Enum names     | PascalCase             | `StatusCode`       |
| Enum values    | SCREAMING_SNAKE_CASE   | `STATUS_ACTIVE`    |
| Enum zero value| Must end with `_UNKNOWN` or `_UNSPECIFIED` | `STATUS_UNKNOWN = 0` |
| Service names  | PascalCase             | `UserService`      |
| RPC names      | PascalCase             | `GetUser`          |

## 3. Documentation: The Fine-Print Contract

**Write protobuf comments like detailed fine-print contracts.** Proto files are high-level interfaces shared across services and across time. Anyone writing code that uses this interface should have a crystal-clear understanding of the expected values.

**Base rule:** When other developers read your code just by looking at the field name and type, they should know exactly what values to expect. If not, use a better name or add more comments/examples.

### Document Everything

All of these **MUST** have documentation comments:
- Messages
- Fields
- Enums
- Enum values
- Services and RPCs

### Include Example Values

Always show example values when the format isn't obvious:

```protobuf
// Bad - unclear format
string timestamp = 1;
string software_version = 2;

// Good - with examples
// Represents process error codes as a 3-character string.
// E.g. "001", "022"
string error_code = 1;

// The unique device identifier. E.g. "device-abc123"
string device_id = 2;

// Software version in release format. E.g. "22.01", "release-22.01"
string software_version = 3;
```

### Specify Zero or Missing Value Behavior

By default, unset scalar fields are indistinguishable from zero values (implicit field presence). **Document what empty/zero means:**

```protobuf
// The user's preferred language code (ISO 639-1).
// E.g. "en", "ko". Empty string means the system default will be used.
string language_code = 1;

// Maximum retry attempts. Zero means no retries (fail immediately).
int32 max_retries = 2;

// Optional deadline for the operation.
// If not set (null), the operation has no timeout.
google.protobuf.Timestamp deadline = 3;
```

### RPC Error Documentation

For RPC services, **document possible error codes and failure conditions:**

```protobuf
service DeviceService {
  // GetStatus returns the current device status.
  //
  // Errors:
  //   - NOT_FOUND: Device with the given ID does not exist.
  //   - UNAVAILABLE: Device is offline or unreachable.
  //   - PERMISSION_DENIED: Caller lacks permission to access this device.
  rpc GetStatus(GetStatusRequest) returns (GetStatusResponse);

  // ExecuteCommand sends a command to the device.
  //
  // Errors:
  //   - INVALID_ARGUMENT: Command parameters are malformed.
  //   - FAILED_PRECONDITION: Device is not in a state to execute command
  //     (e.g., emergency stop is active).
  //   - DEADLINE_EXCEEDED: Device did not respond within timeout.
  rpc ExecuteCommand(ExecuteCommandRequest) returns (ExecuteCommandResponse);
}
```

### Complete Example

```protobuf
// UserProfile represents a user's public profile information.
message UserProfile {
  // The unique identifier for the user. E.g. "user-abc123"
  // Empty string is invalid and should never occur.
  string user_id = 1;

  // User's display name. E.g. "John Doe"
  // Empty string means the user has not set a display name.
  string display_name = 2;

  // Status indicates the user's current account status.
  enum Status {
    // STATUS_UNKNOWN is the default unset value.
    // Treat as an error if received.
    STATUS_UNKNOWN = 0;
    // STATUS_ACTIVE indicates the user is active and can use the system.
    STATUS_ACTIVE = 1;
    // STATUS_SUSPENDED indicates the user is temporarily suspended.
    STATUS_SUSPENDED = 2;
  }

  // Current account status. STATUS_UNKNOWN should never be set explicitly.
  Status status = 3;
}
```

## 4. Backward Compatibility

### Never Change Field Numbers

Field numbers are part of the wire format. Changing them breaks all existing serialized data and communicating peers.

If you delete a field, **reserve** both the field number and name:

```protobuf
message UserProfile {
  reserved 3, 7;
  reserved "old_field", "legacy_name";
  // ...
}
```

Do not reorganize or renumber fields. Field numbers are not meant to be sequential or tidy.

### Never Change Package or Message Names

The protobuf package path is orthogonal to language-specific import paths (e.g., `go_package`, `java_package`). Changing the protobuf package or message name is risky because:

- `google.protobuf.Any` encodes the full type URL (e.g., `type.googleapis.com/mypackage.MyMessage`). If sender and receiver use different proto versions, unmarshaling fails.
- Adding a `package` line where none existed is equally risky.

```protobuf
edition = "2024";
package mycompany.myservice.v1;  // Changing this breaks Any compatibility
```

### Field Name Changes

Field names are backward compatible for the **binary** wire format. However, they can break:
- JSON serialization (field names are used as JSON keys)
- Text proto format
- Field masks

Treat field name changes with caution in APIs that use JSON or text proto.

### Deprecation Protocol

When deprecating a field:

1. Mark it with `[deprecated = true]` and add a comment explaining:
   - **Why** it is deprecated
   - **What replaces it** (the recommended alternative)
   - **When** it will be removed (if known)
2. Ensure it **still works** — deprecation does not mean removal
3. No new code should depend on it

```protobuf
// DEPRECATED: Use display_name instead. Will be removed in v2.
// The user's full name.
string full_name = 3 [deprecated = true];
```

When ready to remove, delete the field and reserve both the number and name.

## 5. Design Patterns

### Prefer Enums Over Booleans

Boolean fields often grow beyond two states, and they have backward compatibility problems.

**The expansion problem:**

```protobuf
// Bad - what if we add bzip, zstd later?
bool compressed = 2;

// Good - extensible
enum Compression {
  COMPRESSION_UNSPECIFIED = 0;
  COMPRESSION_NONE = 1;
  COMPRESSION_GZIP = 2;
  COMPRESSION_ZSTD = 3;
}
Compression compression = 2;
```

**The backward compatibility problem:**

```protobuf
// Bad - old servers won't set this field, so the zero value (false)
// is indistinguishable from an explicit "not successful"
bool success = 2;

// Good - old servers return UNSPECIFIED, which clients can handle
enum Result {
  RESULT_UNSPECIFIED = 0;
  RESULT_SUCCESS = 1;
  RESULT_FAILURE = 2;
}
Result result = 2;
```

Code handling an enum can detect unknown values and fail explicitly, rather than silently misinterpreting a default `false`.

### Prefer Nested Over Flattened Messages

Group related fields into sub-messages for clarity and reusability:

```protobuf
// Good - nested structure
message MachineMetrics {
  // Primary key identifying which device these metrics belong to.
  string device_id = 1;

  // Process represents a single OS process on the device.
  message Process {
    // The process ID. E.g. 12345
    int32 pid = 1;
    // Effective user name of the process owner. E.g. "appuser"
    string user = 2;
    // CPU usage percentage (2 decimal points). E.g. 99.99
    float cpu_used_percentage = 3;
  }

  // Running processes on the device.
  repeated Process processes = 2;
}
```

### Use Well Known Types

Prefer Well Known Types over hand-rolled equivalents.

#### Timestamp

Use `google.protobuf.Timestamp` instead of strings for time points:

```protobuf
// Bad - ambiguous format, no type safety
string timestamp = 1;

// Good - standard type with language-specific utility functions
google.protobuf.Timestamp created_at = 1;
```

`Timestamp` serializes to RFC 3339 in JSON (e.g., `"2024-01-15T07:34:51.119Z"`) and to an efficient binary format on the wire. All supported languages provide utility functions for conversion.

If you must use a string for a timestamp, use RFC 3339 or ISO 8601 and document the format explicitly.

#### Duration

Use `google.protobuf.Duration` for time spans:

```protobuf
// Bad
int64 timeout_ms = 1;

// Good
google.protobuf.Duration timeout = 1;
```

#### Any

Use `google.protobuf.Any` for polymorphic message fields. Be aware that `Any` encodes the full type URL, so all possible message types must be available in the type registry at deserialization time.

```protobuf
import "google/protobuf/any.proto";

message Event {
  google.protobuf.Timestamp time = 1;
  // The event payload. All possible event types must be registered.
  google.protobuf.Any payload = 2;
}
```

#### Other Useful WKTs

| Type | Use For |
|------|---------|
| `google.protobuf.Struct` | Arbitrary JSON-like data |
| `google.protobuf.FieldMask` | Partial updates |
| `google.protobuf.Empty` | RPCs with no request/response payload |
| `google.protobuf.StringValue` (wrappers) | Distinguishing "unset" from zero with implicit presence |

## 6. Linting

### buf lint (recommended)

```bash
buf lint
```

Configure rules in `buf.yaml`:

```yaml
version: v2
lint:
  use:
    - STANDARD
    - COMMENTS
```

The `COMMENTS` rule set enforces documentation on messages, fields, enums, enum values, services, and RPCs.

### Bazel Integration

Projects using Bazel may have custom lint test rules. Check the project's build rules for proto lint targets and follow the existing pattern:

```python
# Example pattern - actual rule names vary by project
proto_library(
    name = "example_proto",
    srcs = ["example.proto"],
)

# Check project's build_rules/ or tools/ for the actual lint rule
proto_lint_test(
    name = "example_proto_lint",
    protos = [":example_proto"],
)
```

**Naming convention:** `{name}_proto` for the library, `{name}_proto_lint` for the lint test.

## 7. Formatting

### buf format

```bash
buf format -w          # Write changes
buf format -d          # Diff (dry run)
```

### clang-format

Some projects use `clang-format` for proto files:

```bash
clang-format -i *.proto
```

### Bazel

Check if the project has a format target:

```bash
bazel run //:format    # Project-specific target name
```

## 8. JSON Serialization Gotchas

When serializing proto messages to JSON, be aware of these common pitfalls:

- **Default value stripping:** By default, fields with zero/default values are omitted from JSON output. Use your language's "include default values" option if you need them.
- **Field name casing:** Proto JSON uses camelCase by default (e.g., `user_name` becomes `userName`). Use the "preserve proto field names" option if downstream systems expect snake_case.
- **Any type registry:** When using `google.protobuf.Any` with JSON, all possible message types must be available in the type registry, or deserialization will fail.

Wersje

W bazie nie ma innych skilli o nazwie protobuf-dev.

Migawka bazy z 13.11.2026 · wersja paczki ac467ad0753e (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100protobuf
    Obsługuje pliki Protocol Buffer (.proto), buf.yaml, buf.gen.yaml i buf.lock: projekt proto, CLI buf, usługi gRPC i Connect, ograniczenia protovalidate, ewolucja schematu oraz błędy lint i breaking.
  • 100rails-protobuf
    Wspiera budowę aplikacji Rails ze schematem API w Protocol Buffers: dodawanie RPC, komunikatów .proto i reguł buf.validate przez connect_rpc_rails i protobufable.
  • 100buf-cli-lint-breaking-build
    Pomaga w narzędziu buf: sprawdza lint, wykrywa zmiany łamiące kontrakt i buduje pliki protobuf, także w CI.
  • 100protobuf
    Definiuje schematy danych w Protocol Buffers i generuje typowany kod dla TypeScript, Go, Python i innych języków, z zasadami ewolucji schematu bez łamania klientów.
  • 100go-dev
    Dostarcza wiedzę do rozwoju w Go: idiomatyczne wzorce, obsługa błędów, testy, nazewnictwo pakietów i wykrywanie systemu budowania (toolchain Go, Bazel, Makefile).
  • 100protobuf-compat-checking
    Opakowuje buf breaking, aby porównać schemat Protobuf z wcześniejszą wersją, klasyfikuje zmiany łamiące zgodność (FILE, PACKAGE, WIRE_JSON, WIRE), konfiguruje reguły w buf.yaml i blokuje CI według kodu wyjścia.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.