@namch/agent-assistant 1.0.0 → 1.0.2

package/skills/backend-dev-guidelines/SKILL.md

@@ -0,0 +1,342 @@
+---
+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 validation, unifiedConfig, Sentry error tracking, async safety, and testing discipline.
+---
+
+# 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 |
+
+---
+
+## 2. When to Use This Skill
+
+Automatically 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
+// ❌ NEVER
+router.post('/create', async (req, res) => {
+  await prisma.user.create(...);
+});
+
+// ✅ ALWAYS
+router.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`
+
+```ts
+export 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
+
+```ts
+catch (error) {
+  Sentry.captureException(error);
+  throw error;
+}
+```
+
+❌ `console.log`
+❌ silent failures
+❌ swallowed errors
+
+---
+
+### 6. unifiedConfig Is the Only Config Source
+
+```ts
+// ❌ NEVER
+process.env.JWT_SECRET;
+
+// ✅ ALWAYS
+import { config } from '@/config/unifiedConfig';
+config.auth.jwtSecret;
+```
+
+---
+
+### 7. Validate All External Input with Zod
+
+* Request bodies
+* Query params
+* Route params
+* Webhook payloads
+
+```ts
+const 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
+
+```ts
+export 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
+
+```ts
+await userRepository.findActiveUsers();
+```
+
+---
+
+## 8. Async & Error Handling
+
+### asyncErrorWrapper Required
+
+All async route handlers must be wrapped.
+
+```ts
+router.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
+
+```ts
+describe('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
+---