service-catalog-entry

サービスカタログエントリーのスキル

マイクロサービスまたは社内プラットフォームサービスの完全なサービスカタログエントリーを作成します。サービスの内容、依存方法、信頼性の特性、問題発生時の問い合わせ先について、社内のあらゆるエンジニアが理解するために必要な情報を提供します。適切に作成されたカタログエントリーは、共有サービスに依存するチームの妨げとなる「誰が所有しているのか」「安全に使えるのか」といった疑問を解消します。

必要な入力

まだ提供されていない場合は、次の情報を尋ねてください。

• サービス名 — コード、監視、デプロイで使用される正式な識別子
• チームとオーナー — チーム名、テックリード名、オンコール連絡先
• アーキテクチャの概要 — サービスの機能、呼び出し元、呼び出し先
• SLA 要件 — 可用性目標、レイテンシ SLO、サポートティア、メンテナンス時間帯
• 主要 API — 他チームが使用する重要なエンドポイント（メソッド、パス、簡単な説明）
• 取り扱うデータ — サービスが保存または処理するデータ、機密性の分類、保持期間

出力形式

---

サービスカタログ：[Service Name]

[このサービスが利用者に提供する機能を、平易な言葉で一文で説明]

例：「Payments Service は、Acme のすべての製品で請求、返金、サブスクリプションの請求イベントを処理します。」

---

識別情報

