backend-dev-guidelines

バックエンド開発ガイドライン

目的

最新の Node.js／Express／TypeScript のパターンを使用するバックエンドサービス全体で、一貫性とベストプラクティスを確立します。

Node.js／Express／TypeScript と Prisma、Sentry を使用するプロジェクト向けに作成されています。異なるスタックを使用している場合は、アーキテクチャの原則を適宜取り入れてください。リポジトリのルートにある CLAUDE_INTEGRATION_GUIDE.md を参照してください。

このスキルを使用するタイミング

以下の作業を行うと自動的に有効になります。

• ルート、エンドポイント、API の作成または変更
• コントローラー、サービス、リポジトリの構築
• ミドルウェア（認証、検証、エラー処理）の実装
• Prisma を使用したデータベース操作
• Sentry によるエラー追跡
• Zod による入力検証
• 設定管理
• バックエンドのテストとリファクタリング

---

クイックスタート

バックエンド機能の新規作成チェックリスト

• ルート：シンプルに定義し、コントローラーに処理を委譲する
• コントローラー：BaseController を継承する
• サービス：DI を使用したビジネスロジック
• リポジトリ：データベースアクセス（複雑な場合）
• 検証：Zod スキーマ
• Sentry：エラー追跡
• テスト：単体テストと統合テスト
• 設定：unifiedConfig を使用する

マイクロサービスの新規作成チェックリスト

• ディレクトリ構成（architecture-overview.md を参照）
• Sentry 用の instrument.ts
• unifiedConfig の設定
• BaseController クラス
• ミドルウェアスタック
• エラーバウンダリー
• テストフレームワーク

---

アーキテクチャの概要

レイヤードアーキテクチャ

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

重要な原則： 各レイヤーが担う責務は 1 つだけです。

詳細については、architecture-overview.md を参照してください。

---

ディレクトリ構成

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

命名規則：

• コントローラー：PascalCase - UserController.ts
• サービス：camelCase - userService.ts
• ルート：camelCase + Routes - userRoutes.ts
• リポジトリ：PascalCase + Repository - UserRepository.ts

---

基本原則（7 つの重要なルール）

1. ルートはルーティングのみ、処理はコントローラーが担当する

// ❌ 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. すべてのコントローラーは 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. すべてのエラーを Sentry に送信する

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

4. unifiedConfig を使用し、process.env は絶対に使用しない

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

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

5. すべての入力を Zod で検証する

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

6. データアクセスにはリポジトリパターンを使用する

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

7. 包括的なテストを必須とする

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

---

よく使用するインポート

// 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';

---

クイックリファレンス

HTTP ステータスコード

コード	用途
200	成功
201	作成済み
400	不正なリクエスト
401	未認証
403	アクセス禁止
404	見つかりません
500	サーバーエラー

サービスのテンプレート

ブログ API（✅ 成熟）- REST API のテンプレートとして使用します
認証サービス（✅ 成熟）- 認証パターンのテンプレートとして使用します

---

避けるべきアンチパターン

❌ ルートにビジネスロジックを記述する
❌ process.env を直接使用する
❌ エラー処理が欠けている
❌ 入力を検証しない
❌ どこでも Prisma を直接使用する
❌ Sentry の代わりに console.log を使用する

---

ナビゲーションガイド

目的	参照先
アーキテクチャを理解する	architecture-overview.md
ルート／コントローラーを作成する	routing-and-controllers.md
ビジネスロジックを整理する	services-and-repositories.md
入力を検証する	validation-patterns.md
エラー追跡を追加する	sentry-and-monitoring.md
ミドルウェアを作成する	middleware-guide.md
データベースにアクセスする	database-patterns.md
設定を管理する	configuration.md
非同期処理／エラーを処理する	async-and-errors.md
テストを作成する	testing-guide.md
例を確認する	complete-examples.md

---

リソースファイル

architecture-overview.md

レイヤードアーキテクチャ、リクエストのライフサイクル、関心の分離

routing-and-controllers.md

ルート定義、BaseController、エラー処理、例

services-and-repositories.md

サービスのパターン、DI、リポジトリパターン、キャッシュ

validation-patterns.md

Zod スキーマ、バリデーション、DTO パターン

sentry-and-monitoring.md

Sentry の初期化、エラーキャプチャ、パフォーマンス監視

middleware-guide.md

認証、監査、エラーバウンダリ、AsyncLocalStorage

database-patterns.md

PrismaService、リポジトリ、トランザクション、最適化

configuration.md

UnifiedConfig、環境設定、シークレット

async-and-errors.md

非同期パターン、カスタムエラー、asyncErrorWrapper

testing-guide.md

単体テスト／統合テスト、モック、カバレッジ

complete-examples.md

完全な例、リファクタリングガイド

---

関連スキル

• database-verification - カラム名とスキーマの整合性を検証します
• error-tracking - Sentry 連携パターン
• skill-developer - スキルを作成・管理するためのメタスキル

---

スキルのステータス: COMPLETE ✅ 行数: < 500 ✅ プログレッシブディスクロージャー: 11 個のリソースファイル ✅