backend-dev-guidelines

Enforces layered architecture standards for Node.js Express TypeScript microservices.

Updated Jul 29, 2026
One-click install
npx skills add https://github.com/MaiconGambini/opencode-harness-guide --skill backend-dev-guidelines-maicongambini
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: backend-dev-guidelines
Source: https://github.com/MaiconGambini/opencode-harness-guide/tree/main/skills/backend-dev-guidelines
Command: npx skills add https://github.com/MaiconGambini/opencode-harness-guide --skill backend-dev-guidelines-maicongambini

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Backend codebases often drift into inconsistent patterns: business logic leaking into routes, direct process.env access, missing input validation, and swallowed errors. This Skill enforces a strict, opinionated architecture for Node.js + Express + TypeScript microservices so every route, controller, service, and repository follows the same production-grade rules. ## Core Features & Use Cases - Layered Architecture Enforcement: Mandates the Routes → Controllers → Services → Repositories flow with a BaseController pattern, dependency injection, and Prisma repositories. - BFRI Risk Scoring: Provides a Backend Feasibility & Risk Index to assess whether a change is safe, moderate, risky, or dangerous before implementation. - Validation, Config & Observability Rules: Requires Zod validation for all external input, unifiedConfig as the only configuration source, and Sentry capture for all errors. - Use Case: When asked to add a new REST endpoint, the Skill generates a clean route delegating to a BaseController-based controller, a DI-driven service with business rules, a Prisma repository, Zod schemas, and tests—while rejecting anti-patterns like logic in routes. ## Quick Start Ask the agent to create a new Express endpoint for user management following the backend development guidelines, including validation, error handling, and tests.

Frequently Asked Questions about backend-dev-guidelines

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I structure an Express TypeScript microservice with layered architecture?

Organize code into Routes, Controllers, Services, and Repositories where each layer has one responsibility. Routes only register paths and middleware, controllers handle HTTP concerns via a BaseController, services contain business logic, and repositories encapsulate Prisma queries.

How to validate request input in Express with Zod?

Define Zod schemas for request bodies, query params, and route params, then parse them in the controller before calling services. Unvalidated external input is treated as a bug, and ZodError instances map to 400 responses.

Should I use process.env directly in Node.js backend code?

No. Use a unifiedConfig module as the single source of truth that reads config files, falls back to environment variables, validates at startup, and provides type-safe access. Direct process.env usage causes typos, missing defaults, and untestable code.

How do I handle async errors in Express routes?

Wrap every async route handler with an asyncErrorWrapper that forwards rejections to next(error), and register an error boundary middleware after all routes. All caught errors must be captured to Sentry rather than logged with console.log or silently swallowed.

When should I use the repository pattern with Prisma?

Use repositories when queries are complex, reused in multiple places, need caching, or must be mocked for testing. Repositories expose intent-based methods like findActiveUsers and keep Prisma client calls out of controllers and services.

What is the BFRI score and when does it block backend work?

BFRI (Backend Feasibility & Risk Index) scores architectural fit and testability against complexity, data risk, and operational risk on a -10 to +10 scale. Scores below 3 require refactoring, isolation, or redesign before implementation proceeds.