項目	値
サービス名	[service-name]
正式なリポジトリ	[https://github.com/[org]/[repo]]
オーナーチーム	[チーム名]
テックリード	[名前] ([Slack: @handle])
オンコールローテーション	[PagerDuty サービスリンク]
Slack チャンネル	#[team-channel]
サポートティア	[ティア 1 — 24 時間 365 日 / ティア 2 — 営業時間内 / ティア 3 — ベストエフォート]
ステータス	[稼働中 / 非推奨 / 終了日：YYYY-MM-DD]
言語 / ランタイム	[例：Go 1.22 / Python 3.12 / Node 20]
デプロイプラットフォーム	[Kubernetes / ECS / Lambda / など]
環境	[本番環境：URL]

---

サービスの機能

[専門用語や略語は説明なしに使わず、平易な言葉で 2〜3 段落で説明します。]

[第 1 段落：このサービスが解決するビジネス上の課題。このサービスが存在しない場合、何が壊れる、または欠けるのかを説明します。]

[第 2 段落：大まかな仕組み — 主な処理モデル（例：リクエスト／レスポンス API、イベント駆動型コンシューマー、バッチプロセッサー）、起動条件、生成するものを説明します。]

[第 3 段落：このサービスが担当しないこと — 明確な責任範囲を示します。これにより、他チームが対象範囲について誤った前提を持つのを防ぎます。]

---

アーキテクチャのコンテキスト

システム図

[Upstream callers]          [This Service]             [Downstream dependencies]
                                                        
  [Web App]  ──────────→                          ──→  [Primary Database — PostgreSQL]
  [Mobile API]  ────────→  [Service Name]         ──→  [Cache — Redis]
  [Partner API] ────────→  (Port 8080/gRPC)       ──→  [Message Queue — Kafka/SQS]
                                                   ──→  [External Service / API]
                           ↓ emits events to
                        [Event Bus / SNS]
                           ↓ consumed by
                  [Downstream Service A]
                  [Downstream Service B]

このサービスに依存するサービス

呼び出し元	利用方法	連絡先
[サービス / チーム A]	[例：「支払いを開始するために POST /charges を呼び出す」]	[Slack: #team-a]
[サービス / チーム B]	[例：「Kafka トピック経由で payment.completed イベントを購読する」]	[Slack: #team-b]
[サービス / チーム C]	[例：「請求状況を確認するために GET /subscriptions を呼び出す」]	[Slack: #team-c]

このサービスが依存するもの

依存先	種類	重要度	依存先のオンコール連絡先
[PostgreSQL インスタンス]	データベース	重大 — 利用できない場合、すべての書き込みが失敗します	[DBA チーム: #db-oncall]
[Redis クラスター]	キャッシュ	高 — 利用できない場合、レイテンシが悪化します	[Infra チーム: #infra-oncall]
[Kafka クラスター]	メッセージキュー	高 — 非同期イベントがキューに滞留します	[Infra チーム: #infra-oncall]
[Stripe API]	外部 API	重大 — 決済処理が失敗します	[ベンダーのステータス: status.stripe.com]
[Auth Service]	内部サービス	重大 — すべての認証が失敗します	[Auth チーム: #auth-oncall]

---

サービスレベル契約

可用性とレイテンシ

SLO	目標	測定期間	エラーバジェット
可用性	[99.9%]	直近30日間	[43 min/month]
p50 レイテンシ（主要エンドポイント）	< [50] ms	直近24時間	—
p99 レイテンシ（主要エンドポイント）	< [500] ms	直近24時間	—
p99.9 レイテンシ（主要エンドポイント）	< [2000] ms	直近24時間	—
エラー率	< [0.1]%	直近1時間	—

SLO ダッシュボード： [Link to monitoring dashboard] 現在のエラーバジェット残量： [Link to SLO dashboard or inline value]

サポートティア

ティア	対象範囲	応答時間	解決時間
P1 — サービス停止	認証済みのすべてのリクエストが失敗	15 分	1 時間
P2 — 大幅な性能低下	エラー率 >1% または p99 >SLO の 2 倍	30 分	4 時間
P3 — 軽微な問題	重要度の低いエンドポイントの性能低下	翌営業日	3 営業日
機能リクエスト／バグ	標準のチケットプロセスで対応	[Ticket SLA]	ロードマップに準拠

インシデントの報告先： [PagerDuty service link] からページを送信するか、#incidents に投稿してください。 機能リクエストまたはバグの報告先： [JIRA project / GitHub repo Issues] でチケットを作成してください。

メンテナンス時間

• 計画停止時間： [例：「日曜日 02:00–04:00 UTC — 48h 前に #[team-channel] で事前告知」]
• デプロイ時間： [例：「平日 10:00–16:00 UTC — 金曜日および祝日の前日はデプロイなし」]
• 破壊的変更の通知： [例：「API の破壊的変更は最低 30 日前に通知 — 下記のバージョニングポリシーを参照」]

---

API コントラクト

認証

すべての API 呼び出しで以下が必要です：[例：「Authorization ヘッダーを介した Bearer トークン。トークンは Auth Service（/api/v1/token）によって発行されます」]

Authorization: Bearer [jwt-token]
Content-Type: application/json

ベース URL

環境	ベース URL
本番環境	https://[service-name].internal.[company].com
ステージング	https://[service-name].staging.[company].com
ローカル開発	http://localhost:[port]

主要エンドポイント

メソッド	パス	説明	認証必須	レート制限
GET	/health	稼働状態と準備状態の確認	いいえ	なし
GET	/api/v1/[resource]	[説明 — 例：「認証済みユーザーのリソース一覧を取得」]	はい	[100 req/min]
GET	/api/v1/[resource]/:id	[説明 — 例：「ID で単一のリソースを取得」]	はい	[500 req/min]
POST	/api/v1/[resource]	[説明 — 例：「新しいリソースを作成」]	はい	[50 req/min]
PUT	/api/v1/[resource]/:id	[説明 — 例：「既存のリソースを更新」]	はい	[50 req/min]
DELETE	/api/v1/[resource]/:id	[説明]	はい	[20 req/min]

API ドキュメント全文： [OpenAPI/Swagger spec URL] | [Postman collection URL]

バージョニングポリシー

• API のバージョンは URL パスに含まれます（/api/v1/、/api/v2/）
• マイナーな追加（新しい任意フィールド、新しいエンドポイント）は破壊的変更ではないため、バージョンを上げません
• 破壊的変更（フィールドの削除、型の変更、認証の変更）には新しいメジャーバージョンが必要です
• 廃止予定のバージョンは、後継バージョンが GA に達してから [90 days] の間サポートされます
• 廃止の通知は #[team-channel] に投稿し、登録済みの利用者にメールで送信します

エラーレスポンス形式

{
  "error": {
    "code": "[ERROR_CODE]",
    "message": "[Human-readable description]",
    "request_id": "[UUID — include in support tickets]",
    "details": {}
  }
}

一般的なエラーコード：

HTTP ステータス	エラーコード	意味
400	INVALID_REQUEST	リクエスト本文またはパラメーターが検証に失敗しました
401	UNAUTHENTICATED	認証トークンがないか、無効です
403	FORBIDDEN	トークンは有効ですが、このリソースへのアクセス権がありません
404	NOT_FOUND	リソースが存在しません
409	CONFLICT	リソースが重複しているか、状態が競合しています
422	UNPROCESSABLE_ENTITY	リクエストは有効ですが、ビジネスルールに違反しています
429	RATE_LIMITED	リクエストが多すぎます — 間隔を空けて再試行してください
500	INTERNAL_ERROR	予期しないサーバーエラーです — サポートチケットに request_id を記載してください
503	SERVICE_UNAVAILABLE	下流の依存先が利用できません — バックオフを伴って再試行してください

発行されるイベント（イベント駆動の場合）

イベント	トピック／キュー	スキーマ	発行されるタイミング
[resource].created	[kafka-topic / sns-arn]	[Schema URL]	[新しいリソースが作成されたとき]
[resource].updated	[kafka-topic / sns-arn]	[Schema URL]	[リソースが変更されたとき]
[resource].deleted	[kafka-topic / sns-arn]	[Schema URL]	[リソースが削除されたとき]

---

データ分類

データ要素	機密性	保存先	保存期間	保存時に暗号化
[ユーザーの個人識別情報 — 例：メールアドレス、氏名]	[個人識別情報／制限付き]	[PostgreSQL の users テーブル]	[アカウント削除まで]	はい
[金融データ — 例：カード番号の下4桁]	[PCI／厳重な制限付き]	[PostgreSQL の payment_methods テーブル]	[規制に基づき7年間]	はい — フィールド単位の暗号化
[運用ログ]	[内部]	[CloudWatch / Datadog]	[90日間]	はい（保存時。検索対象外）
[匿名化された分析データ]	[公開]	[データウェアハウス]	[無期限]	はい

データの保存場所： [例：「すべてのデータは us-east-1 に保存されます。EU の顧客データは GDPR の要件に従い eu-west-1 に保存されます。」] コンプライアンス対象範囲： [例：SOC 2 Type II / PCI DSS Level 2 / HIPAA / GDPR] データアクセス方針： [例：「本番データベースへのアクセスには[承認プロセス]が必要です。アクセスは記録され、四半期ごとにレビューされます。」]

---

運用手順書

手順書	場所	使用する状況
オンコール手順書	[Wiki / GitHub link]	PagerDuty アラートへの対応
デプロイ手順書	[Wiki / GitHub link]	本番環境への新バージョンのデプロイ
データベース移行手順書	[Wiki / GitHub link]	スキーマ移行の実行
ロールバック手順書	[Wiki / GitHub link]	問題のあるデプロイのロールバック
インシデント対応手順書	[Wiki / GitHub link]	インシデントの宣言と管理
災害復旧計画	[Wiki / GitHub link]	ゾーン／リージョンの障害またはデータ損失

監視ダッシュボード：

ダッシュボード	リンク	用途
サービス概要	[Datadog / Grafana link]	エラー率、レイテンシ、スループット
インフラストラクチャ	[Link]	CPU、メモリ、ポッドの状態
データベース	[Link]	クエリのパフォーマンス、コネクションプール
SLO／エラーバジェット	[Link]	バジェットの消費率、可用性
依存関係の健全性	[Link]	上流の依存関係の状態

---

既知の制限事項

制限事項を正直に記載してください。このセクションにより、他のチームが誤った前提に基づいて構築するのを防げます。

制限事項	影響	回避策	修正予定
[例：一括書き込み API がないため、項目を1つずつ作成する必要があります]	[大量のインポートでは遅く、N 回の HTTP 呼び出しが必要です]	[100件を超える場合は、バッチインポート CLI ツールを使用してください]	[第3四半期に一括 API を予定 — チケット：[URL]]
[例：リストエンドポイントの最大ページサイズは100です]	[1回の呼び出しで100件を超える項目を取得できません]	[cursor パラメーターを使用してページネーションしてください]	[現在、拡大する予定はありません — 仕様です]
[例：レート制限はサービス単位ではなくトークン単位です]	[トラフィックの多い利用者が、同じトークンを使う他の利用者の制限に達する可能性があります]	[専用のサービスアカウントトークンをリクエストしてください]	[サービス単位のレート制限をロードマップに掲載]
[例：リストエンドポイントでは、書き込み直後の読み取りに結果整合性が適用されます]	[作成直後、レコードがリストに表示されるまでに時間がかかる場合があります（遅延 <500ms）]	[作成を確認するには GET /:id を使用してください。即時の整合性を確認するためにリストに依存しないでください]	[?consistent=true による自分の書き込みの読み取り整合性を実装中]

はじめに

このサービスの利用を開始するには：

1. アクセスを申請します：[アクセス申請フォームまたは手順へのリンク]
2. サービスアカウントの認証情報を取得します：[手順へのリンク]
3. API ドキュメントを読みます：[OpenAPI 仕様の URL]
4. サンドボックス環境を試します：https://[service-name].sandbox.[company].com
5. 利用者向け Slack チャンネルに参加します：#[service-name]-consumers

クライアントライブラリ（利用可能な場合）：

言語	パッケージ	インストール
[Python]	[[package-name]]	pip install [package-name]
[Go]	[github.com/[org]/[package]]	go get github.com/[org]/[package]
[TypeScript/JS]	[@[org]/[package]]	npm install @[org]/[package]

---

品質チェック

• 「概要」は専門用語を使わずに書かれており、別のチームの新人エンジニアでも 2 分以内に理解できます
• SLO の目標値は、関係者と合意した具体的な数値です。希望的な目標やテンプレートからの転記ではありません
• 「依存しているユーザー」テーブルに、直接利用しているすべての上流の利用者が記載されています。抜け漏れはありません
• API エラーコードは正確で、テスト済みです。希望的な内容のドキュメントではありません
• 既知の制限事項を率直に記載しています。サービスを実態以上によく見せるために隠していることはありません
• ランブックへのリンクはすべて有効です。参照切れや TODO のプレースホルダーはありません
• データ分類には、保持期間と暗号化の状況が含まれています。機密性レベルだけではありません
• 少なくとも 1 つの利用者チームがエントリーをレビューし、サービスに関する自分たちの経験と一致していることを確認しています

アンチパターン

• 希望的な SLO の目標値を書かないでください。目標値は、テンプレートから転記するのではなく、関係者と合意し、過去のデータに基づいて設定する必要があります
• ランブックへのリンクを TODO のプレースホルダーのままにしないでください。リンク切れやリンクの欠落があると、インシデント発生時にカタログエントリーが役に立たないどころか、かえって悪影響を及ぼします
• サービスをよく見せるために「既知の制限事項」セクションを省略しないでください。制限事項を開示しないと、誤った連携や下流でのインシデントにつながります
• テストせずに API エラーコードを記載しないでください。希望的なエラーの説明は利用者を誤解させます
• 「概要」セクションに専門用語を使わないでください。別のチームの新人エンジニアでも 2 分以内に理解できる必要があります