AGENT SKILL

backend-dev-guidelines

Comprehensive backend development guide for Node.js/Express/TypeScript microservices. Use when creating routes, controllers, services, repositories, middleware, or working with Express APIs, Prisma database access, Sentry error tracking, Zod validation, unifiedConfig, dependency injection, or async patterns. Covers layered architecture (routes → controllers → services → repositories), BaseController pattern, error handling, performance monitoring, testing strategies, and migration from legacy patterns.

License 许可
MIT
最近更新
2026-11-12
Stars
★ 0
Forks
0

01 前言 Front Matter

name
backend-dev-guidelines
description
Comprehensive backend development guide for Node.js/Express/TypeScript microservices. Use when creating routes, controllers, services, repositories, middleware, or working with Express APIs, Prisma database access, Sentry error tracking, Zod validation, unifiedConfig, dependency injection, or async patterns. Covers layered architecture (routes → controllers → services → repositories), BaseController pattern, error handling, performance monitoring, testing strategies, and migration from legacy patterns.

02 资源文件 13

03 SKILL.md 正文

Backend Development Guidelines

Purpose

Establish consistency and best practices across backend microservices (blog-api, auth-service, notifications-service) using modern Node.js/Express/TypeScript patterns.

When to Use This Skill

Automatically activates when working on:

  • Creating or modifying routes, endpoints, APIs
  • Building controllers, services, repositories
  • Implementing middleware (auth, validation, error handling)
  • Database operations with Prisma
  • Error tracking with Sentry
  • Input validation with Zod
  • Configuration management
  • Backend testing and refactoring

Quick Start

New Backend Feature Checklist

  • [ ] Route: Clean definition, delegate to controller
  • [ ] Controller: Extend BaseController
  • [ ] Service: Business logic with DI
  • [ ] Repository: Database access (if complex)
  • [ ] Validation: Zod schema
  • [ ] Sentry: Error tracking
  • [ ] Tests: Unit + integration tests
  • [ ] Config: Use unifiedConfig

New Microservice Checklist

  • [ ] Directory structure (see architecture-overview.md)
  • [ ] instrument.ts for Sentry
  • [ ] unifiedConfig setup
  • [ ] BaseController class
  • [ ] Middleware stack
  • [ ] Error boundary
  • [ ] Testing framework

Architecture Overview

Layered Architecture

HTTP Request
    ↓
Routes (routing only)
    ↓
Controllers (request handling)
    ↓
Services (business logic)
    ↓
Repositories (data access)
    ↓
Database (Prisma)

Key Principle: Each layer has ONE responsibility.

See architecture-overview.md for complete details.


Directory Structure

service/src/
├── config/              # UnifiedConfig
├── controllers/         # Request handlers
├── services/            # Business logic
├── repositories/        # Data access
├── routes/              # Route definitions
├── middleware/          # Express middleware
├── types/               # TypeScript types
├── validators/          # Zod schemas
├── utils/               # Utilities
├── tests/               # Tests
├── instrument.ts        # Sentry (FIRST IMPORT)
├── app.ts               # Express setup
└── server.ts            # HTTP server

Naming Conventions:

  • Controllers: PascalCase - UserController.ts
  • Services: camelCase - userService.ts
  • Routes: camelCase + Routes - userRoutes.ts
  • Repositories: PascalCase + Repository - UserRepository.ts

Core Principles (7 Key Rules)

1. Routes Only Route, Controllers Control

// ❌ NEVER: Business logic in routes
router.post('/submit', async (req, res) => {
    // 200 lines of logic
});

// ✅ ALWAYS: Delegate to controller
router.post('/submit', (req, res) => controller.submit(req, res));

2. All Controllers Extend BaseController

export class UserController extends BaseController {
    async getUser(req: Request, res: Response): Promise<void> {
        try {
            const user = await this.userService.findById(req.params.id);
            this.handleSuccess(res, user);
        } catch (error) {
            this.handleError(error, res, 'getUser');
        }
    }
}

3. All Errors to Sentry

