planetscale-customer-report-template

顧客向けレポートのテンプレート

目的

顧客のデータベースと、任意で接続されたリポジトリについて、明確な評価レポートを作成します。レポートは、実行可能で、根拠に裏付けられ、安全である必要があります。推奨事項と適用済みの変更を分けて記載します。

トーンと表現

レポートの目的は、顧客が利用中のプラットフォームを最大限に活用できるよう、正確に評価することです。機能の利用促進は、表現ではなく、証拠に基づいて行います。技術的かつ断定的な文体を用います。マーケティング文句ではなく、エンジニアによる評価として記述します。

• 未使用の機能は、影響を定量化した機能上のギャップとして記載します。 「無効（良い）」「未有効化（安全）」など、またはそれ以外の形で、機能を利用していないことを肯定的な所見として示してはいけません。適切な形式は、現状、その機能が提供するもの、およびその機能が該当する測定結果を記載することです。 例：「生クエリの収集：無効。これを有効にすると、実行ごとのリテラルなパラメーター値が確認できるようになります。Q1（クエリ総実行時間の38%）に該当しますが、パターンレベルのデータだけでは、トリガーとなった実行を特定できません。」
• 熱意を示す表現は使いません。 「十分に役立っている」「効果が出ている」「簡単に導入できる」「根本原因の特定にかかる時間を数時間から数分に短縮する」などの表現や、いかなる感嘆表現も使用しないでください。仕組みと測定結果を記載し、数値によって説明します。
• 運用コストは、和らげることなく事実として本文中に記載します。 「リテラル値が可観測性パイプラインから確認できるようになる」は機能の特性です。安心させるような言葉を添えず、一度だけ記載します。
• すべての推奨事項に、対応する具体的な所見（フィンガープリント、メトリクス、イベント数、期間）を明記します。 測定結果を伴わない推奨事項は不完全です。
• 有効な機能は評価し、称賛しません。 機能が有効な場合は、現在の動作を測定可能な形で記載し（「異常検知により、7日間で接続数の急増が9回検出されました。配信チャネルは設定されていません」）、設定が完了しているかどうかを示します。
• 適合性も分析の一部です。証拠から見て顧客にその機能が適していない場合は、その旨を記載します。
• 推奨事項は、現状の脅威ではなく、変更によって実現する内容を軸に記述します。 「認証情報の侵害による影響範囲を限定する」ではなく、「サービスごとに認証情報を分け、ダウンタイムなしでローテーションできる専用のアプリケーションロールを設ける」と記載します。「影響範囲」「保護されていない」「露出している」「デフォルトで公開」「リスクがある」など、危機感をあおる表現は避けます。実際のリスクは、事実として記載します。「本番ブランチではレプリカが0台であり、プライマリの障害からの復旧にはリストアが必要です」は所見であり、レポートに記載します。避けるのは危機感をあおる表現であり、開示ではありません。
• プラットフォームの動作は、推測ではなく、検証済みの仕様に基づいて報告します。 2つのAPIサーフェスに異なる値が表示される場合、通常は別々の設定を示しています。ドキュメントを確認し、有効な状態を報告します。検証されていない推測に基づいて、プラットフォームの動作に一貫性がない、矛盾している、またはバグがあると断定してはいけません。仕様を検証できない場合は、各サーフェスに表示されている内容を結論を出さずに記載し、PlanetScale サポートに問い合わせるよう案内します。検証の結果、プラットフォームの動作に実際の誤りがある場合は、事実に基づいて報告し、PlanetScale サポートに引き継ぎます。これはプラットフォームの問題であり、顧客の設定に関する所見ではありません。

実行状況と調査結果は分けて記載します

評価ツールの障害（HTTP ステータスコード、MCP エラー、CLI の失敗、トークンスコープの問題、タイムアウト、エンドポイントのプローブ）は、実行状況を表すものであり、データベースの状態を表すものではありません。これらは調査結果ではなく、実行ログに記載します。

• 証拠を収集できなかった場合、レポートにはエラーの詳細を付けず、「この実行では評価できませんでした」と記載します。
• 証拠の付録には収集した証拠を記載します。
• 実行ログ（ツールエラー、試行したパス、アクセスできなかった箇所）はレポートに添付され、評価を実行した担当者が参照できます。情報を隠すことはありません。ツールのエラーは顧客のデータベースについて何も示さないため、分けて記載します。
• 呼び出しが失敗したことを根拠に、機能が未設定だと結論づけてはいけません。「未設定」と判断するには、呼び出しが成功し、結果が空である必要があります。

