best-practices

Audit Dockerfile, compose and devcontainer.json files against the containers-best-practices rule set and offer each fix interactively. Walks every container file under a path, prints a prioritized findings report keyed by rule ID (DOCKER-, COMPOSE-, DEVC-, BUILDX-, SEC-, UV-), then applies fixes one at a time with per-finding approval. Use when asked to audit, scan, lint or harden containers, Dockerfiles, compose files or dev containers; never autofixes.

Use when working with Dockerfiles, docker-compose/compose.yml, buildx, dev containers (devcontainer.json), or .dockerignore — including Python container builds with uv. Covers image hardening, multi-stage builds, layer/cache ordering, BuildKit cache + secret mounts, compose services, GPU + Docker Model Runner, dev-container lifecycle and volume state, and container security footguns. For Python packaging outside containers use python-best-practices or uv-best-practices.

Use when working with SQLite or PostgreSQL (Postgres) from Python — sqlite3 connections, PRAGMA settings (journal_mode WAL, synchronous, foreign_keys, busy_timeout, optimize, user_version), SQLite schema and migrations, Postgres via psycopg and a SQLAlchemy pool, Alembic migrations, pg_advisory_xact_lock advisory locks, and SELECT FOR UPDATE row locking. Covers the SQLITE- and PG- rule families. Async SQLAlchemy session wiring in FastAPI lives in fastapi-best-practices.

Use when working with FastAPI apps — building or reviewing APIRouter route modules, Pydantic v2 request/response models, Depends() dependencies, lifespan startup/shutdown, OAuth2/JWT or bearer-token auth, pydantic-settings secrets, async SQLAlchemy sessions, TestClient/httpx tests, uvicorn deployment, or observability (OpenTelemetry tracing/metrics, OTLP export, X-Request-ID request id and log correlation, /healthz and /readyz probes, pure ASGI middleware). Covers the FAPI- rule family (structure, models/validation, settings, dependencies, path operations, errors, security, async DB, testing, deployment), OBS- (observability) and API- (bearer-token comparison, secret-file precedence). FastAPI-specific only; general Python rules live in python-best-practices.

Use when working with Go code — .go files and go.mod/go.sum, go build / go test / go test -race / go vet / gofmt / staticcheck / golangci-lint / govulncheck, module and package layout, error handling (errors.Is / %w), the context package, goroutines and channels, errgroup, stdlib net/http servers and clients, graceful shutdown on SIGINT/SIGTERM, parameterized SQL, or Go security (html/template, crypto/rand). Covers the GO- rule family (layout, errors, concurrency, HTTP, security, modules, quality, testing). Language-level Go only — container packaging lives in containers-best-practices, gRPC service rules in grpc-best-practices.

Use when working with gRPC — .proto files and proto3 schema design, enum zero values and _UNSPECIFIED sentinels, well-known types (google.protobuf.Timestamp / Duration / FieldMask), List pagination (page_size / page_token / next_page_token), buf or protoc generation, grpc-go / grpclib / grpcio servers and clients, google.rpc status codes and rich errors, deadlines and cancellation propagation, streaming RPCs (server/client/bidi), interceptors (auth, logging, panic recovery, protovalidate), TLS / mTLS transport credentials and the insecure-credentials footgun, server reflection + grpcurl/grpcui, health checking, message-size limits and connection reuse. Covers the GRPC- rule family (proto design, error model, deadlines, streaming, interceptors, security, tooling, performance). Protocol-level rules apply to any language; code examples are grpc-go. For the language underneath, see go-best-practices.

Use when adding, editing, or reviewing rules in the best-practices library — covers the rule-ID format (PREFIX-NNN), severity scale, four-part What/Why/How/When-NOT-to-apply reference structure, SKILL.md shape, third-person description-field rules, and how to use tools/new-skill.sh + tools/new-rule.sh + tools/lint.sh + tools/render-index.sh. Activate on phrases like "best practices format", "add a rule", "rule format", "severity scale", "new domain skill", or when generating content for any *-best-practices skill.

Use when working with Python projects — `.py` files, `pyproject.toml` (without `[tool.uv]`), `conftest.py`, `mypy.ini`, `pyrightconfig.json`, `.python-version` — or when the user asks about Python project layout, typing, linting, testing, async, logging, packaging, dependency auditing, or profiling. Mentions of pytest, mypy, pyright, basedpyright, ruff, structlog, hatch, or setuptools-scm are triggers. Covers the PY- rule family. For uv-specific patterns (`uv sync`, `[tool.uv]`, `uv.lock`) use uv-best-practices; for Python-in-Docker use containers-best-practices.

Use when editing repository hygiene and CI config — .pre-commit-config.yaml hooks, .github/dependabot.yml, GitHub Actions workflows (.github/workflows/*.yml, permissions, zizmor audits), CODEOWNERS, justfile task-runner recipes that CI calls, or secret scanning (gitleaks). Covers the REPO- rule family (pre-commit as a maintained artifact, one dependency bot with a cooldown, secret scanning, justfile/CI parity, CODEOWNERS, workflow static analysis, least-privilege GITHUB_TOKEN). Language-agnostic repo plumbing; language rules live in the language skills.

Use when working with uv (Astral's Python package and project manager) — `uv sync` / `add` / `lock` / `run` / `tool` / `build` / `publish` / `audit` / `export`, `uvx`, a `uv.lock` or `pylock.toml` file, or a `pyproject.toml` with `[tool.uv]` or `[dependency-groups]`. Covers project shape, lockfile hygiene, workspaces, dependency groups, private registries, Python version pinning, CI, publishing, vulnerability scanning, and migration from pip / poetry / PDM / Hatch. Covers the UVP- rule family. For container-side uv patterns (Dockerfile builds) use containers-best-practices instead.