backend-dev-guidelines

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

web/、worker/、packages/shared/ にまたがるバックエンドや API の作業では、このスキルを使用してください。

適用する場面

• tRPC ルーターやプロシージャを作成または変更する
• パブリック API エンドポイントを作成または変更する
• キュープロセッサー、プロデューサー、またはキューを使用するワークフローを作成または変更する
• バックエンドのサービスやリポジトリを構築またはリファクタリングする
• バックエンドの認証、ミドルウェア、検証、または可観測性に取り組む
• Prisma または ClickHouse のアクセスパターンを更新する
• 共有バックエンドコードにフィールド、オプション、フラグ、または列挙型のメンバーを追加する
• バックエンドのテストを追加または修正する

このスキルの読み方

• 複数のバックエンド領域にまたがるタスク、または全体を通した参照マップが必要な場合は、この SKILL.md を使用してください。
• 対象範囲がより狭い場合は、作業内容に該当する参照ファイルだけを読んでください。
• タスクでユーザー指定の URL、新しい外部 HTTP リクエスト、新しい統合を導入する場合、またはシークレット、RBAC、リダイレクト処理に触れる場合は、変更の設計や実装の前に、共通の security-review スキルも読み込んでください。

新しい概念を追加する前に

共有スキーマやペイロードへのフィールド追加、共有シグネチャへのオプションやフラグの追加、列挙型のメンバー追加、環境変数の切り替え、単一の呼び出し元にのみ存在する分岐の追加を行う前、または変更が不要だと判断する前に、references/new-concepts.md を読んでください。

クイックスタートチェックリスト

UI：新しい tRPC 機能

• features/[feature]/server/*Router.ts にルーターを定義します。
• 適切な保護付きまたはパブリックプロシージャを使用します。
• JWT 対応ミドルウェアで認証します。
• プロジェクト／リソースへのアクセス権と利用資格を確認します。
• Zod v4 で入力を検証します。
• ビジネスロジックはサービスファイルに記述します。
• 関連する場合は、エラー処理に traceException を使用します。
• __tests__/ にユニットテストまたは統合テストを追加します。
• env.mjs 経由で設定にアクセスします。

既存のエンドポイント：フィールドまたはフィルターの追加

コーディングを始める前に、変更が新しいエンドポイント、既存のエンドポイントへのフィールド／フィルターの追加、または意味上の置き換え／破壊的変更のいずれに当たるかを分類します。

フィールド／フィルターを追加する場合：

• 正規の述語を再利用します。フィールドグループの選択をすでにサポートしているエンドポイントでは、既存のフィールドグループ／プロジェクション経路を再利用します。
• エンドポイントの既存のレスポンス契約を維持します。フィールドグループを扱うエンドポイントでは通常の省略可能な部分行スキーマとコンバーター経路を使用し、通常のエンドポイントでは厳密なレスポンススキーマとコンバーター経路を維持します。
• 互換性のために必要な場合を除き、API バージョン固有のフィールドセット、キャスト、または「必ず選択されている」ことを確認するランタイムアサーションを作成しないでください。
• 既存のフィルター例を置き換えるのではなく、例と契約を拡張します。
• 変更したファイルごとではなく、固有の境界ごとにテストを 1 つ作成します。

SDK：新しいパブリック API エンドポイント

• pages/api/public/ にルートを作成します。
• withMiddlewares と createAuthedProjectAPIRoute でラップします。
• features/public-api/types/ に型を定義します。
• Basic 認証で認証します。
• Zod スキーマでクエリ、ボディ、レスポンスを検証します。
• パスとスキーマに API バージョニングを含めます。
• Fern API 定義を TypeScript の型と一致するよう更新します。
• __tests__/async/ にエンドツーエンドテストを追加します。

Worker：新しいキュープロセッサー

• worker/src/queues/ にプロセッサーを作成します。
• packages/shared/src/server/queues にキューの型を定義します。
• ビジネスロジックは features/ または worker/src/features/ に配置します。
• 失敗したジョブと、エラーを記録したうえで正常に完了すべきジョブを区別します。
• app.ts の WorkerManager にキューを登録します。
• Worker の vitest テストを追加します。

基本原則

• tRPC のプロシージャ、公開 API ルート、キュープロセッサーは、ビジネスロジックをサービスに委譲します。
• 設定には env.mjs を通じてアクセスしてください。環境設定の外で process.env を直接読み取らないでください。
• 外部からのすべての入力を Zod v4 で検証してください。
• 単純な CRUD には Prisma を直接使用し、複雑なクエリアクセスにはリポジトリを使用してください。
• 新しい要件は、既存の共有コードで使われている語彙で表現してください。共有抽象化に概念を追加するのは、最初の選択肢ではなく最後の手段です。
• バックエンドの可観測性には OpenTelemetry と DataDog を使用してください。
• プロジェクトスコープのデータベースクエリには、必ず projectId でフィルターをかけてください。
• Fern API の定義を、公開 TypeScript API コントラクトと同期させてください。
• バックエンドのテストは、互いに独立し、並列実行に安全な状態を保ってください。

実例

• プロジェクト認証と Zod 入力を使用する tRPC ルーター： web/src/features/events/server/eventsRouter.ts。
• ミドルウェアと型付きリクエスト／レスポンススキーマを使用する公開 API ルート： web/src/pages/api/public/datasets/index.ts。
• 型付きジョブ、ロギング、リトライ動作を備えたワーカーキュープロセッサー： worker/src/queues/evalQueue.ts。
• Prisma と ClickHouse のテナントフィルター： references/database-patterns.md。

命名規則

• tRPC ルーター：camelCaseRouter.ts。例：datasetRouter.ts。
• サービス：機能のサーバーディレクトリにある service.ts。
• キュープロセッサー：camelCaseQueue.ts。例：evalQueue.ts。
• 公開 API ルート：kebab-case のファイル名。例：dataset-items.ts。

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

• ルートやプロシージャにビジネスロジックを記述する。
• env.mjs／env.ts ではなく、process.env を直接使用する。
• エラーハンドリングがない。
• 入力検証がない。
• テナントスコープのクエリに projectId フィルターがない。
• logger／traceException ではなく console.log を使用する。

リファレンスマップ

トピック	次の場合に読む	ファイル
アーキテクチャとパッケージ境界	web／worker／shared の分割、リクエストフロー、またはキューのライフサイクルを確認する場合	references/architecture-overview.md
ルーティングとコントローラー	tRPC プロシージャ、公開 API ルート、またはキューのエントリーポイントを作成する場合	references/routing-and-controllers.md
ミドルウェアと認証	リクエスト認証、権限、またはミドルウェアの構成を変更する場合	references/middleware-guide.md
サービスとリポジトリ	ビジネスロジック、リポジトリコード、または DI パターンを配置する場合	references/services-and-repositories.md
データベースアクセス	Prisma、ClickHouse、テナントフィルター、またはクエリパターンを扱う場合	references/database-patterns.md
共有コードへの新しい概念	共有抽象化にフィールド、オプション、フラグ、または enum メンバーを追加する場合	references/new-concepts.md
設定	環境変数、起動時設定、または実行時トグルを追加する場合	references/configuration.md
テスト	バックエンドテストを追加または更新する場合	references/testing-guide.md