AGENT SKILL

rust-best-practices

Guide for writing idiomatic Rust code based on Apollo GraphQL's best practices handbook. Use this skill when: (1) writing new Rust code or functions, (2) reviewing or refactoring existing Rust code, (3) deciding between borrowing vs cloning or ownership patterns, (4) implementing error handling with Result types, (5) optimizing Rust code for performance, (6) writing tests or documentation for Rust projects.

License 许可
MIT
最近更新
2026-11-13
Stars
★ 29
Forks
156

01 前言 Front Matter

name
rust-best-practices
license
MIT
metadata
{ "author": "apollographql", "version": "1.1.1" }
description
Guide for writing idiomatic Rust code based on Apollo GraphQL's best practices handbook. Use this skill when: (1) writing new Rust code or functions, (2) reviewing or refactoring existing Rust code, (3) deciding between borrowing vs cloning or ownership patterns, (4) implementing error handling with Result types, (5) optimizing Rust code for performance, (6) writing tests or documentation for Rust projects.
allowed-tools
Bash(cargo:*) Bash(rustc:*) Bash(rustfmt:*) Bash(clippy:*) Read Write Edit Glob Grep
compatibility
Rust 1.70+, Cargo

02 资源文件 9

03 SKILL.md 正文

Rust Best Practices

Apply these guidelines when writing or reviewing Rust code. Based on Apollo GraphQL's Rust Best Practices Handbook.

Best Practices Reference

Before reviewing, familiarize yourself with Apollo's Rust best practices. Read ALL relevant chapters in the same turn in parallel. Reference these files when providing feedback:

Quick Reference

Borrowing & Ownership

  • Prefer &T over .clone() unless ownership transfer is required
  • Use &str over String, &[T] over Vec<T> in function parameters
  • Small Copy types (≤24 bytes) can be passed by value
  • Use Cow<'_, T> when ownership is ambiguous

Error Handling

  • Return Result<T, E> for fallible operations; avoid panic! in production
  • Never use unwrap()/expect() outside tests
  • Use thiserror for library errors, anyhow for binaries only
  • Prefer ? operator over match chains for error propagation

Performance

  • Always benchmark with --release flag
  • Run cargo clippy -- -D clippy::perf for performance hints
  • Avoid cloning in loops; use .iter() instead of .into_iter() for Copy types
  • Prefer iterators over manual loops; avoid intermediate .collect() calls

Linting

Run regularly: cargo clippy --all-targets --all-features --locked -- -D warnings

Key lints to watch:

  • redundant_clone - unnecessary cloning
  • large_enum_variant - oversized variants (consider boxing)
  • needless_collect - premature collection

Use #[expect(clippy::lint)] over #[allow(...)] with justification comment.

Testing

  • Name tests descriptively: process_should_return_error_when_input_empty()
  • One assertion per test when possible
  • Use doc tests (///) for public API examples
  • Consider cargo insta for snapshot testing generated output

Generics & Dispatch

  • Prefer generics (static dispatch) for performance-critical code
  • Use dyn Trait only when heterogeneous collections are needed
  • Box at API boundaries, not internally

Type State Pattern

Encode valid states in the type system to catch invalid operations at compile time:

struct Connection<State> { /* ... */ _state: PhantomData<State> }
struct Disconnected;
struct Connected;

impl Connection<Connected> {
    fn send(&self, data: &[u8]) { /* only connected can send */ }
}

Documentation

  • // comments explain why (safety, workarounds, design rationale)
  • /// doc comments explain what and how for public APIs
  • Every TODO needs a linked issue: // TODO(#42): ...
  • Enable #![deny(missing_docs)] for libraries

04 同仓库更多 Skills

CognitionAI
CognitionAI/devin-marketplace

business-data

暂无简介

★ 29
CognitionAI
CognitionAI/devin-marketplace

workflow

Creates durable, resumable workflows using Vercel's Workflow SDK. Use when building workflows that need to survive restarts, pause for external events, retry on failure, or coordinate multi-step operations over time. Triggers on mentions of "workflow", "durable functions", "resumable", "workflow sdk", "queue", "event", "push", "subscribe", or step-based orchestration.

★ 29
CognitionAI
CognitionAI/devin-marketplace

workflow

Vercel Workflow SDK expert guidance. Use when building durable workflows, long-running tasks, API routes or agents that need pause/resume, retries, step-based execution, or crash-safe orchestration with Vercel Workflow.

★ 29
CognitionAI
CognitionAI/devin-marketplace

verification

Full-story verification — infers what the user is building, then verifies the complete flow end-to-end: browser → API → data → response. Triggers on dev server start and 'why isn't this working' signals.

★ 29
CognitionAI
CognitionAI/devin-marketplace

vercel-storage

Vercel storage expert guidance — Blob, Global Config (formerly Edge Config), and Marketplace storage (Neon Postgres, Upstash Redis). Use when choosing, configuring, or using data storage with Vercel applications.

★ 29
CognitionAI
CognitionAI/devin-marketplace

vercel-services

Configure and troubleshoot Vercel Services for multiple frontends and backends in one project. Use when composing a polyglot or multi-service application on one Vercel deployment; defining the `services` key, service-targeted rewrites, or service bindings in `vercel.json`; or running all services with `vercel dev`.

★ 29