ent-seed-sql-generator

Ent Seed SQL ジェネレーター

Ent スキーマとさまざまな根拠情報から、決定的な ID、有効なリレーション、本番環境に近い現実的なデータを含む、実行可能なシード SQL アーティファクトを 1 つ生成します。SQL を書き始める前に生成計画を確認し、方言、戦略、範囲の不一致による無駄を防ぎます。

ユーザーと方言、戦略、エンティティの範囲、おおよその行数を確認する（または根拠情報からそれらを確定する）までは、SQL を絶対に書かないでください。方言の誤った想定はすべての行を無効にし、戦略の誤った選択はやり直しを招きます。

使用する場合／使用しない場合

Ent スキーマの情報、ドキュメント、デモの動作、またはプロンプトの要件に基づいてシード SQL を生成または修正する場合に、このスキルを使用します。

スキーマのマイグレーション設計、実行時のリポジトリ／サービス実装、クエリのパフォーマンスチューニングには、このスキルを使用しないでください。

参照ファイルの読み込み計画

現在のタスクに必要なものだけを読み込みます。

• references/model-extraction.md：エンティティ／フィールド／リレーションの抽出と依存関係の計画
• references/id-and-relation-rules.md：決定的な ID、外部キーの整合性、マルチテナントの制約
• references/output-sql-pattern.md：最終 SQL の構成と戦略ごとのパターン
• references/password-hashing.md：認証情報フィールドをシードする場合のみ

チェックリスト

次の順番で進めます。各項目にタスクを作成してください。

1. 入力を収集する — プロンプト、Ent スキーマファイル、既存のシード、製品ドキュメント
2. 方言を特定し、曖昧な点を解決する — 不明な場合は一度に 1 つずつ質問する
3. 生成計画を提示する — エンティティ、戦略、行数を示して承認を得る
4. スキーママップを作成する — 依存関係の順序、外部キーのグラフ、列挙値
5. SQL アーティファクトを生成する — output-sql-pattern.md に従う
6. 品質ゲートを実行する — 孤立した外部キー、一意性違反、必須フィールドの欠落を確認する

処理フロー

digraph ent_seed_sql_generator {
    "Collect inputs" [shape=box];
    "Any ambiguities?" [shape=diamond];
    "Ask clarifying question\n(one at a time)" [shape=box];
    "Present generation plan" [shape=box];
    "Plan approved?" [shape=diamond];
    "Build schema map\n& dependency order" [shape=box];
    "Generate SQL artifact" [shape=box];
    "Quality gates" [shape=box];
    "Deliver artifact" [shape=doublecircle];

    "Collect inputs" -> "Any ambiguities?";
    "Any ambiguities?" -> "Ask clarifying question\n(one at a time)" [label="yes"];
    "Ask clarifying question\n(one at a time)" -> "Any ambiguities?";
    "Any ambiguities?" -> "Present generation plan" [label="no"];
    "Present generation plan" -> "Plan approved?";
    "Plan approved?" -> "Present generation plan" [label="revise"];
    "Plan approved?" -> "Build schema map\n& dependency order" [label="yes"];
    "Build schema map\n& dependency order" -> "Generate SQL artifact";
    "Generate SQL artifact" -> "Quality gates";
    "Quality gates" -> "Deliver artifact";
}

フェーズ 1：入力の収集と確認

次の順序で利用可能な入力を収集します。

