sql-to-business-logic

SQL からビジネスロジックへの翻訳

使用する場面

• ステークホルダーから「このクエリは具体的に何を計算しているのですか？」と尋ねられたとき
• 技術的な知識がない読者向けに、クエリライブラリや dbt モデルを文書化するとき
• クエリのロジックをビジネス要件と比較して、正確性を確認するとき
• 新しいアナリストに既存の SQL パターンを紹介するとき
• リファクタリングの前に、文書化されていないレガシークエリを翻訳するとき

プロセス

1. クエリとコンテキストを受け取る — SQL と、それが答えるビジネス上の問いを入手します。また、スキーマに関する情報（主要なテーブルや列がビジネス上どのような意味を持つか）も収集します。
2. FROM/JOIN の構造を翻訳する — どのデータソースがどのように結合されているか、またどの種類の結合が使われているかを平易な言葉で説明します（内部結合では一致する行だけが残り、左外部結合では左側のすべての行が残ります）。結合の種類が示された目的と一致していないように見える場合は、その点を記載します。
3. WHERE フィルターを翻訳する — 各フィルター条件を、ビジネスルールとして平易な言葉で列挙します（例：status = 'completed' →「支払いと処理が完了した注文のみを含める」）。
4. GROUP BY と集計を説明する — 各集計で何を、どの粒度で計算するかを説明します。scripts/sql_explainer.py を使って、構造を最初に解析します。
5. 出力列を要約する — 各出力列のビジネス上の意味と、特殊なケース（NULL 値、丸め処理、通貨単位など）を記載します。
6. 問題点を指摘し、検証のための質問を作成する — 潜在的な問題（暗黙の NULL 伝播、想定外の行数増加、ハードコードされた日付など）を特定します。クエリの作成者に確認する質問を 3～5 個作成します。翻訳全体の記録には assets/query_documentation_template.md を使います。

このスキルに必要な入力

• 完全な SQL クエリ（SELECT から ORDER BY まで）
• クエリが答えることを意図したビジネス上の問い
• テーブルと列の説明（またはデータカタログのエントリー）
• 主要なステータス値、日付の扱い、通貨に関するビジネスルール
• 想定される出力：誰が結果を読み、どのような意思決定に使うか

出力

• scripts/sql_explainer.py — SQL クエリを解析し、構造化された平易な言葉の説明を生成します
• assets/query_documentation_template.md — 目的、手順ごとのロジック、出力列、ビジネスルール、検証のための質問を記載した翻訳
• 任意：クエリのロジックを表すフローチャート