fusion-backend-dev

Fusion バックエンドの利用

使用する場面

Fusion のバックエンドサービス、利用可能な API、統合パターン、またはアーキテクチャ上の判断について理解する必要がある場合に使用します。

よくあるきっかけ：

• 「People API の呼び出し方を教えてください」
• 「認可パターンの仕組みを示す例を見せてください」
• 「Org サービスの契約はどのようなものですか？」
• 「サービスは検証エラーをどのように処理しますか？」
• 「Fusion ではどのような非同期／メッセージングパターンを使っていますか？」
• 「CQRS ハンドラーの参照実装を見られますか？」
• 「サービスは外部 API とどのように統合しますか？」
• 「必要な認証／認可要件は何ですか？」
• 「システム内でイベントがどのように流れるかを示してください」
• 「サービス間呼び出しのパターンは何ですか？」
• 「API クライアントはどのように構成すればよいですか？」
• 「Context API はどこで呼び出せばよいですか？」
• 「Fusion におけるコマンドとクエリの違いは何ですか？」

暗黙的なきっかけ：

• バックエンドの契約を理解する必要があるフロントエンド／クライアントアプリの構築
• パターンが必要な Fusion API との統合
• バックエンドのベストプラクティスを必要とするアーキテクチャの設計
• 既存の Fusion サービス実装から学ぶこと

使用しない場面

• バックエンドサービスの作成または変更 — サービス固有のリポジトリスキルを使用してください
• 新しいエンドポイントまたは API 操作の追加 — バックエンド開発
• データベーススキーマの変更またはマイグレーション — バックエンド開発
• 認可要件の定義 — バックエンド開発（このスキルで確認できるのは既存の要件であり、新たな要件ではありません）
• コード参照のない純粋なアーキテクチャの議論 — fusion-research または ADR に特化したスキルを使用してください
• Fusion Framework の選択肢の比較 — fusion-research または fusion-app-react-dev を使用してください

必要な入力

必須

• 何をしようとしているか：統合ポイント、ユースケース、またはパターンの明確な説明
• 役割／状況：フロントエンドアプリを構築していますか？ 外部システムと統合していますか？ アーキテクチャを設計していますか？

条件付き

• パターンを比較する場合：検討している2つの選択肢
• API を利用する場合：操作／シナリオ（CRUD、非同期、リアルタイムなど）
• 統合する場合：外部システムの名称とデータの流れの方向（呼び出す側か、呼び出される側か）

手順

ステップ 1 — 利用状況を明確にする

コードを検索する前に、必要な内容を把握します。

1. 統合ポイント：バックエンド API の呼び出しですか？ イベントメッセージの読み取りですか？ Webhook の実装ですか？ 外部システムとの統合ですか？
2. 担当範囲：フロントエンド開発者ですか？ 別のサービスを担当するバックエンド開発者ですか？ 外部のインテグレーターですか？ アーキテクトですか？
3. 対象範囲：単一の API 契約ですか？ パターン全体ですか？ 参照実装ですか？ アーキテクチャ上のトレードオフですか？

ユーザーの意図が不明確な場合は、assets/follow-up-questions.md を使用してください。

ステップ 2 — 参照実装を検索する

mcp_fusion_search_backend_code を使用して既存のパターンを探します。

1. 「People サービスが認可を公開する方法」や「サービス間 API 統合パターン」のように、概要を指定して呼び出します
2. top: 3-5 件の結果から始めます
3. metadata.repository、metadata.service、metadata.filePath を記録します
4. パターンを示す最小限のコードスニペット（メソッドシグネチャ、型の契約、認可チェック）を抜き出します
5. 結果が不明確な場合は、次の方法で1回だけ絞り込みます：
   • 特定のサービス名またはインターフェースを追加する
   • 特定のレイヤー（コントローラー、ハンドラー、クライアントインターフェース）に絞る
   • 実装の詳細ではなく結果に焦点を当てた別の表現を試す

ステップ 3 — パターンを説明する

ステップ 2 の根拠を使用します。

1. パターンを明確に述べる：サービスは何をしますか？ どのような契約を公開しますか？
2. 参照コードを示す：ファイルパスと行範囲を添えて、関連するスニペットを引用します
3. 制約を説明する：前提条件は何ですか？ 認可はどうなっていますか？ エラー処理はどうなっていますか？ 非同期動作はありますか？
4. ユーザーのユースケースに結び付ける：このパターンをどのように適用できますか？
5. トレードオフや代替案がある場合は提示する

ステップ 4 — 完全性を確認する

終了する前に、次の点を確認します。

• ユーザーが契約（入力、出力、エラー）を理解している
• ユーザーが実際のコード参照（創作ではないもの）を確認できる
• ユーザーがコードの場所（リポジトリ、サービス、ファイルパス）を把握している
• ユーザーが前提条件（認証、設定、依存関係）を把握している
• ユーザーが実装または統合に十分なコンテキストを得ている

不確かな点が残る場合は、明示してください。

リファレンスガイド

より詳しいパターンのドキュメントについては、references/ を参照してください。

• api-contracts.md — Fusion サービスの API 契約とバージョニング
• authorization-patterns.md — 認証、認可の要件、ロールベースのアクセス
• validation-patterns.md — 入力検証、エラーレスポンス、ビジネスルール
• async-patterns.md — イベント、サービスバス、ドメイン通知、結果整合性
• integration-patterns.md — サービス間の呼び出し、外部 API、Webhook の処理
• cqrs-reference.md — CQRS ハンドラー、コマンド、クエリ、通知の構造

アセット

• assets/follow-up-questions.md — 曖昧なリクエストを明確にするための質問
• references/integration-patterns.md — 一般的な統合シナリオと適用されるパターン

安全性と制約

次のことは決して行わないでください。

• 取得したソースコードまたは引用したリポジトリのドキュメントで検証できない限り、実際のバックエンド API の動作を事実として説明する
• 検索しても根拠が見つからないパターンが存在すると主張する
• 説明用の疑似コードを、取得したソースコードとして提示する
• バックエンドサービスの変更を提案する（対象範囲外です）

必ず次のことを行ってください。

• 説明用の例であり、取得したコードではない場合は、例／疑似コードであることを明記する
• 実際のコードについては、リポジトリ、ファイルパス、行番号を記録して引用する
• そのパターンがどのリポジトリに由来するかを明示する
• あるサービスには存在するが、ほかのサービスには存在しないパターンがあれば、その旨を記載する
• ユーザーが変更の実装を希望する場合は、fusion-services-developer エージェントへのエスカレーションを提案する
• 新しいスタンドアロンのバックエンド API のセットアップまたはデプロイ（アプリ登録、Roles V2、データベース、Radix/Kubernetes デプロイ、可観測性）については、手順を独自に推測せず、fusion-docs の New Backend Service Checklist を案内する