backend-engineering

バックエンドエンジニアリングの方法論

バックエンドエンジニアリングとは、アプリケーションを支えるサーバーサイドシステム、つまり API、サービス、データアクセス、統合、およびアーキテクチャを実際に機能させる実行時の振る舞いを構築する技術です。この方法論は、software-architecture での目標設計後、qa-methodology での品質検証前の実装を対象とします。現行システムをまずリバースエンジニアリングする必要がある場合は、software-architecture-analysis を使用してください。周辺アーキテクチャや移行の判断を担うことなく、実行時の境界、トランザクションの振る舞い、メッセージ処理、共存の接点を実装可能な形にします。

バックエンドエンジニアの担当領域

担当すること	担当しないこと
API の実装 — REST／gRPC／GraphQL エンドポイント、リクエスト検証、レスポンス形式、エラー処理、ミドルウェアチェーン	API コントラクトは api-design-and-evolution の担当です。サービスの分割と目標境界は software-architecture の担当です
サービスロジック — ビジネスルール、ワークフローのオーケストレーション、状態管理、バックグラウンドジョブ処理	デプロイパイプラインとインフラストラクチャは platform-engineering の担当です
イベント駆動型の実装 — ドメインイベントの発行、アウトボックス／インボックスの連携、ハンドラーの冪等性、再実行と障害時の経路	イベントコントラクトの管理と配信セマンティクスは api-design-and-evolution の担当です
サービス内の移行の接点 — アダプター、選択可能な経路、オーソリティチェック、実装の引き継ぎ	システム間の移行ライフサイクルと切り替えの判断権限は migration-engineering の担当です
データベースのアクセスパターン — クエリ設計、接続管理、トランザクション境界、N+1 の検出、ページネーション	データプラットフォームとモデル戦略は data-architect の担当です。スキーマとパイプラインの運用は data-engineering の担当です
統合コード — サードパーティ API クライアント、Webhook ハンドラー、メッセージキューのコンシューマー／プロデューサー	コードレビューと品質ゲートは qa-methodology の担当です
サービスレベルでのオブザーバビリティ計装 — 構造化ログ、メトリクス、トレーシングフック	オブザーバビリティのインフラストラクチャと信頼性ポリシーは platform-engineering と site-reliability-engineering の担当です
サービスレベルのテスト — ビジネスロジックのユニットテスト、API コントラクトの統合テスト	テスト戦略と自動化は qa-methodology の担当です

参考ファイル

参考資料	読み込むタイミング
references/api-patterns.md	API エンドポイントを設計または実装するとき — リソースのモデリング、バージョニング、ページネーション、エラーレスポンス形式、リクエストの検証
references/service-patterns.md	サービスロジックを構成するとき — クリーン／ヘキサゴナル／レイヤードアーキテクチャ、依存性注入、ミドルウェアの合成、リクエストのライフサイクル、バックグラウンドジョブ
references/event-driven-service-implementation.md	イベント駆動型のアプリケーションフローを実装するとき — ドメインイベント、作業単位、トランザクショナルアウトボックス／インボックス、冪等なハンドラー、再試行／再生、可観測性、障害処理
references/migration-coexistence-patterns.md	旧実装と新実装を安全に共存させるとき — アダプター、ストラングラーハンドオフ、腐敗防止境界、デュアルパス、権限、削除条件
references/database-testing.md	データベースアクセスパターン（コネクションプーリング、クエリ最適化、N+1 の検出、ページネーション戦略、トランザクション境界、読み取り／書き込みの分割、レプリケーションラグ）およびサービスレベルのテスト（ビジネスロジックの単体テスト、テストコンテナ／WireMock を使った API コントラクトの統合テスト、Pact によるコントラクトテスト、テストフィクスチャ、CI との統合）
references/integration-patterns.md	外部システムと統合するとき — バックオフを伴う再試行、サーキットブレーカー、冪等性キー、Webhook の検証、メッセージキューのコンシューマー
references/error-handling.md	エラーを体系的に処理するとき — 分類（クライアント側とサーバー側）、構造化レスポンス、例外処理パターン、可観測性のための相関
references/source-index.md	このオリジナルの統合資料の出典と所有権に関する注記。対象範囲や出典の境界を確認するときに読み込みます

テンプレート

テンプレート	使用するタイミング
templates/service-design-record.md	サービスを設計または再構成するとき — 構造、API サーフェス、データアクセス、エラー処理、テスト計画を、レビュー可能な単一の記録にまとめます
templates/error-handling-taxonomy.md	サービスのエラーコントラクトを定義または監査するとき — 分類、レスポンス形式、再試行／冪等性ポリシー、エラーパスのテスト

スクリプト

スクリプト	使用するタイミング
scripts/n1-query-spotter.py	Python ソースをスキャンして、N+1 クエリの可能性があるパターン（ループ内のクエリに似た呼び出し）を検出します。CI で扱いやすい出力には --json を指定します。検出時は終了コード 1 を返します

