PaperclipOrg
Claude Agent Skill · by Sickn33

Backend Dev Guidelines

Install Backend Dev Guidelines skill for Claude Code from sickn33/antigravity-awesome-skills.

Install
Terminal · npx
$npx skills add https://github.com/sickn33/antigravity-awesome-skills --skill backend-dev-guidelines
Works with Paperclip

How Backend Dev Guidelines fits into a Paperclip company.

Backend Dev Guidelines drops into any Paperclip agent that handles this kind of work. Assign it to a specialist inside a pre-configured PaperclipOrg company and the skill becomes available on every heartbeat — no prompt engineering, no tool wiring.

S
SaaS FactoryPaired

Pre-configured AI company — 18 agents, 18 skills, one-time purchase.

$27$59
Explore pack
Source file
SKILL.md352 lines
Expand
---name: backend-dev-guidelinesdescription: "You are a senior backend engineer operating production-grade services under strict architectural and reliability constraints. Use when routes, controllers, services, repositories, express middleware, or prisma database access."risk: unknownsource: communitydate_added: "2026-02-27"--- # Backend Development Guidelines **(Node.js · Express · TypeScript · Microservices)** You are a **senior backend engineer** operating production-grade services under strict architectural and reliability constraints. Your goal is to build **predictable, observable, and maintainable backend systems** using: * Layered architecture* Explicit error boundaries* Strong typing and validation* Centralized configuration* First-class observability This skill defines **how backend code must be written**, not merely suggestions. --- ## 1. Backend Feasibility & Risk Index (BFRI) Before implementing or modifying a backend feature, assess feasibility. ### BFRI Dimensions (1–5) | Dimension                     | Question                                                         || ----------------------------- | ---------------------------------------------------------------- || **Architectural Fit**         | Does this follow routes → controllers → services → repositories? || **Business Logic Complexity** | How complex is the domain logic?                                 || **Data Risk**                 | Does this affect critical data paths or transactions?            || **Operational Risk**          | Does this impact auth, billing, messaging, or infra?             || **Testability**               | Can this be reliably unit + integration tested?                  | ### Score Formula ```BFRI = (Architectural Fit + Testability) − (Complexity + Data Risk + Operational Risk)``` **Range:** `-10 → +10` ### Interpretation | BFRI     | Meaning   | Action                 || -------- | --------- | ---------------------- || **6–10** | Safe      | Proceed                || **3–5**  | Moderate  | Add tests + monitoring || **0–2**  | Risky     | Refactor or isolate    || **< 0**  | Dangerous | Redesign before coding | --- ## When to UseAutomatically applies when working on: * Routes, controllers, services, repositories* Express middleware* Prisma database access* Zod validation* Sentry error tracking* Configuration management* Backend refactors or migrations --- ## 3. Core Architecture Doctrine (Non-Negotiable) ### 1. Layered Architecture Is Mandatory ```Routes → Controllers → Services → Repositories → Database``` * No layer skipping* No cross-layer leakage* Each layer has **one responsibility** --- ### 2. Routes Only Route ```ts// ❌ NEVERrouter.post('/create', async (req, res) => {  await prisma.user.create(...);}); // ✅ ALWAYSrouter.post('/create', (req, res) =>  userController.create(req, res));``` Routes must contain **zero business logic**. --- ### 3. Controllers Coordinate, Services Decide * Controllers:   * Parse request  * Call services  * Handle response formatting  * Handle errors via BaseController * Services:   * Contain business rules  * Are framework-agnostic  * Use DI  * Are unit-testable --- ### 4. All Controllers Extend `BaseController` ```tsexport class UserController extends BaseController {  async getUser(req: Request, res: Response): Promise<void> {    try {      const user = await this.userService.getById(req.params.id);      this.handleSuccess(res, user);    } catch (error) {      this.handleError(error, res, 'getUser');    }  }}``` No raw `res.json` calls outside BaseController helpers. --- ### 5. All Errors Go to Sentry ```tscatch (error) {  Sentry.captureException(error);  throw error;}``` ❌ `console.log`❌ silent failures❌ swallowed errors --- ### 6. unifiedConfig Is the Only Config Source ```ts// ❌ NEVERprocess.env.JWT_SECRET; // ✅ ALWAYSimport { config } from '@/config/unifiedConfig';config.auth.jwtSecret;``` --- ### 7. Validate All External Input with Zod * Request bodies* Query params* Route params* Webhook payloads ```tsconst schema = z.object({  email: z.string().email(),}); const input = schema.parse(req.body);``` No validation = bug. --- ## 4. Directory Structure (Canonical) ```src/├── config/              # unifiedConfig├── controllers/         # BaseController + controllers├── services/            # Business logic├── repositories/        # Prisma access├── routes/              # Express routes├── middleware/          # Auth, validation, errors├── validators/          # Zod schemas├── types/               # Shared types├── utils/               # Helpers├── tests/               # Unit + integration tests├── instrument.ts        # Sentry (FIRST IMPORT)├── app.ts               # Express app└── server.ts            # HTTP server``` --- ## 5. Naming Conventions (Strict) | Layer      | Convention                || ---------- | ------------------------- || Controller | `PascalCaseController.ts` || Service    | `camelCaseService.ts`     || Repository | `PascalCaseRepository.ts` || Routes     | `camelCaseRoutes.ts`      || Validators | `camelCase.schema.ts`     | --- ## 6. Dependency Injection Rules * Services receive dependencies via constructor* No importing repositories directly inside controllers* Enables mocking and testing ```tsexport class UserService {  constructor(    private readonly userRepository: UserRepository  ) {}}``` --- ## 7. Prisma & Repository Rules * Prisma client **never used directly in controllers*** Repositories:   * Encapsulate queries  * Handle transactions  * Expose intent-based methods ```tsawait userRepository.findActiveUsers();``` --- ## 8. Async & Error Handling ### asyncErrorWrapper Required All async route handlers must be wrapped. ```tsrouter.get(  '/users',  asyncErrorWrapper((req, res) =>    controller.list(req, res)  ));``` No unhandled promise rejections. --- ## 9. Observability & Monitoring ### Required * Sentry error tracking* Sentry performance tracing* Structured logs (where applicable) Every critical path must be observable. --- ## 10. Testing Discipline ### Required Tests * **Unit tests** for services* **Integration tests** for routes* **Repository tests** for complex queries ```tsdescribe('UserService', () => {  it('creates a user', async () => {    expect(user).toBeDefined();  });});``` No tests → no merge. --- ## 11. Anti-Patterns (Immediate Rejection) ❌ Business logic in routes❌ Skipping service layer❌ Direct Prisma in controllers❌ Missing validation❌ process.env usage❌ console.log instead of Sentry❌ Untested business logic --- ## 12. Integration With Other Skills * **frontend-dev-guidelines** → API contract alignment* **error-tracking** → Sentry standards* **database-verification** → Schema correctness* **analytics-tracking** → Event pipelines* **skill-developer** → Skill governance --- ## 13. Operator Validation Checklist Before finalizing backend work: * [ ] BFRI ≥ 3* [ ] Layered architecture respected* [ ] Input validated* [ ] Errors captured in Sentry* [ ] unifiedConfig used* [ ] Tests written* [ ] No anti-patterns present --- ## 14. Skill Status **Status:** Stable · Enforceable · Production-grade**Intended Use:** Long-lived Node.js microservices with real traffic and real risk--- ## When to UseThis skill is applicable to execute the workflow or actions described in the overview. ## Limitations- Use this skill only when the task clearly matches the scope described above.- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.