dynamodb-single-table

DynamoDB シングルテーブル設計パイプライン

このスキルは、DynamoDB のシングルテーブル設計を設計・実装するための 3 ステップのパイプラインを実行します。ユーザーがワークフロー全体を希望する場合や、次にどのステップに進めばよいかのガイダンスが必要な場合に使用します。

パイプラインの概要

  Step 1                    Step 2                    Step 3
  ┌──────────────────┐      ┌──────────────────┐      ┌──────────────────┐
  │ Access Patterns   │ ──>  │ Table Design      │ ──>  │ Query Interfaces  │
  │                   │      │                   │      │                   │
  │ Elicit entities   │      │ Design PK/SK/GSI  │      │ Generate method   │
  │ & access patterns │      │ Map AP -> Query   │      │ signatures & types│
  │ Output: .md file  │      │ Output: .md file  │      │ Output: .md file  │
  └──────────────────┘      └──────────────────┘      └──────────────────┘
  Skill:                    Skill:                    Skill:
  dynamodb-access-patterns  dynamodb-table-design     dynamodb-query-interfaces

ステップ 0：パイプラインの状態を確認する

ルーティングの前に、ユーザーのプロジェクトにパイプラインの成果物がすでにあるか確認します。次のパターンに一致するファイルを検索します。

• **/access-patterns.md または **/access_patterns.md
• **/table-design.md または **/table_design.md
• **/query-interfaces.md または **/query_interfaces.md

次の一般的な場所も確認します。

• docs/dynamodb/
• docs/
• プロジェクトのルート

存在するファイルに基づいて判断します：

見つかったファイル	状態	アクション
なし	新規開始	dynamodb-access-patterns にルーティング
アクセスパターンのみ	ステップ 1 完了	ファイルパスを指定して dynamodb-table-design にルーティング
アクセスパターン + テーブル設計	ステップ 1～2 完了	ファイルパスを指定して dynamodb-query-interfaces にルーティング
3 つすべてのファイル	パイプライン完了	エンティティの追加、変更、またはレビューを希望するか尋ねる
テーブル設計のみ（アクセスパターンなし）	部分的／レガシー	アクセスパターンを文書化する必要があることを伝え、補完するかステップ 3 に進むか尋ねる

見つかった内容をユーザーに伝えます：

I found existing DynamoDB design artifacts in your project:

  [x] Access Patterns: docs/dynamodb/access-patterns.md
  [x] Table Design:    docs/dynamodb/table-design.md
  [ ] Query Interfaces: (not found)

You're ready for Step 3. Should I generate the query interfaces from
your table design?

ルーティング方法

ユーザーの希望	ルーティング先
ゼロから設計を始める	dynamodb-access-patterns
エンティティとそのクエリ方法を定義する	dynamodb-access-patterns
アクセスパターンがあり、キー設計が必要	dynamodb-table-design
テーブル設計があり、コードインターフェースが必要	dynamodb-query-interfaces
既存のテーブルに新しいエンティティを追加する	新しいエンティティについて dynamodb-access-patterns から始め、その後パイプラインを続ける
シングルテーブル設計の概念を理解する	以下の概念を使って直接回答する

基本概念（クイックリファレンス）

シングルテーブル設計とは？

すべてのエンティティタイプを 1 つの DynamoDB テーブルに格納します。関連データをあらかじめアイテムコレクション（同じパーティションキーを共有するアイテム）に結合しておくことで、1 回の Query 呼び出しで取得できます。これにより、結合が不要になり、ネットワークのラウンドトリップが減ります。

シングルテーブル設計を使用する場合

• どの規模でも 30 ミリ秒未満の応答時間が必要
• 頻繁には変更されない、明確に定義されたアクセスパターンがある
• 1 回のリクエストで複数のエンティティタイプを取得する必要がある
• OLTP ワークロードを構築している（分析用途ではない）

シングルテーブル設計を使用しない場合

• アクセスパターンが急速に変化している（スタートアップの初期段階）
• GraphQL のタイプごとのリゾルバーを使用している（リゾルバーモデルでは単一クエリのメリットが失われます）
• 柔軟なアドホッククエリが必要（代わりにリレーショナルデータベースを検討してください）

主要な原則

1. まずアクセスパターンを定義します。 クエリが分からないままキーを設計してはいけません。
2. アイテムコレクションにあらかじめ結合します。 関連データは同じパーティションキーを共有します。
3. テーブルは 1 つ、キー名は汎用的にします。 userId／orderId ではなく pk／sk を使用します。
4. 別のアクセスパターンには GSI を使用します。 新しいものを作成する前に再利用を検討します（最大 20 個）。
5. 複数フィールドのソートには複合ソートキーを使用します。 SK に階層構造をエンコードします。
6. スキャンは使用しません。 すべてのクエリでパーティションキーを使用する必要があります。Scan が必要なら、設計を見直してください。
7. 複数アイテムへの書き込みにはトランザクションを使用します。 アイテムコレクション間の一貫性を確保します。

作成される成果物

パイプラインの完了時に、ユーザーは 3 つのファイルを用意できます。

ファイル	内容	作成元
access-patterns.md	エンティティ、属性、すべての読み取り／書き込み／削除パターン	dynamodb-access-patterns
table-design.md	PK／SK の設計、GSI、アクセスパターンからクエリへのマッピング	dynamodb-table-design
query-interfaces.md	エンティティタイプ、キーのビルダー、リポジトリメソッドのシグネチャ	dynamodb-query-interfaces

これらのファイルは、実装フェーズの仕様として使用します。