{"id":"0b107dd0-b649-48c7-9269-a92b55e95703","shortId":"fBV3YB","kind":"skill","title":"backend-dev-guidelines","tagline":"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.","description":"# 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## When to Use\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## 2. 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## 3. 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## 4. 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## 5. 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## 6. 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## 7. 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## 8. 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## 9. 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## 10. 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## 11. 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## 12. 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## 13. 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.\n\n## Limitations\n- Use this skill only when the task clearly matches the scope described above.\n- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.\n- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.","tags":["backend","dev","guidelines","antigravity","awesome","skills","sickn33","agent-skills","agentic-skills","ai-agent-skills","ai-agents","ai-coding"],"capabilities":["skill","source-sickn33","skill-backend-dev-guidelines","topic-agent-skills","topic-agentic-skills","topic-ai-agent-skills","topic-ai-agents","topic-ai-coding","topic-ai-workflows","topic-antigravity","topic-antigravity-skills","topic-claude-code","topic-claude-code-skills","topic-codex-cli","topic-codex-skills"],"categories":["antigravity-awesome-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/sickn33/antigravity-awesome-skills/backend-dev-guidelines","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add sickn33/antigravity-awesome-skills","source_repo":"https://github.com/sickn33/antigravity-awesome-skills","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 37911 github stars · SKILL.md body (7,518 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T18:50:40.880Z","embedding":null,"createdAt":"2026-04-18T20:33:35.908Z","updatedAt":"2026-05-18T18:50:40.880Z","lastSeenAt":"2026-05-18T18:50:40.880Z","tsv":"'+10':177 '-10':176 '/config/unifiedconfig':392 '/create':268,276 '/users':551 '0':192,198 '1':97,114,238 '10':183,615 '11':643 '12':675 '13':703 '2':193,231,261 '3':186,288,423,684 '4':319,468 '5':115,187,359,484 '6':182,377,512 '7':394,536 '8':562 '9':582 'access':33,219,438 'action':181,737 'add':189 'affect':140 'agnost':312 'align':654 'alway':274,388 'analyt':666 'analytics-track':665 'anti':617,700 'anti-pattern':616,699 'api':652 'app':464 'app.ts':462 'appli':207 'applic':575,731 'architectur':18,54,71,118,167,233,240,686 'ask':775 'assess':110 'async':269,330,537,543,607 'asyncerrorwrapp':540,552 'auth':151,443 'automat':206 'await':272,340,534 'backend':2,9,34,45,67,89,98,108,227,681 'backend-dev-guidelin':1 'base':531 'basecontrol':304,323,329,357,431 'bfri':102,112,166,179,683 'bill':152 'bodi':402 'boundari':74,783 'bug':422 'build':62 'busi':127,286,307,434,621,641 'call':296,355 'camelcase.schema.ts':483 'camelcaseroutes.ts':481 'camelcaseservice.ts':477 'canon':426 'captur':691 'catch':346,366 'central':79 'checklist':678 'clarif':777 'class':83,326,505 'clear':750 'client':517 'code':90,202 'complex':129,131,170,598 'config':382,390,428 'config.auth.jwtsecret':393 'configur':80,225 'console.log':372,636 'const':338,410,416 'constraint':21,57 'constructor':492,507 'contain':284,306 'contract':653 'control':25,124,212,244,289,293,321,430,432,474,498,522,631 'controller.list':555 'convent':470,473 'coordin':290 'core':232 'correct':664 'creat':604 'criteria':786 'critic':141,577 'cross':253 'cross-lay':252 'danger':199 'data':136,142,171 'databas':32,218,247,661 'database-verif':660 'decid':292 'defin':87 'depend':485,490 'describ':601,738,754 'dev':3,650 'develop':35,672 'di':314 'dimens':113,116 'direct':496,520,628 'directori':424 'disciplin':584 'doctrin':234 'domain':134 'email':413,415 'enabl':499 'encapsul':524 'enforc':708 'engin':10,46 'environ':766 'environment-specif':765 'error':73,223,302,347,349,361,367,369,371,376,445,538,567,656,690 'error-track':655 'event':668 'everi':576 'execut':733 'expect':608 'expert':771 'explicit':72 'export':325,504 'expos':528 'express':28,38,215,440,463 'extend':322,328 'extern':397 'failur':374 'feasibl':99,111 'featur':109 'final':680 'first':82,460 'first-class':81 'fit':119,168 'follow':122 'format':300 'formula':165 'framework':311 'framework-agnost':310 'frontend':649 'frontend-dev-guidelin':648 'getus':331,351 'go':362 'goal':59 'govern':674 'grade':14,50,711 'guidelin':4,36,651 'handl':298,301,526,539 'handler':545 'helper':358,453 'http':466 'immedi':619 'impact':150 'implement':104 'import':389,461,494 'index':101 'infra':155 'inject':486 'input':398,417,688,780 'insid':497 'instead':637 'instrument.ts':458 'integr':162,456,591,644 'intend':712 'intent':530 'intent-bas':529 'interpret':178 'isol':197 'layer':70,239,249,254,257,472,627,685 'leakag':255 'limit':742 'live':716 'log':573 'logic':128,135,287,435,622,642 'long':715 'long-liv':714 'maintain':66 'manag':226 'mandatori':242 'match':751 'mean':180 'mere':95 'merg':614 'messag':153 'method':532 'microservic':40,718 'middlewar':29,216,442 'migrat':230 'miss':632,788 'mock':500 'moder':188 'modifi':106 'monitor':191,564 'must':91,283,546,579 'name':469 'negoti':237 'never':266,385,518 'node.js':37,717 'non':236 'non-negoti':235 'observ':64,84,563,581 'one':259 'oper':11,47,146,173,676 'output':760 'outsid':356 'overview':741 'param':404,406 'pars':294 'pascalcasecontroller.ts':475 'pascalcaserepository.ts':479 'path':143,578 'pattern':618,701 'payload':408 'perform':570 'permiss':781 'pipelin':669 'predict':63 'present':702 'prisma':31,217,437,513,516,629 'prisma.user.create':273 'privat':508 'proceed':185 'process.env':634 'process.env.jwt':386 'product':13,49,710 'production-grad':12,48,709 'promis':336,560 'queri':403,525,599 'question':117 'rang':175 'raw':353 'readon':509 'real':720,723 'receiv':489 'redesign':200 'refactor':195,228 'reject':561,620 'reliabl':20,56,160 'repositori':27,126,214,246,436,478,495,514,523,595 'req':270,277,280,332,553,556 'req.body':419 'req.params.id':342 'request':295,333,401 'requir':541,565,585,779 'res':271,278,281,334,344,350,554,557 'res.json':354 'respect':687 'respons':260,299,335 'review':772 'risk':100,137,147,172,174,724 'riski':194 'rout':24,123,211,243,262,264,282,405,439,441,480,544,594,624 'router.get':550 'router.post':267,275 'rule':308,487,515 'safe':184 'safeti':782 'schema':411,448,663 'schema.parse':418 'scope':753 'score':164 'secret':387 'senior':8,44 'sentri':222,364,459,566,569,639,658,693 'sentry.captureexception':368 'server':467 'server.ts':465 'servic':15,26,51,125,213,245,291,297,305,433,476,488,590,626 'share':450 'silent':373 'skill':86,647,671,673,704,729,745 'skill-backend-dev-guidelines' 'skill-develop':670 'skip':250,625 'sourc':383 'source-sickn33' 'specif':767 'src':427 'stabl':707 'standard':659 'status':705,706 'stop':773 'strict':17,53,471 'strong':75 'structur':425,572 'substitut':763 'success':785 'suggest':96 'swallow':375 'system':68 'task':749 'test':163,190,454,457,502,583,586,588,592,596,612,696,769 'testabl':156,169,318 'this.handleerror':348 'this.handlesuccess':343 'this.userservice.getbyid':341 'throw':370 'tobedefin':610 'topic-agent-skills' 'topic-agentic-skills' 'topic-ai-agent-skills' 'topic-ai-agents' 'topic-ai-coding' 'topic-ai-workflows' 'topic-antigravity' 'topic-antigravity-skills' 'topic-claude-code' 'topic-claude-code-skills' 'topic-codex-cli' 'topic-codex-skills' 'trace':571 'track':224,568,657,667 'traffic':721 'transact':145,527 'treat':758 'tri':337 'ts':265,324,365,384,409,503,533,549,600 'type':76,449,451 'typescript':39 'unhandl':559 'unifiedconfig':378,429,694 'unit':161,317,455,587 'unit-test':316 'untest':640 'usag':635 'use':22,69,205,313,519,695,713,727,743 'user':339,345,606,609 'usercontrol':327 'usercontroller.create':279 'userrepositori':510,511 'userrepository.findactiveusers':535 'userservic':506,602 'util':452 'valid':78,221,395,421,444,446,482,633,677,689,768 'verif':662 'via':303,491 'webhook':407 'work':209,682 'workflow':735 'wrap':548 'written':93,697 'z.object':412 'z.string':414 'zero':285 'zod':220,400,447","prices":[{"id":"f3d1e0ba-d679-47fa-9ce4-dbcde422c20b","listingId":"0b107dd0-b649-48c7-9269-a92b55e95703","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"sickn33","category":"antigravity-awesome-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T20:33:35.908Z"}],"sources":[{"listingId":"0b107dd0-b649-48c7-9269-a92b55e95703","source":"github","sourceId":"sickn33/antigravity-awesome-skills/backend-dev-guidelines","sourceUrl":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/backend-dev-guidelines","isPrimary":false,"firstSeenAt":"2026-04-18T21:33:18.651Z","lastSeenAt":"2026-05-18T18:50:40.880Z"},{"listingId":"0b107dd0-b649-48c7-9269-a92b55e95703","source":"skills_sh","sourceId":"sickn33/antigravity-awesome-skills/backend-dev-guidelines","sourceUrl":"https://skills.sh/sickn33/antigravity-awesome-skills/backend-dev-guidelines","isPrimary":true,"firstSeenAt":"2026-04-18T20:33:35.908Z","lastSeenAt":"2026-05-07T22:40:37.511Z"}],"details":{"listingId":"0b107dd0-b649-48c7-9269-a92b55e95703","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"sickn33","slug":"backend-dev-guidelines","github":{"repo":"sickn33/antigravity-awesome-skills","stars":37911,"topics":["agent-skills","agentic-skills","ai-agent-skills","ai-agents","ai-coding","ai-workflows","antigravity","antigravity-skills","claude-code","claude-code-skills","codex-cli","codex-skills","cursor","cursor-skills","developer-tools","gemini-cli","gemini-skills","kiro","mcp","skill-library"],"license":"mit","html_url":"https://github.com/sickn33/antigravity-awesome-skills","pushed_at":"2026-05-18T08:24:49Z","description":"Installable GitHub library of 1,400+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and more. Includes installer CLI, bundles, workflows, and official/community skill collections.","skill_md_sha":"2bf0bfa2c918b53bb1226a8a2b27ddbbc9d65657","skill_md_path":"skills/backend-dev-guidelines/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/backend-dev-guidelines"},"layout":"multi","source":"github","category":"antigravity-awesome-skills","frontmatter":{"name":"backend-dev-guidelines","description":"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."},"skills_sh_url":"https://skills.sh/sickn33/antigravity-awesome-skills/backend-dev-guidelines"},"updatedAt":"2026-05-18T18:50:40.880Z"}}