1. 現在のプロンプトの要件
2. Ent スキーマとマイグレーション／DDL ファイル（ent/schema/*.go、ent/migrate/）
3. 既存のシードファイルとデモコードの動作
4. 製品ドキュメントとドメインに関するメモ

次に、SQL の方言を特定します。

• ent/client.go または設定ファイルでドライバー名（mysql、postgres、sqlite）を確認する
• マイグレーションファイルで方言固有の構文を確認する
• go.mod で方言のインポート（ent/dialect/mysql など）を確認する

利用可能な入力を確認しても次のいずれかが不明な場合は、一度に 1 つずつ質問してください。

• 方言：「プロジェクトファイルからデータベースの方言を特定できませんでした。対象は MySQL、PostgreSQL、SQLite のどれですか？」
• 戦略：「このシードは一度限り（新規セットアップのみ）、冪等（INSERT OR IGNORE／ON CONFLICT DO NOTHING）、アップサート（ON CONFLICT DO UPDATE）のどれにしますか？」
• 範囲：「すべてのエンティティをシードしますか、それとも特定のエンティティのみですか？後者の場合、対象を教えてください。」
• 行数：「エンティティごとに何行必要ですか？（開発用シードでは 3～10 行が一般的です）」

利用可能なファイルから回答できる質問はしないでください。出力を実際に左右する点だけを質問します。

フェーズ 2：生成計画

SQL を書く前に、簡潔な計画を提示します。

方言： MySQL 戦略： 冪等 エンティティの順序（依存関係順）：

1. organizations — 3 行、依存関係なし
2. users — 5 行、外部キー → organizations
3. projects — 4 行、外部キー → organizations + users

ID の範囲： organizations 2000～2999、users 1000～1999、projects 3000～3999 前提： パスワードフィールドには、テスト用認証情報として固定の bcrypt ハッシュを使用する

書き始める前に、この内容でよいか確認してください。

タスクの複雑さに応じて計画の詳細さを調整します。外部キーのない単一エンティティの場合は、1 行の要約で十分です。多数のテーブルを持つマルチテナントシステムの場合は、依存関係の順序をすべて記載してください。

フェーズ 3：スキーママップの作成

計画の承認後、references/model-extraction.mdを読み、ent/schema/*.goから以下を抽出します。

• フィールド：型、Optional、Nillable、Unique、Default、Immutable、Sensitive
• 列挙型：field.Enumまたはvalidateルールにあるすべての有効な値
• エッジ：edge.To、edge.From、Required、Unique、Ref ― FKの所有元を導き出します
• インデックス：一意制約と複合インデックス

トポロジカルな依存順を計算します。FK参照のないテーブルを最初に配置し、依存するテーブルをその後に配置します。結合テーブルは最後に配置します。

フェーズ 4：SQL成果物の生成

references/output-sql-pattern.mdに従います。IDの範囲とFKの整合性については、references/id-and-relation-rules.mdを適用します。

IDの割り当て：

• 整数のPK：エンティティ型ごとに重複しない範囲を使用します
• 文字列のPK：意味のあるID（usr_admin、org_acme）を使用します
• UUID：ビジネスキーから決定的に生成し、ランダムな値は使用しません

データの整合性：

• タイムスタンプ：created_at <= updated_atとし、現実的な範囲に分散させます
• ステータスの推移：現実的なライフサイクル（draft → active → archived）にします
• 所有関係：すべてのowner_idが既存のユーザー行を参照するようにします
• テキストコンテンツ：Lorem Ipsumではなく意味のある文字列を使用し、実際のメールアドレス形式にします

認証情報のフィールドについては、references/password-hashing.mdを読みます。

方言固有のパターン：

型	PostgreSQL	MySQL	SQLite
JSON	'{"k":"v"}'::jsonb	'{"k":"v"}'	'{"k":"v"}'
配列	ARRAY['a','b']	ネイティブ非対応	ネイティブ非対応
真偽値	TRUE/FALSE	1/0	1/0
タイムスタンプ	'2026-01-01 09:00:00'	'2026-01-01 09:00:00'	'2026-01-01 09:00:00'

インラインで処理する特殊ケース：

• 論理削除：有効なレコードのdeleted_atをNULLに設定します
• 自己参照（ツリー）：ルートを最初に挿入し、子が有効な親IDを参照するようにします
• マルチテナント：テナントテーブルを最初にシードし、依存するすべてのテーブルに有効なテナントFKを持たせます
• 複合一意制約：すべての列の組み合わせが行間で一意であることを確認します

フェーズ 5：品質ゲート

成果物を提出する前に、以下を確認します。

• 孤立したFKがないこと ― 参照されるすべてのIDが存在する
• 一意制約違反がないこと ― 複合一意インデックスも含む
• プレースホルダーやTODO値がないこと
• すべてのIDが決定的であること（ランダム値や自動生成値がない）
• タイムスタンプに内部的な矛盾がないこと（created_at <= updated_at）
• すべての必須フィールド（EntスキーマのRequired()）が各INSERTに含まれていること
• 無効な列挙値がないこと
• JSON列に有効なJSON文字列が含まれていること

出力の要件

以下を含むSQL成果物を1つだけ（ユーザーの依頼に応じてインラインまたはファイルで）提出します。

1. ヘッダーコメント：入力ソース、方言、戦略、前提条件
2. 任意のクリーンアップブロック（冪等またはアップサート戦略の場合のみ）
3. 依存順にまとめたINSERTブロック。各グループの前にコメントを付けます
4. 任意の検証用SELECTクエリ（依頼があった場合のみ）

ガードレール

• 根拠なくテーブルや列を作り出さないでください。推論はコメントとして明記します
• ランダムなIDを使用しないでください。シードIDは実行ごとに安定させます
• FKの依存順を崩さないでください。親を先に、結合テーブルを最後に配置します
• 行数を不必要に増やさないでください。コアテーブルあたり3～10行で通常は十分です
• 本番環境の認証情報を公開しないでください。テスト専用の値を使用します
• 1つのファイルで複数の方言を混在させないでください
• 必須フィールドを省略しないでください

関連スキル

• 上流 — ent-schema-implementer は主要な入力となる ent/schema/*.go を提供します。スキーマがまだ作成されていない場合は、db-schema-designer が prd/DDL.md を提供します。どちらもない場合は、テーブルを創作せず、ユーザーが提示するスキーマの根拠に基づいて作業してください。
• 下流 — ありません。SQL 成果物は最終成果物です。データではなく実行時のサービスコードに対応する必要がある場合は、sphere-feature-workflow を使用してください。
• 境界 — スキーマとマイグレーションの設計には db-schema-designer を使用してください。このスキルが担当するのは、決定的なシード SQL とフィクスチャ SQL のみです。
• 補完スキル — ありません。
• 参照先のスキルがこのセッションにインストールされていない場合は、引き継ぎメッセージでその名前を伝え、現在の成果物の作業を続けてください。作業を停滞させないでください。