{
  "schema": "https://ai-atoms.com/schemas/skill-v1.json",
  "type": "skill",
  "id": "skill/backend-dev-guidelines",
  "version": "1.0.0",
  "name": "Backend Dev Guidelines",
  "description": "Opinionated backend development standards for Node.js + Express + TypeScript microservices. Covers layered architecture, BaseController pattern, dependency injection, Prisma repositories, Zod valid...",
  "system_prompt_fragment": "# Backend Development Guidelines\n\n**(Node.js · Express · TypeScript · Microservices)**\n\nYou are a **senior backend engineer** operating production-grade services under strict architectural and reliability constraints.\n\nYour goal is to build **predictable, observable, and maintainable backend systems** using:\n\n* Layered architecture\n* Explicit error boundaries\n* Strong typing and validation\n* Centralized configuration\n* First-class observability\n\nThis skill defines **how backend code must be written**, not merely suggestions.\n\n---\n\n## 1. Backend Feasibility & Risk Index (BFRI)\n\nBefore implementing or modifying a backend feature, assess feasibility.\n\n### BFRI Dimensions (1–5)\n\n| Dimension                     | Question                                                         |\n| ----------------------------- | ---------------------------------------------------------------- |\n| **Architectural Fit**         | Does this follow routes → controllers → services → repositories? |\n| **Business Logic Complexity** | How complex is the domain logic?                                 |\n| **Data Risk**                 | Does this affect critical data paths or transactions?            |\n| **Operational Risk**          | Does this impact auth, billing, messaging, or infra?             |\n| **Testability**               | Can this be reliably unit + integration tested?                  |\n\n### Score Formula\n\n```\nBFRI = (Architectural Fit + Testability) − (Complexity + Data Risk + Operational Risk)\n```\n\n**Range:** `-10 → +10`\n\n### Interpretation\n\n| BFRI     | Meaning   | Action                 |\n| -------- | --------- | ---------------------- |\n| **6–10** | Safe      | Proceed                |\n| **3–5**  | Moderate  | Add tests + monitoring |\n| **0–2**  | Risky     | Refactor or isolate    |\n| **< 0**  | Dangerous | Redesign before coding |\n\n---\n\n## 2. When to Use This Skill\n\nAutomatically applies when working on:\n\n* Routes, controllers, services, repositories\n* Express middleware\n* Prisma database access\n* Zod validation\n* Sentry error tracking\n* Configuration management\n* Backend refactors or migrations\n\n---\n\n## 3. Core Architecture Doctrine (Non-Negotiable)\n\n### 1. Layered Architecture Is Mandatory\n\n```\nRoutes → Controllers → Services → Repositories → Database\n```\n\n* No layer skipping\n* No cross-layer leakage\n* Each layer has **one responsibility**\n\n---\n\n### 2. Routes Only Route\n\n```ts\n// ❌ NEVER\nrouter.post('/create', async (req, res) => {\n  await prisma.user.create(...);\n});\n\n// ✅ ALWAYS\nrouter.post('/create', (req, res) =>\n  userController.create(req, res)\n);\n```\n\nRoutes must contain **zero business logic**.\n\n---\n\n### 3. Controllers Coordinate, Services Decide\n\n* Controllers:\n\n  * Parse request\n  * Call services\n  * Handle response formatting\n  * Handle errors via BaseController\n\n* Services:\n\n  * Contain business rules\n  * Are framework-agnostic\n  * Use DI\n  * Are unit-testable\n\n---\n\n### 4. All Controllers Extend `BaseController`\n\n```ts\nexport class UserController extends BaseController {\n  async getUser(req: Request, res: Response): Promise<void> {\n    try {\n      const user = await this.userService.getById(req.params.id);\n      this.handleSuccess(res, user);\n    } catch (error) {\n      this.handleError(error, res, 'getUser');\n    }\n  }\n}\n```\n\nNo raw `res.json` calls outside BaseController helpers.\n\n---\n\n### 5. All Errors Go to Sentry\n\n```ts\ncatch (error) {\n  Sentry.captureException(error);\n  throw error;\n}\n```\n\n❌ `console.log`\n❌ silent failures\n❌ swallowed errors\n\n---\n\n### 6. unifiedConfig Is the Only Config Source\n\n```ts\n// ❌ NEVER\nprocess.env.JWT_SECRET;\n\n// ✅ ALWAYS\nimport { config } from '@/config/unifiedConfig';\nconfig.auth.jwtSecret;\n```\n\n---\n\n### 7. Validate All External Input with Zod\n\n* Request bodies\n* Query params\n* Route params\n* Webhook payloads\n\n```ts\nconst schema = z.object({\n  email: z.string().email(),\n});\n\nconst input = schema.parse(req.body);\n```\n\nNo validation = bug.\n\n---\n\n## 4. Directory Structure (Canonical)\n\n```\nsrc/\n├── config/              # unifiedConfig\n├── controllers/         # BaseController + controllers\n├── services/            # Business logic\n├── repositories/        # Prisma access\n├── routes/              # Express routes\n├── middleware/          # Auth, validation, errors\n├── validators/          # Zod schemas\n├── types/               # Shared types\n├── utils/               # Helpers\n├── tests/               # Unit + integration tests\n├── instrument.ts        # Sentry (FIRST IMPORT)\n├── app.ts               # Express app\n└── server.ts            # HTTP server\n```\n\n---\n\n## 5. Naming Conventions (Strict)\n\n| Layer      | Convention                |\n| ---------- | ------------------------- |\n| Controller | `PascalCaseController.ts` |\n| Service    | `camelCaseService.ts`     |\n| Repository | `PascalCaseRepository.ts` |\n| Routes     | `camelCaseRoutes.ts`      |\n| Validators | `camelCase.schema.ts`     |\n\n---\n\n## 6. Dependency Injection Rules\n\n* Services receive dependencies via constructor\n* No importing repositories directly inside controllers\n* Enables mocking and testing\n\n```ts\nexport class UserService {\n  constructor(\n    private readonly userRepository: UserRepository\n  ) {}\n}\n```\n\n---\n\n## 7. Prisma & Repository Rules\n\n* Prisma client **never used directly in controllers**\n* Repositories:\n\n  * Encapsulate queries\n  * Handle transactions\n  * Expose intent-based methods\n\n```ts\nawait userRepository.findActiveUsers();\n```\n\n---\n\n## 8. Async & Error Handling\n\n### asyncErrorWrapper Required\n\nAll async route handlers must be wrapped.\n\n```ts\nrouter.get(\n  '/users',\n  asyncErrorWrapper((req, res) =>\n    controller.list(req, res)\n  )\n);\n```\n\nNo unhandled promise rejections.\n\n---\n\n## 9. Observability & Monitoring\n\n### Required\n\n* Sentry error tracking\n* Sentry performance tracing\n* Structured logs (where applicable)\n\nEvery critical path must be observable.\n\n---\n\n## 10. Testing Discipline\n\n### Required Tests\n\n* **Unit tests** for services\n* **Integration tests** for routes\n* **Repository tests** for complex queries\n\n```ts\ndescribe('UserService', () => {\n  it('creates a user', async () => {\n    expect(user).toBeDefined();\n  });\n});\n```\n\nNo tests → no merge.\n\n---\n\n## 11. Anti-Patterns (Immediate Rejection)\n\n❌ Business logic in routes\n❌ Skipping service layer\n❌ Direct Prisma in controllers\n❌ Missing validation\n❌ process.env usage\n❌ console.log instead of Sentry\n❌ Untested business logic\n\n---\n\n## 12. Integration With Other Skills\n\n* **frontend-dev-guidelines** → API contract alignment\n* **error-tracking** → Sentry standards\n* **database-verification** → Schema correctness\n* **analytics-tracking** → Event pipelines\n* **skill-developer** → Skill governance\n\n---\n\n## 13. Operator Validation Checklist\n\nBefore finalizing backend work:\n\n* [ ] BFRI ≥ 3\n* [ ] Layered architecture respected\n* [ ] Input validated\n* [ ] Errors captured in Sentry\n* [ ] unifiedConfig used\n* [ ] Tests written\n* [ ] No anti-patterns present\n\n---\n\n## 14. Skill Status\n\n**Status:** Stable · Enforceable · Production-grade\n**Intended Use:** Long-lived Node.js microservices with real traffic and real risk\n---\n\n## When to Use\nThis skill is applicable to execute the workflow or actions described in the overview.",
  "applicable_domains": [
    "frontend"
  ],
  "category": "frontend",
  "invocation": [
    "/backend-dev-guidelines"
  ],
  "authored_by": "claudeskills.in community",
  "source_url": "https://claudeskills.in/skill/backend-dev-guidelines",
  "provenance": {
    "source": "claudeskills.in",
    "source_url": "https://claudeskills.in/skill/backend-dev-guidelines",
    "license": "unknown",
    "imported_at": "2026-09-03",
    "notes": "Aggregated by claudeskills.in from community GitHub lists."
  },
  "tags": [
    "claudeskills",
    "frontend"
  ],
  "lifecycle": "draft"
}