サービス連携

.factory/skills/service-integration/
├── SKILL.md
├── schemas/ (任意)
├── patterns.md (任意)
└── observability-checklist.md (任意)

---
name: service-integration
description: 所有境界、信頼性標準、オブザーバビリティ要件を保ちながら、共有モノレポ内の既存サービスを拡張または連携します。明確なドメイン境界を持つサービスでバックエンドAPI、ジョブ、イベントの追加または変更が必要な場合に使用します。
---
# スキル: 複雑なコードベースでのサービス連携

## 目的

所有境界、信頼性標準、オブザーバビリティ要件を保ちながら、メインのバックエンドコードベース内の既存サービスを拡張または連携します。

## このスキルを使うタイミング

- 変更にバックエンドAPI、ジョブ、イベントの追加または変更が必要。
- サービスが、明確な所有権とドメイン境界を持つ**共有モノレポ**内にある。
- 作業には他チームとの調整が必要な場合があるが、主な実装は自チームのサービス内で行う。

## 入力

- **ビジネス要件**: ユーザーまたはシステム動作変更の短い説明。
- **主要サービス**: 関連するサービスとドメインの名前/パス。
- **既存契約**: 関連するAPIスキーマ、イベント、メッセージ形式。
- **非機能要件**: レイテンシ、エラーバジェット、データ保持、スループットの期待値。
- **変更管理**: ロールアウト戦略、機能フラグ、移行計画。

## 対象外

- 新しいインフラやデータストアが必要なグリーンフィールドシステム。
- クロスリージョンまたはクロスクラウドのレプリケーション設計。
- 事前承認なしに確立された所有境界と衝突する変更。

## 規約

- `AGENTS.md`と内部アーキテクチャドキュメントに記載された**ドメイン境界**とモジュールレイアウトに従う。
- 既存の**設定、ロギング、メトリクス、トレーシング**パターンを使用する。
- 確立された**エラーハンドリング**と**リトライ/バックオフ**ユーティリティを再利用する。

## 必須の動作

1. 既存のフレームワークパターンを使って、新しいAPI、ジョブ、イベントを導入する。
2. 可能な限り後方互換性を維持する。破壊的変更が必要な場合は移行手順を文書化する。
3. すべての新しい動作をログ、メトリクス、トレースで観測可能にする。
4. 既存のセキュリティとプライバシー要件（認証/認可、PII処理、データレジデンシー）を尊重する。

## 必須の成果物

- 関連するサービスとドメインモジュールでのコード変更。
- 中核ロジックと境界条件の**単体テスト**。
- ハーネスが存在する場合、新規または変更されたインターフェースの**統合テストまたは契約テスト**。
- チームのプロセスで必要な場合のみ、**ランブックまたは設計ドキュメント**を更新する（ここに重複させず、PR説明からリンクする）。

## 実装チェックリスト

1. 所有者を特定し、どのサービスを変更すべきか確認する。
2. サービスと依存関係をまたぐデータフローと制御フローを整理する。
3. 連携面（API、イベント、ジョブ）を設計し、既存規約に照らして検証する。
4. 関連ファイルとモジュールを近接させたまま変更を実装する。
5. 適切なレイヤー（単体、統合、契約）でテストを追加または更新する。
6. ログ/メトリクス/トレースにより、本番で新しい動作をデバッグできるようにする。
7. 必要に応じて、安全なロールアウトのために機能フラグまたは設定を接続する。

## 検証

サービスレベルの検証コマンドを実行します。例:

- `pnpm test --filter <service>`、またはサービスディレクトリで`pytest`
- `pnpm lint`、または使用言語に相当するリンター
- `AGENTS.md`またはサービスドキュメントで参照されている既存の**契約テストまたは統合テストスイート**

以下を満たしたらスキルは完了です:

- 関連するすべてのテストとリンターが成功する。
- 新しい連携がローカルまたはステージング環境で正しく動作する。
- オブザーバビリティ信号（ログ、メトリクス、トレース）が、ノイズの多い回帰なしに期待される動作を示す。

## 安全性とエスカレーション

- 変更が**共有スキーマ、中核認証ロジック、請求、コンプライアンス上重要なデータ**に触れる場合は停止し、明示的な人間の承認と設計レビューを依頼する。
- 他チーム所有の依存関係に変更が必要な場合は、そのチケットを作成または更新し、PRで前提と契約期待値を明確に文書化する。