try {
    await operation();
} catch (error) {
    Sentry.captureException(error);
    throw error;
}

4. Use unifiedConfig, NEVER process.env

// ❌ NEVER
const timeout = process.env.TIMEOUT_MS;

// ✅ ALWAYS
import { config } from './config/unifiedConfig';
const timeout = config.timeouts.default;

5. Validate All Input with Zod

const schema = z.object({ email: z.string().email() });
const validated = schema.parse(req.body);

6. Use Repository Pattern for Data Access

// Service → Repository → Database
const users = await userRepository.findActive();

7. Comprehensive Testing Required

describe('UserService', () => {
    it('should create user', async () => {
        expect(user).toBeDefined();
    });
});

Common Imports

// Express
import express, { Request, Response, NextFunction, Router } from 'express';

// Validation
import { z } from 'zod';

// Database
import { PrismaClient } from '@prisma/client';
import type { Prisma } from '@prisma/client';

// Sentry
import * as Sentry from '@sentry/node';

// Config
import { config } from './config/unifiedConfig';

// Middleware
import { SSOMiddlewareClient } from './middleware/SSOMiddleware';
import { asyncErrorWrapper } from './middleware/errorBoundary';

Quick Reference

HTTP Status Codes

Code Use Case
200 Success
201 Created
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Server Error

Service Templates

Blog API (✅ Mature) - Use as template for REST APIs Auth Service (✅ Mature) - Use as template for authentication patterns


Anti-Patterns to Avoid

❌ Business logic in routes ❌ Direct process.env usage ❌ Missing error handling ❌ No input validation ❌ Direct Prisma everywhere ❌ console.log instead of Sentry


Navigation Guide

Need to... Read this
Understand architecture architecture-overview.md
Create routes/controllers routing-and-controllers.md
Organize business logic services-and-repositories.md
Validate input validation-patterns.md
Add error tracking sentry-and-monitoring.md
Create middleware middleware-guide.md
Database access database-patterns.md
Manage config configuration.md
Handle async/errors async-and-errors.md
Write tests testing-guide.md
See examples complete-examples.md

Resource Files

architecture-overview.md

Layered architecture, request lifecycle, separation of concerns

routing-and-controllers.md

Route definitions, BaseController, error handling, examples

services-and-repositories.md

Service patterns, DI, repository pattern, caching

validation-patterns.md

Zod schemas, validation, DTO pattern

sentry-and-monitoring.md

Sentry init, error capture, performance monitoring

middleware-guide.md

Auth, audit, error boundaries, AsyncLocalStorage

database-patterns.md

PrismaService, repositories, transactions, optimization

configuration.md

UnifiedConfig, environment configs, secrets

async-and-errors.md

Async patterns, custom errors, asyncErrorWrapper

testing-guide.md

Unit/integration tests, mocking, coverage

complete-examples.md

Full examples, refactoring guide


Related Skills

  • database-verification - Verify column names and schema consistency
  • error-tracking - Sentry integration patterns
  • skill-developer - Meta-skill for creating and managing skills

Skill Status: COMPLETE ✅ Line Count: < 500 ✅ Progressive Disclosure: 11 resource files ✅

04 同仓库更多 Skills

Gabriellmaia01
Gabriellmaia01/neuro-dose-assist

webapp-testing

Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.

测试与质量前端开发
★ 0
Gabriellmaia01
Gabriellmaia01/neuro-dose-assist

web-artifacts-builder

Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.

前端开发
★ 0
Gabriellmaia01
Gabriellmaia01/neuro-dose-assist

theme-factory

Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly.

视觉设计
★ 0
Gabriellmaia01
Gabriellmaia01/neuro-dose-assist

slack-gif-creator

Knowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."

邮件与沟通图像与多媒体
★ 0
Gabriellmaia01
Gabriellmaia01/neuro-dose-assist

skill-creator

Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.

Skill与智能体开发
★ 0
Gabriellmaia01
Gabriellmaia01/neuro-dose-assist

mcp-builder

Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).

Skill与智能体开发
★ 0