出力形式

レポートはプレーンな Markdown で、見出し付きのセクション、文章、パイプテーブルで構成します。これが基本形式であり、必ず全内容を出力してください。あらゆるエージェント、ターミナル、チャット画面で利用できます。ホストエージェントがより豊かな表示形式（Cursor のキャンバス、HTML プレビュー、ダッシュボードなど）を提供している場合は、Markdown レポートの代わりではなく、追加で使用してもかまいません。

必須のレポート形式

PlanetScale のベストプラクティス評価

スコープ

• 組織：
• データベース：
• レビュー対象のブランチ：
• エンジン：
• レビュー対象のリポジトリ：
• 使用したインターフェース：
• 対象期間：
• 適用した変更：なし

エグゼクティブサマリー

箇条書きで3～7項目を記載します。最初の項目では、このデータベースに対してプラットフォームが現在行っていることを、測定値を含め、事実に基づいて記載します。たとえば、レプリカのトポロジーとフェイルオーバーの態勢、バックアップの頻度と最終成功日時、Insights の収集量、有効な安全機能などです。称賛ではなく、レポートの土台となる運用上の現状を示します。 続いて、次の項目を記載します。

• 最もリスクの高い安全性のギャップ。
• 観測可能性を向上させる、最も効果の高い改善策。
• 自動化に関する、最も効果の高い機会。
• エンジン固有のワークフローのギャップ。
• リポジトリの計測に関するギャップ。

現状

データベースとブランチのトポロジー

証拠を含めます。

安全性ワークフロー

Vitess の場合：

• 安全なマイグレーション。
• デプロイリクエスト。
• 承認要件。
• ゲート付きデプロイの利用状況。
• スキーマのリバート手順書。

Postgres の場合：

• ブランチのマイグレーションワークフロー。
• ロール。
• pg_strict。
• トラフィック制御。
• バックアップ／PITR。
• コネクションプーリング。
• プライベート接続と IP 制限。

観測可能性

• Query Insights の状態。
• 異常。
• クエリタグ。
• 生クエリの収集状況。
• スキーマの推奨事項。

自動化

• Webhook。
• エージェントのループ。
• CI／PR ワークフロー。
• インシデントのルーティング。

リポジトリの計測

• 検出されたフレームワークと ORM。
• 現在の SQL コメントまたはトレース。
• 推奨する SQLCommenter パッケージ／パス。
• タグスキーマ。

推奨事項

次のテーブル構造を使用します。

ID	推奨事項	対象	利点	リスク	承認が必要	事前テストが必要	証拠

推奨事項 ID：

• Insights／クエリタグには OBS-*。
• Vitess の安全性／デプロイワークフローには VIT-*。
• Postgres のロール、pg_strict、トラフィック制御、PITR、ネットワークには PG-*。
• Webhook と自動化には WEB-*。
• リポジトリの計測には APP-*。
• MCP／エージェントのワークフローには AGENT-*。

承認が必要な変更案

変更案ごとに、次の内容を含めます。

• ID。
• 正確な対象。
• 正確な変更内容。
• 使用するインターフェース。
• 推奨する理由。
• 予想される効果。
• 可用性への影響の可能性。
• テスト計画。
• ロールバック計画。
• 本番環境を変更するかどうか。

意図的に適用しなかった変更

以下の内容を明確に記載します。

• PlanetScale の設定は変更していません。
• スキーマは変更していません。
• トラフィック制御は変更していません。
• ロールや認証情報は変更していません。
• Webhook は変更していません。
• コードは変更していません。
• ブランチ、バックアップ、復元、デプロイリクエスト、マイグレーションは作成していません。

証拠の付録

証拠項目ごとに、次の内容を記載します。

• 出典。
• コマンド／API／MCP／リポジトリのパス。
• タイムスタンプ。
• 値。
• 注記。

最後に必ず記載する文

レポートの末尾に、次の文を記載してください。

“No changes have been applied. Approve specific change IDs before any mutation.”