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

(Node.js · Express · TypeScript · マイクロサービス)

あなたはシニアバックエンドエンジニアとして、厳密なアーキテクチャおよび信頼性制約下でプロダクショングレードのサービスを運用します。

目標は、以下を使用して予測可能で、観測可能で、保守性の高いバックエンドシステムを構築することです：

• レイヤード・アーキテクチャ
• 明示的なエラーバウンダリ
• 強い型付けと検証
• 一元化された設定
• ファーストクラスの観測可能性

このスキルは、バックエンドコードがどのように書かれるべきかを定義しています。単なる提案ではなく、必須事項です。

---

1. バックエンド実現可能性・リスク指標（BFRI）

バックエンド機能を実装または変更する前に、実現可能性を評価します。

BFRI の構成要素（1～5）

構成要素	質問
アーキテクチャの適合性	これは routes → controllers → services → repositories に従っていますか？
ビジネスロジックの複雑性	ドメインロジックはどの程度複雑ですか？
データリスク	これは重要なデータパスまたはトランザクションに影響を与えますか？
運用リスク	これは認証、請求、メッセージング、またはインフラに影響を与えますか？
テスト可能性	これは確実にユニット + インテグレーション テストが可能ですか？

スコア計算式

BFRI = (アーキテクチャの適合性 + テスト可能性) − (複雑性 + データリスク + 運用リスク)

範囲： -10 → +10

解釈

BFRI	意味	アクション
6～10	安全	進行
3～5	中程度	テスト + モニタリングを追加
0～2	リスク	リファクタリングまたは隔離
< 0	危険	コード前に設計を見直す

---

使用タイミング

以下の作業時に自動的に適用されます：

• Routes、controllers、services、repositories
• Express ミドルウェア
• Prisma データベースアクセス
• Zod 検証
• Sentry エラートラッキング
• 設定管理
• バックエンドリファクタリングまたはマイグレーション

---

2. コア・アーキテクチャ・ドクトリン（非交渉的）

1. レイヤード・アーキテクチャは必須

Routes → Controllers → Services → Repositories → Database

• レイヤースキップなし
• レイヤー間の漏洩なし
• 各レイヤーは単一の責任を持つ

---

2. Routes はルーティングのみ行う

// ❌ 絶対に禁止
router.post('/create', async (req, res) => {
  await prisma.user.create(...);
});

// ✅ 常にこうする
router.post('/create', (req, res) =>
  userController.create(req, res)
);

Routes にはビジネスロジックはゼロである必要があります。

---

3. Controllers は調整、Services は決定

• Controllers：

  • リクエストをパース
  • サービスを呼び出す
  • レスポンスフォーマットを処理
  • BaseController 経由でエラーを処理

• Services：

  • ビジネスルールを含む
  • フレームワークに依存しない
  • DI を使用
  • ユニットテスト可能

---

4. すべての Controllers は BaseController を拡張

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');
    }
  }
}

BaseController ヘルパー以外での生の res.json 呼び出しはなし。

---

5. すべてのエラーは Sentry に送信

catch (error) {
  Sentry.captureException(error);
  throw error;
}

❌ console.log ❌ サイレント失敗 ❌ 呑み込まれたエラー

---

6. unifiedConfig が唯一の設定ソース

// ❌ 絶対に禁止
process.env.JWT_SECRET;

// ✅ 常にこうする
import { config } from '@/config/unifiedConfig';
config.auth.jwtSecret;

---

7. Zod ですべての外部入力を検証

• リクエストボディ
• クエリパラメータ
• ルートパラメータ
• Webhook ペイロード

const schema = z.object({
  email: z.string().email(),
});

const input = schema.parse(req.body);

検証なし = バグ。

---

3. ディレクトリ構造（標準）

src/
├── config/              # unifiedConfig
├── controllers/         # BaseController + controllers
├── services/            # ビジネスロジック
├── repositories/        # Prisma アクセス
├── routes/              # Express routes
├── middleware/          # 認証、検証、エラー
├── validators/          # Zod スキーマ
├── types/               # 共有型
├── utils/               # ヘルパー
├── tests/               # ユニット + インテグレーション テスト
├── instrument.ts        # Sentry（最初のインポート）
├── app.ts               # Express アプリ
└── server.ts            # HTTP サーバー

---

4. 命名規則（厳密）

レイヤー	規則
Controller	PascalCaseController.ts
Service	camelCaseService.ts
Repository	PascalCaseRepository.ts
Routes	camelCaseRoutes.ts
Validators	camelCase.schema.ts

---

5. 依存性注入ルール

• Services はコンストラクタ経由で依存関係を受け取る
• Controllers 内での repositories の直接インポートなし
• モッキングとテストが可能になる

export class UserService {
  constructor(
    private readonly userRepository: UserRepository
  ) {}
}

---

6. Prisma & Repository ルール

• Prisma クライアントは controllers で直接使用しない

• Repositories：

  • クエリをカプセル化
  • トランザクションを処理
  • インテント・ベースのメソッドを公開

await userRepository.findActiveUsers();

---

7. 非同期 & エラーハンドリング

asyncErrorWrapper が必須

すべての非同期ルートハンドラはラップが必須。

router.get(
  '/users',
  asyncErrorWrapper((req, res) =>
    controller.list(req, res)
  )
);

ハンドルされていない Promise rejection なし。

---

8. 観測可能性 & モニタリング

必須

• Sentry エラートラッキング
• Sentry パフォーマンストレーシング
• 構造化ログ（該当する場合）

すべての重要なパスは観測可能である必要があります。

---

9. テスト規律

必須テスト

• ユニットテスト for services
• インテグレーションテスト for routes
• Repository テスト for 複雑なクエリ

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

テストなし → マージなし。

---

10. アンチパターン（即座に却下）

❌ Routes でのビジネスロジック ❌ Service レイヤーをスキップ ❌ Controllers での直接 Prisma ❌ 検証の欠落 ❌ process.env 使用 ❌ console.log ではなく Sentry ❌ テストされていないビジネスロジック

---

11. 他のスキルとの統合

• frontend-dev-guidelines → API コントラクト整合性
• error-tracking → Sentry 標準
• database-verification → スキーマ正確性
• analytics-tracking → イベントパイプライン
• skill-developer → スキルガバナンス

---

12. オペレーター検証チェックリスト

バックエンド作業を最終化する前に：

• BFRI ≥ 3
• レイヤード・アーキテクチャが尊重されている
• 入力が検証されている
• エラーが Sentry にキャプチャされている
• unifiedConfig が使用されている
• テストが書かれている
• アンチパターンが存在しない

---

13. スキルステータス

ステータス： Stable · Enforceable · Production-grade 対象用途： 実トラフィックと実リスクを持つ長期的な Node.js マイクロサービス

使用タイミング

このスキルは、概要で説明されているワークフローまたはアクションを実行する際に適用可能です。

制限事項

• このスキルは、上記で説明されているスコープと明確に一致するタスクの場合のみ使用します。
• 出力を環境固有の検証、テスト、または専門家レビューの代替として扱わないでください。
• 必須入力、権限、安全性の境界、または成功基準が不明な場合は、停止して明確化を求めます。