関連するスキル

• programming-principles — DDD は、境界づけられたコンテキスト、集約、ドメイン言語、リポジトリ、ドメインモデリングの指針を担います。このスキルは、そのカタログを重複させるのではなく、実装上の接点でそれらの決定を適用します。
• api-design-and-evolution — イベント／メッセージの契約、配信セマンティクス、互換性、コンシューマー向け API の決定を担います。
• migration-engineering — システム間の移行分類、互換性維持期間、照合、切り替え、復旧、非推奨化、クリーンアップを担います。このスキルは、サービス内での共存に関する接点のみを実装します。
• software-architecture — サービスの分割と目標境界の戦略を担います。バックエンドエンジニアリングは、承認済みの境界を実装します。
• data-engineering — スキーマ移行とパイプライン運用を担います。アプリケーションコードでは、そうした運用で使用するリポジトリやトランザクションのインターフェースを公開する場合があります。
• secure-software-engineering — 脅威モデリング、認可、シークレット、信頼できない入力、セキュリティ受け入れ証跡を担います。
• release-engineering — 段階的なデリバリー、アーティファクトの昇格、リリースゲート、ロールバックの仕組みを担います。
• postgres — データベースの問題における PostgreSQL 側の診断を担います。設定の確認、インデックスやクエリプランの問題、バキューム／肥大化、バックアップ／PITR、レプリケーション、フェイルオーバーが対象です。アプリケーションレベルのデータアクセスパターンはここで扱い、エンジンレベルの運用はそちらに振り分けます。
• supabase — Supabase を使った構築を担います。マイグレーション、RLS、Auth、Storage、Edge Functions が対象です。エージェントの Supabase タスク遂行能力を評価するには、エージェント評価ハーネスのリファレンスを使用してください。

コア原則

インターフェースは契約です — API 境界はサービスレベルの契約です。すべてのエンドポイントシグネチャ、リクエストスキーマ、レスポンス形式、エラーコードは、コンシューマーへの約束です。破壊的変更はバージョン番号の更新ではなく、調整の問題です。

ビジネスロジックが中心です — ビジネスルールは、フレームワーク上の関心事、トランスポートプロトコル、インフラストラクチャの詳細から分離してください。適切に構成されたサービスは、HTTP ライブラリ、データベースドライバー、デプロイプラットフォームの変更にも耐えられます。

適切な場所でエラーを処理します — 意味のある処理に十分なコンテキストがある境界でエラーを捕捉してください。早すぎるとコンテキストが失われ、遅すぎると復旧できなくなります。

成功だけでなく、失敗を想定して設計します — 外部への呼び出しはすべて失敗する可能性があります。データベース接続はいつでも切断される可能性があります。メッセージは重複する可能性があります。冪等性、再試行、グレースフルデグラデーションは最適化ではなく、必須要件です。

適切なレベルでテストします — ビジネスロジックには単体テストを行います。API 契約には統合テストを行います。サービス境界には契約テストを行います。それぞれのレベルで、異なる種類の障害を検出します。

実装判断の進め方

1. 境界づけられたコンテキスト、集約／不変条件の境界、信頼できる情報源を明確にします。DDD の選択については、ここでカタログを作り直すのではなく、 programming-principles を参照してください。
2. トランスポート、ブローカー、データベース、クロック、ベンダーに関する関心事は、アプリケーションまたはドメインに面したコードが所有するポートの背後に置きます。インフラストラクチャにそれらのポートを実装させます。
3. 永続状態を変更してファクトを出力するコマンドでは、集約を読み込み、ドメインの振る舞いを呼び出し、状態とアウトボックスレコードを 1 つの作業単位でコミットします。ネットワーク呼び出しの間、トランザクションを開いたままにしないでください。
4. 受信メッセージでは、エッジでエンベロープを検証し、コンシューマーの権限範囲内で重複を排除し、ハンドラーを適用して、永続的な処理結果のコミット後にのみ確認応答を返します。リプレイとポイズンメッセージの判断には、イベント参照を読み込みます。
5. 旧経路と新経路が共存する場合は、各操作でどちらの経路が正となるのか、出力をどのように比較するのか、引き継ぎまたは削除を許可する根拠は何かを記録します。実装上の接続箇所については移行リファレンスを参照し、移行ライフサイクルの処理は外部に委ねます。
6. ドメイン／アプリケーションの振る舞いに対するユニットテストと、トランザクション、アウトボックス、インボックス、重複、再試行、リプレイ、復旧の振る舞いに対する境界統合テストを追加します。

完了基準

実装に明確な依存関係の方向、トランザクションと権限の境界、分類された失敗／再試行の振る舞い、メッセージ処理または共存経路の可観測性、重複および失敗ケースに焦点を当てたテストがあり、スコープ外の各判断について担当する隣接領域へのリンクが明確になっていれば、このスキルは完了です。