backend-dev-guidelines

name	backend-dev-guidelines
name_zh	后端开发指南
description	Shared backend guide for Langfuse's Next.js, tRPC, BullMQ, and TypeScript
description_zh	遵循后端开发最佳实践，包括 API 设计、数据库操作和安全性。
category	dev-tools
tags	["ai","api","backend","cli","database"]
source	null
license	UNKNOWN
language	en
author	unknown
version	0.1.0
needs_review	false
slug	backend-dev-guidelines
created	2026-06-12
updated	2026-06-12
inputs	[{"name":"request","type":"string","required":true,"description":"User request or task description"}]
output	{"format":"markdown","description":"Generated content based on the user request"}

When to use

Use this skill when you need guidance on backend dev guidelines.

Inputs

User request or task description.

Output

Generated content based on the user request.

Prompt

Follow the guidelines in this skill when working on related tasks.

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 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.

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
Routing and controllers	You are writing tRPC procedures, public API routes, or queue entrypoints	references/routing-and-controllers.md
Middleware and auth	You are changing request auth, permissions, or middleware composition	references/middleware-guide.md
Services and repositories	You are placing business logic, repository code, or DI patterns	references/services-and-repositories.md
Database access	You are touching Prisma, ClickHouse, tenant filters, or query patterns	references/database-patterns.md
Configuration	You are adding env vars, startup config, or runtime toggles	references/configuration.md
Testing	You are adding or updating backend tests	references/testing-guide.md

When NOT to use

Do not use this skill for tasks outside its scope.

Example

See the skill content above for practical examples.

# 使用 backend-dev-guidelines 技能
python scripts/use-skill.py backend-dev-guidelines

# 查看技能详情
python scripts/inspect-skill.py backend-dev-guidelines

# 验证技能
python scripts/validate-skill.py backend-dev-guidelines