backend-dev-guidelines · git:20260729.43ab53a · 2026-07-29 · sha256 d50e2f20ae9ef0e8
backend-dev-guidelines git:20260729.43ab53aB
Immutable. This exact content never changes and is served at /api/v1/blob/d50e2f20ae9ef0e8.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_u3v4pj6cyh65vfri/d50e2f20ae9ef0e8528ecd3418888f7be7ca877773e7db9c2cd45fd18ea689f7.json
Then /plugin install backend-dev-guidelines@markdownregistry-u3v4pj6cyh65vfri in Claude Code. It installs this exact version, the one graded B here, pinned to the commit it was graded at, and leaves it there.
--- name: backend-dev-guidelines description: Build or review Langfuse backend code. Use for tRPC routers, public REST APIs, BullMQ processors, services, middleware, Prisma or ClickHouse access, OpenTelemetry, Zod, environment configuration, or backend tests. --- # Backend Development Guidelines Use this skill for backend and API work across `web/`, `worker/`, and `packages/shared/`. ## When to Apply - Creating or modifying tRPC routers and procedures - Creating or modifying public API endpoints - Creating or modifying queue processors, producers, or queue-backed workflows - Building or refactoring backend services and repositories - Working on backend auth, middleware, validation, or observability - Updating Prisma or ClickHouse access patterns - Adding or fixing backend tests ## How to Read This Skill - Use this `SKILL.md` when the task spans multiple backend areas or you need the end-to-end reference map. - Read only the specific reference file that matches the work when the scope is narrower. - If the task introduces a user-supplied URL, an outbound HTTP request, a new integration, or touches secrets, RBAC, or redirect handling, also load the shared [`security-review`](../security-review/SKILL.md) skill before designing or implementing the change. ## Quick Start Checklists ### UI: New tRPC Feature - Define the router in `features/[feature]/server/*Router.ts`. - Use the appropriate protected or public procedure. - Authenticate with JWT-aware middleware. - Check project/resource access and entitlements. - Validate input with Zod v4. - Put business logic in a service file. - Use `traceException` for error handling where relevant. - Add unit or integration tests in `__tests__/`. - Access config via `env.mjs`. ### Existing Endpoint: Additive Field or Filter Before coding, classify the change as a new endpoint, an additive field/filter on an existing endpoint, or a semantic replacement/breaking change. For an additive field/filter: - Reuse the canonical predicate. For endpoints that already support field-group selection, reuse their existing field-group/projection path. - Preserve the endpoint's existing response contract: use the normal optional partial-row schema and converter path for field-group endpoints; retain the strict response schema and converter path for ordinary endpoints. - Do not create API-version-specific field sets, casts, or "must be selected" runtime assertions unless compatibility requires them. - Extend examples and contracts; do not replace an existing filter example. - Write one test per unique boundary, not one test per file touched. ### SDKs: New Public API Endpoint - Create the route in `pages/api/public/`. - Wrap it with `withMiddlewares` and `createAuthedProjectAPIRoute`. - Define types in `features/public-api/types/`. - Authenticate with basic auth. - Validate query, body, and response with Zod schemas. - Include API versioning in paths and schemas. - Update Fern API definitions to match TypeScript types. - Add end-to-end tests in `__tests__/async/`. ### Worker: New Queue Processor - Create the processor in `worker/src/queues/`. - Define queue types in `packages/shared/src/server/queues`. - Place business logic in `features/` or `worker/src/features/`. - Distinguish failed jobs from jobs that should succeed with a recorded error. - Register the queue in `WorkerManager` in `app.ts`. - Add worker vitest coverage. ## Core Principles - tRPC procedures, public API routes, and queue processors delegate business logic to services. - Access configuration through `env.mjs`; do not read `process.env` directly outside env setup. - Validate all external input with Zod v4. - Use Prisma directly for simple CRUD and repositories for complex query access. - Use OpenTelemetry and DataDog for backend observability. - Always filter project-scoped database queries by `projectId`. - Keep Fern API definitions in sync with public TypeScript API contracts. - Keep backend tests independent and parallel-safe. ## Live Examples - tRPC router with project auth and Zod input: `web/src/features/events/server/eventsRouter.ts`. - Public API route with middleware and typed request/response schemas: `web/src/pages/api/public/datasets/index.ts`. - Worker queue processor with typed jobs, logging, and retry behavior: `worker/src/queues/evalQueue.ts`. - Tenant filters for Prisma and ClickHouse: `references/database-patterns.md`. ## Naming Conventions - tRPC routers: `camelCaseRouter.ts`, for example `datasetRouter.ts`. - Services: `service.ts` in the feature server directory. - Queue processors: `camelCaseQueue.ts`, for example `evalQueue.ts`. - Public API routes: kebab-case filenames, for example `dataset-items.ts`. ## Anti-Patterns to Avoid - Business logic in routes or procedures. - Direct `process.env` usage instead of `env.mjs` / `env.ts`. - Missing error handling. - Missing input validation. - Missing `projectId` filters on tenant-scoped queries. - `console.log` instead of `logger` / `traceException`. ## Reference Map | Topic | Read this when | File | | ----------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | | Architecture and package boundaries | You need the web/worker/shared split, request flow, or queue lifecycle | [references/architecture-overview.md](references/architecture-overview.md) | | Routing and controllers | You are writing tRPC procedures, public API routes, or queue entrypoints | [references/routing-and-controllers.md](references/routing-and-controllers.md) | | Middleware and auth | You are changing request auth, permissions, or middleware composition | [references/middleware-guide.md](references/middleware-guide.md) | | Services and repositories | You are placing business logic, repository code, or DI patterns | [references/services-and-repositories.md](references/services-and-repositories.md) | | Database access | You are touching Prisma, ClickHouse, tenant filters, or query patterns | [references/database-patterns.md](references/database-patterns.md) | | Configuration | You are adding env vars, startup config, or runtime toggles | [references/configuration.md](references/configuration.md) | | Testing | You are adding or updating backend tests | [references/testing-guide.md](references/testing-guide.md) |