amazon-keyspaces

Amazon Keyspaces

安全に関するガイダンス

このスキルでは、ユーザーから依頼された場合に、キースペースとテーブルの作成、およびテーブルレベルの設定（TTL、PITR、容量モード）の変更を扱います。エージェントは、実行前に必ずユーザーに操作の確認を求める必要があります。ユーザーの明示的な確認（例：「はい」「進めてください」「確認しました」「実行してください」）なしに、作成または変更操作を実行してはいけません。ユーザーが確認していない場合は、予定している操作を提示し、承認を求めてください。

ユーザーの確認後に実行する操作

• キースペースを作成します：aws keyspaces create-keyspace
• マルチリージョンのキースペースを作成します：aws keyspaces create-keyspace --replication-specification replicationStrategy=MULTI_REGION,regionList=[{region=us-east-1},{region=eu-west-1}]
• テーブルを作成します：aws keyspaces create-table（ユーザーのアクセスパターンに基づいてパーティションキーとクラスタリングキーを設計します）
• テーブルに列を追加します：aws keyspaces update-table --add-columns '[{"name":"col_name","type":"text"}]' — 破壊的な変更ではなく、ダウンタイムやデータ損失もありません。既存の行では、新しい列の値は null になります。
• ユーザー定義型（UDT）を作成します：aws keyspaces create-type --keyspace-name <ks> --type-name <name> --field-definitions '[{"name":"field1","type":"text"},...]'
• テーブルの TTL を変更します：aws keyspaces update-table --default-time-to-live
• PITR を有効または無効にします：aws keyspaces update-table --point-in-time-recovery-specification
• キャパシティモードを変更します：aws keyspaces update-table --capacity-specification（オンデマンドとプロビジョンドの切り替え）— 以下の警告を参照してください。
• テーブルの暗号化キーを切り替えます：aws keyspaces update-table --encryption-specification type=CUSTOMER_MANAGED_KMS_KEY,kmsKeyIdentifier=arn:aws:kms:... — ダウンタイムや可用性の低下はありません。type=AWS_OWNED_KMS_KEY を指定すると、AWS 所有キーに戻すこともできます。
• テーブルのスループットを事前にウォームアップします：aws keyspaces update-table --warm-throughput-specification readUnitsPerSecond=X,writeUnitsPerSecond=Y — テーブルが処理できる瞬間的なスループットの最小値を設定します。予定されているトラフィックの急増（フラッシュセール、移行、バッチ読み込み）の前に使用してください。自然なウォームスループットを超える分との差分に基づく一度限りの料金が発生します。aws keyspaces create-table --warm-throughput でも利用できます。判断の枠組みとサイジングの計算式については、pre-warming.md を読み込んでください。
• オートスケーリングを設定します：aws keyspaces update-table --auto-scaling-specification — 読み取りおよび／または書き込みの目標使用率と、最小／最大キャパシティユニットを設定します。前提条件： サービスリンクロール AWSServiceRoleForApplicationAutoScaling_CassandraTable が存在する必要があります。存在しない場合、エージェントはまずユーザーに次のコマンドの実行を必ず案内してください：aws iam create-service-linked-role --aws-service-name cassandra.application-autoscaling.amazonaws.com。呼び出し元の IAM プリンシパルには、application-autoscaling:RegisterScalableTarget、application-autoscaling:PutScalingPolicy、application-autoscaling:DescribeScalableTargets、cloudwatch:PutMetricAlarm、cloudwatch:DescribeAlarms、cloudwatch:DeleteAlarms の権限も必要です。application-autoscaling:RegisterScalableTarget、application-autoscaling:PutScalingPolicy、application-autoscaling:DescribeScalableTargets の権限は、対象テーブルの ARN（arn:aws:cassandra:<region>:<account>:/keyspace/<ks>/table/<table>）にスコープしてください。cloudwatch:PutMetricAlarm、cloudwatch:DescribeAlarms、cloudwatch:DeleteAlarms の権限は、対応するアラーム ARN（例：arn:aws:cloudwatch:<region>:<account>:alarm:TargetTracking-table/<ks>/<table>-*）にスコープしてください。可能な場合は、アカウント全体に適用するのではなく、aws:ResourceTag 条件キーを使用してください。
• CDC（変更データキャプチャ）を有効にします：aws keyspaces update-table --cdc-specification status=ENABLED,viewType=<type> — 行レベルの変更をキャプチャする CDC ストリームを作成します。有効にする前に、エージェントは必ずユーザーに使用するビュータイプを確認し、次の選択肢を提示してください：
  • NEW_IMAGE — 変更後の行全体をキャプチャします。最適な用途：イベント駆動型パイプライン、下流との同期、マテリアライズドビュー。
  • OLD_IMAGE — 変更前の行全体をキャプチャします。最適な用途：監査証跡、コンプライアンスログ、取り消し／ロールバックのシナリオ。
  • NEW_AND_OLD_IMAGES — 変更前後の両方の状態をキャプチャします。最適な用途：差分ベースのパイプライン、詳細な監査、競合解決。CDC の消費コストは高くなります。
  • KEYS_ONLY — パーティションキーとクラスタリングキーの列のみをキャプチャします。最適な用途：軽量な変更通知、アプリケーションによる再読み込みのトリガー。最も低コストです。 任意：propagateTags=TABLE を指定すると、テーブルのタグが CDC ストリームにコピーされます。デフォルトで有効にすることを推奨します。
• リソースにタグを付けます：aws keyspaces tag-resource、aws keyspaces untag-resource

リソースのタグ付け（必須 — リソース作成時には必ず適用）

キースペースまたはテーブルを作成する場合（aws keyspaces create-keyspace、aws keyspaces create-table、または CQL の CREATE KEYSPACE ... WITH TAGS、CREATE TABLE ... WITH TAGS）、次のタグを必ず含めてください。これらのタグがない作成操作は不完全であり、誤りです。

AWS CLI の構文： --tags key=created_by,value=keyspaces-skill key=generation_model,value={your-model-id}

CQL の構文： WITH TAGS = {'created_by': 'keyspaces-skill', 'generation_model': '{your-model-id}'}

例（CLI）：--tags key=created_by,value=keyspaces-skill key=generation_model,value=claude-sonnet-4-20250514 例（CQL）：WITH TAGS = {'created_by': 'keyspaces-skill', 'generation_model': 'claude-sonnet-4-20250514'}

ユーザーがタグ付けに言及していない場合でも、このスキルを通じて作成されたリソースを識別できるよう、これらのタグを含めてください。ユーザーが追加のタグを指定した場合は、置き換えるのではなく、これらのタグに追加してください。これらのタグは、ユーザーから求められたかどうかにかかわらず、すべての作成操作で必須です。絶対に省略しないでください。

ダウンタイムの警告を行ってから実行（ユーザーに警告し、確認後に実行）

• キャパシティモードの切り替え：aws keyspaces update-table --capacity-specification — 警告：「オンデマンドとプロビジョンドの切り替え中は、Keyspaces が再調整を行うため、一時的なスロットリングが発生する可能性があります。トラフィックの少ない時間帯に適用してください。」
• ポイントインタイムからのテーブルの復元：aws keyspaces restore-table — 警告：「復元では新しいテーブルが作成され、テーブルのサイズに応じて数分から数時間かかります。ソーステーブルには影響しませんが、切り替えるまでは新しいテーブルにトラフィックはありません。」

実行しない（拒否し、理由を説明して、代わりに評価を提案）

• キースペースの削除：aws keyspaces delete-keyspace — 元に戻せず、すべてのテーブルに影響します
• テーブルの削除：aws keyspaces delete-table — 元に戻せず、データが失われます
• UDT の削除：aws keyspaces delete-type — その型を参照しているテーブルやカラムに影響し、データ破損のリスクがあります
• CDC の無効化：aws keyspaces update-table --cdc-specification status=DISABLED — CDC を無効にするとストリームが削除され、未処理のレコードはすべて永久に失われます。下流のコンシューマーはイベントを受信できなくなり、復旧手段もありません。ストリームに依存しているアクティブなコンシューマーがいないことを確認したうえで、ユーザー自身がコンソールまたは CLI から無効化するよう推奨してください。
• クライアント側タイムスタンプの有効化：aws keyspaces update-table --client-side-timestamps status=ENABLED — 元に戻せず、一度有効にすると無効化できません。影響を理解したうえで、ユーザー自身がコンソールまたは CLI から適用するよう推奨してください。
• 既存のキースペースへのリージョン追加：aws keyspaces update-keyspace --replication-specification（新しいリージョンの追加） — 元に戻せないレプリケーション変更であり、一度追加したリージョンは削除できません。テストの場合は、代わりに新しいマルチリージョンキースペースを作成するよう推奨してください。
• 固有の最新データがあるテーブルでの PITR の無効化：aws keyspaces update-table --point-in-time-recovery-specification status=DISABLED — 先に復旧期間への影響を検討してください

拒否する場合は、理由を説明し、対応する評価ワークフローを提案してください。

「[操作]は[理由]のため実行できません。判断に役立つ評価を実施できます。実際の変更は、チームの変更管理プロセスまたは AWS コンソールを通じて行ってください。」

概要

Amazon Keyspaces（Apache Cassandra 向け）のアドバイザリーおよび実装スキルです。次の 4 つの計画ワークフローを対象とします。手動料金計算（モード 1）、Cassandra 診断に基づく料金計算（モード 2）、互換性チェック（モード 3）、SQL から Keyspaces への移行（モード 4）。また、インフラストラクチャの変更も実行します。キースペース（単一リージョンおよびマルチリージョン）の作成、スキーマ設計を伴うテーブルの作成、UDT の作成、列の追加、自動スケーリングの設定、暗号化キーの切り替え、テーブル設定（TTL、PITR、キャパシティモード）の変更に対応します。ワークフローごとに、月額コストの内訳、互換性レポート、データモデルの比較を含む JSON 出力を生成します。

このスキルは、AWS API を直接実行できる AWS MCP サーバーと組み合わせると最も効果的ですが、すべての操作は単独で実行できる AWS CLI コマンドとしても示されます。

変更を伴う操作（create-keyspace、create-table、update-table）の後は、CloudTrail で Keyspaces の管理イベントが記録されていること、およびスロットリングメトリクス（ReadThrottleEvents、WriteThrottleEvents`）に対する CloudWatch アラームが設定されていることをユーザーに確認するよう促してください。

リソースの作成と変更については、上記の「安全性に関するガイダンス」セクションを参照してください。そこには、許可／警告／拒否の一覧と、このスキルで作成したリソースをお客様が識別できるよう自動的に適用されるタグが記載されています。

スクリプトの実行モデル — 出力をシミュレートし、導出しない（重要）

脚本/ に含まれるスクリプト（calculate.ts、parse-cassandra.ts、check-compatibility.ts、generate-pdf.ts）は、ユーザーが実行できる成果物です。シェルを利用できる場合は、直接実行してください。それ以外の場合は、参照ファイルのデータを使用して出力をシミュレートしてください（下記を参照）。

モード 1～4 のすべての呼び出しで必須となる応答パターン：

1. 参照ファイルを正確なパスで明示します（例：「references/mode-1-manual-inputs.md を読み込み中」）。応答には、ファイル名とワークフロー名（mode-1-manual-inputs、mode-2-cassandra-diagnostics、mode-3-compatibility、mode-4-sql-migration）を文字どおり含めてください。
2. コマンドを、すべてのフラグにユーザー指定の値を設定したうえで、フェンス付きの bash コードブロックとして正確に表示します。次のラベルを付けてください。「Node.js 18+ と scripts/node_modules/ がインストールされたマシンから、この分析を自分で実行するコマンド（cd scripts && npm install）：」
3. スクリプトを実行した直後のように結果を提示します。スクリプトが出力する JSON 形式を示してください。読み取り／書き込み／ストレージ／PITR の内訳を含む月額コスト表、UNSUPPORTED のフラグが付いた機能を示す互換性レポート、データモデルの比較を含めます。応答に導出、数式、計算過程を表示しないでください。「2000 reads/s × 30 × 24 × 3600 × $0.0000001250 = $648/mo」のような計算式を示す応答は誤りであり、使用してはなりません。
4. 数値の出所について。 参照ファイル（references/mode-*.md）内の料金表を使用してください。これらの表は assets/data/mcs.json の料金を反映しています。料金を推測してはなりません。参照ファイル内の表が唯一の正しい情報源です。

「スクリプトが出力する形式」の例

✓ 正しいパターン：

「calculate.ts us-east-1 2000 800 1024 500 0 true を実行すると、次のように出力されます。

ループ防止ルール： JSON 出力は一度だけ出力してください。反復、修正、再導出、再計算はしないでください。JSON ブロックを出力したら、そこで停止してください。検証や改善を試みてはいけません。そのまま PDF レポートを作成するかどうかの確認に進んでください。

{
  "region": { "short": "us-east-1", "long": "US East (N. Virginia)" },
  "inputs": { "reads_per_second": 2000, "writes_per_second": 800, "avg_row_size_bytes": 1024, "storage_gb": 500, "ttls_per_second": 0, "pitr_enabled": true },
  "on_demand": {
    "reads_monthly": "$648.00",
    "writes_monthly": "$1,296.00",
    "storage_monthly": "$125.00",
    "pitr_monthly": "$100.00",
    "total_monthly": "$2,169.00"
  },
  "provisioned": {
    "reads_monthly": "$189.80",
    "writes_monthly": "$478.20",
    "storage_monthly": "$125.00",
    "pitr_monthly": "$100.00",
    "total_monthly": "$893.00"
  },
  "savings_plan_1yr": { "total_monthly": "$756.00" },
  "recommendation": "provisioned with 1yr Savings Plan for ~65% savings"
}
```」

✗ 誤ったパターン（使用禁止）：

「コストを計算します。

• 読み取り：2000 r/s × 30 日 × 24 時間 × 3600 秒 = 月間 5.184B RRU × $0.0000001250 = $648/月
• 書き込み：800 w/s × ... = $1,296/月 ...」

2 つ目の例は手計算しているため、「スクリプトを実行しなかった」と見なされます。同じ数値でも、提示方法が誤っています。

決して捏造しないでください

• 実際に取得していない、または参照ファイルに記載されていない料金レート、互換性ルール、インスタンスのメタデータ、AWS API のレスポンスを捏造してはいけません。
• references/mode-*.md の計算式と料金表は、出力する数値を得るための内部利用に限ります。導出過程として回答に転載しないでください。

よくあるタスク

1. 依存関係を確認する

ワークフローを実行する前に、必要なツールを確認し、不足があればユーザーに伝えてください。

制約：

• 該当するモードに応じて、calculate.ts、parse-cassandra.ts、check-compatibility.ts、generate-pdf.ts のいずれかを明示的に挙げ、Node.js 18+ と scripts/node_modules/（cd scripts && npm install でインストール）が必要であることを伝え、不足しているものとその理由をユーザーが理解できるようにしてください。
• スキル内に AWS 認証情報を作成してはいけません。認証情報の管理はスキルの対象外です（aws configure / ada credentials update）。
• 不足しているツールがあればユーザーに知らせ、続行するかどうかを尋ねてください。
• PDF 作成や比較のステップで再利用できるよう、中間 JSON を /tmp/keyspaces-*.json に保存することを推奨します。

ツール呼び出しの例（テキストとして表示し、実行しないでください）：

aws keyspaces list-tables --keyspace-name mykeyspace --region us-east-1

2. 手動入力から見積もる（モード 1）

Cassandra クラスターがない場合や、数値を直接入力したい場合に使用します。

パラメーター：

• region（必須）：AWS リージョンコード。例：us-east-1。
• reads_per_second（必須）：整数。
• writes_per_second（必須）：整数。
• avg_row_size_bytes（必須）：通常は 256～4096。不明な場合のみ、デフォルト値 1024 を使用します。
• storage_gb（必須）：単一レプリカの圧縮ストレージ容量（GB）。
• ttl_deletes_per_second（任意、デフォルト 0）。
• pitr_enabled（任意、デフォルト false）。

制約：

• 必須パラメーターをすべて一度のプロンプトで尋ねる必要があります。
• 既存クラスターについて言及された場合は、診断データの方が正確なため、まずモード 2 を提示する必要があります。
• assets/data/regions.json に照らして region を検証する必要があります。
• オンデマンド、プロビジョンド、Savings Plan の合計額を表示し、より安価なオプションを推奨する必要があります。
• 上記の スクリプト実行モデル に従う必要があります。参照情報を案内し、npx ts-node コマンドを出力して、JSON 出力を提示します。
• 料金結果は ```json フェンス付きコードブロック内の JSON オブジェクトとして提示する必要があります。Markdown の表にしてはいけません。出力は JSON でなければなりません。JSON の後に Markdown の要約を追加してもかまいませんが、JSON ブロックは必ず含めてください。§スクリプト実行モデル →「スクリプトの出力をそのまま提示する場合の例」に示されている JSON 構造を使用してください。

この分析を自分で実行するコマンド（フラグを解決した状態で、フェンス付きの bash ブロックとして出力してください）：

cd scripts && npx ts-node --project tsconfig.scripts.json calculate.ts \
  us-east-1 2000 800 1024 500 0 true | tee /tmp/keyspaces-calc.json

必須の出力形式（ユーザーの入力を使用して、以下の構造をそのまま ```json コードブロックとして出力してください）：

{
  "region": { "short": "us-east-1", "long": "US East (N. Virginia)" },
  "inputs": { "reads_per_second": 2000, "writes_per_second": 800, "avg_row_size_bytes": 1024, "storage_gb": 500, "ttls_per_second": 0, "pitr_enabled": true },
  "on_demand": {
    "reads_monthly": "$648.00",
    "writes_monthly": "$1,296.00",
    "storage_monthly": "$125.00",
    "pitr_monthly": "$100.00",
    "total_monthly": "$2,169.00"
  },
  "provisioned": {
    "reads_monthly": "$189.80",
    "writes_monthly": "$478.20",
    "storage_monthly": "$125.00",
    "pitr_monthly": "$100.00",
    "total_monthly": "$893.00"
  },
  "savings_plan_1yr": { "total_monthly": "$756.00" },
  "recommendation": "provisioned with 1yr Savings Plan for ~65% savings"
}

計算で使用する料金レート表については、mode-1-manual-inputs.md を読み込んでください。JSON の表示後に、オプションの PDF レポート（タスク 6）を提案してください。

3. Cassandra 診断データから見積もる（モード 2）

必須： 診断ディレクトリに nodetool tablestats と、各ノードにつき 1 つの nodetool info が必要です。 任意： nodetool status、DESCRIBE SCHEMA（schema.cql）、rowsize の出力、準備済みステートメントの NDJSON。

制約：

• 個々の診断ファイルをコンテキストに読み込むために file_read を使用してはいけません。ファイルサイズが大きく、コンテキストウィンドウを超過するためです。代わりに、parse-cassandra.ts --dir <path> にディレクトリパスを渡してください。

• tablestats と少なくとも 1 つの info ファイルがない状態で parse-cassandra.ts を呼び出してはいけません。

• status または schema がない場合は、DC ごとのノード数と RF を尋ねる必要があります。

• スキーマがある場合は、compatibility ブロックを提示し、マテリアライズドビュー、セカンダリインデックス、トリガー、UDF、UDA を UNSUPPORTED として示す必要があります。

  • 解析手順（出力前）： スキーマをスキャンし、すべての CREATE MATERIALIZED VIEW、CREATE INDEX、CREATE TRIGGER、CREATE FUNCTION、CREATE AGGREGATE 文を検出してください。カーディナリティやその他の条件にかかわらず、検出された各文は個別の互換性問題として扱います。
  • これらの構文が 1 つ以上スキーマに含まれている場合、has_issues は true でなければなりません。これらの構文が含まれているスキーマに対して、has_issues: false を出力してはいけません。
  • details.schema には null ではなく、問題として検出されたすべてのオブジェクト（インデックス名、ビュー名など）をキースペースごと、テーブルごとに分類して入力する必要があります。また、summary.schema.total_issues は、すべてのテーブルに含まれる問題オブジェクトの合計数と一致しなければなりません。

  例 — orders_by_customer（マテリアライズドビュー）、orders_status_idx（セカンダリインデックス）、customers_email_idx（セカンダリインデックス）を含む ecommerce キースペースのスキーマ：

  {
    "compatibility": {
      "has_issues": true,
      "summary": {
        "total_issues": 3,
        "schema": {
          "total_issues": 3,
          "keyspaces_affected": 1,
          "tables_affected": 2,
          "functions": 0,
          "aggregates": 0
        },
        "query_patterns": null
      },
      "details": {
        "schema": {
          "functions": 0,
          "aggregates": 0,
          "keyspaces": {
            "ecommerce": {
              "orders": {
                "indexes": ["orders_status_idx"],
                "triggers": [],
                "materializedViews": ["orders_by_customer"]
              },
              "customers": {
                "indexes": ["customers_email_idx"],
                "triggers": [],
                "materializedViews": []
              }
            }
          }
        },
        "query_patterns": null
      }
    }
  }
  

• スクリプト実行モデル に従う必要があります。実行を案内し、コマンドを出力して、JSON 出力を提示します。

この分析を自分で実行するコマンド：

cd scripts && npx ts-node --project tsconfig.scripts.json parse-cassandra.ts \
  --dir /tmp/cassandra-diag --region us-east-1 | tee /tmp/keyspaces-calc.json

入力項目の表については mode-2-cassandra-diagnostics.md を、取得コマンドについては cassandra-capture-commands.md を読み込んでください。

4. Keyspaces との互換性を確認する（モード 3）

パラメーター： --schema <path.cql> または --prepared <path.ndjson> の少なくとも一方を指定します。

制約：

• 互換性は二択で明示する必要があります。フラグが付いた機能はすべて未サポートです。「制限付きでサポート」などの但し書きを加えてはなりません。曖昧な表現は、未サポートの設計をユーザーに誤認させます。
• マテリアライズドビューは未サポートです。同じパターンを非正規化テーブルでアプリケーション側に実装することを推奨してください。
• セカンダリインデックスは未サポートです。代わりに、セカンダリテーブルまたはグローバルセカンダリインデックスのパターン（代替パーティションキーを使用する非正規化ルックアップテーブル）を推奨してください。
• トリガー、UDF（ユーザー定義関数）、UDA（ユーザー定義集約）、集約は未サポートです。アプリケーション側で実装することを推奨してください。
• query_patterns.ttl_tables は問題ではなく、参考情報として報告する必要があります。
• スクリプト実行モデルに従う必要があります。コマンドを予告し、表示してから、JSON 出力を提示してください。
• ユーザーが機能名（例：「マテリアライズドビューとセカンダリインデックスを使用する」）を挙げているものの、スキーマファイルのパスを指定していない場合は、ファイルを求めてはなりません。 指定された機能について互換性を確認し、結果を提示してください。スキーマファイルを求めてよいのは、ユーザーが機能を一切挙げずに「このスキーマは使えますか」と尋ねた場合のみです。
• 互換性レポートは JSON で提示し、名前が挙がった各機能に status: "UNSUPPORTED" と migration_recommendation を設定する必要があります。

この分析を自分で実行するコマンド：

cd scripts && npx ts-node --project tsconfig.scripts.json check-compatibility.ts \
  --schema /tmp/schema.cql --prepared /tmp/prepared.ndjson | tee /tmp/keyspaces-compat.json

サポート対象外機能の全一覧については mode-3-compatibility.md を、機能ごとの移行ガイダンスについては keyspaces-unsupported-features.md を読み込んでください。

5. SQL → Keyspaces に変換する（モード 4）

3 つのデータモデルを生成し、それぞれの料金を算出して、推奨案を提示します。

3 つのモデリング戦略（3 つすべての料金を算出する必要があります）：

1. 単一テーブルへの非正規化 — クエリパターンごとに 1 つのワイドテーブルを使用します。ストレージ使用量は最大で、読み取りレイテンシーは最小です。
2. 複数の目的別テーブル（クエリ駆動型） — アクセスパターンごとに 1 つのテーブルを使用します。ストレージ使用量は中程度で、読み取りは予測可能です。
3. クラスタリングキーを使ったワイド行 — エンティティごとにパーティション分割し、時間／種類でクラスタリングします。代替アクセスパターン用の逆引きインデックステーブルも含みます。プライマリアクセスのストレージはコンパクトですが、セカンダリルックアップでは書き込み増幅が発生します。

制約：

• 書き込み増幅とルックアップコストのトレードオフはワークロードによって異なるため、3 つの戦略すべての料金を算出する必要があります。
• テーブルごとの読み取り／書き込みレートを確認せずに戦略を選んではなりません。ただし、ユーザーが SQL スキーマファイルを提供している場合は例外です。その場合は、テーブルごとに読み取り 100 回／秒、書き込み 50 回／秒、平均行サイズ 1 KB、行数に基づく推定ストレージという妥当なデフォルト値で進め、3 戦略の比較をただちに提示してください。使用した前提条件を明記してください。
• SQL の JOIN を特定し、NoSQL でどのように対応するか（非正規化またはセカンダリルックアップ）を説明する必要があります。
• 各戦略について、パーティションキーとクラスタリングキーの設計判断とその理由を示した、Keyspaces 互換スキーマを提示する必要があります。
• スクリプト実行モデルに従う必要があります。コマンドを予告し、3 つの calculate.ts コマンド（戦略ごとに 1 つ）を表示してから、比較 JSON を提示してください。

この分析を自分で実行するコマンド（戦略ごとに 1 回、計 3 回実行）：

cd scripts
# Strategy 1: denormalized single table
npx ts-node --project tsconfig.scripts.json calculate.ts us-east-1 <r1> <w1> <b1> <gb1> 0 false | tee /tmp/keyspaces-s1.json
# Strategy 2: multiple targeted tables
npx ts-node --project tsconfig.scripts.json calculate.ts us-east-1 <r2> <w2> <b2> <gb2> 0 false | tee /tmp/keyspaces-s2.json
# Strategy 3: wide rows with clustering keys
npx ts-node --project tsconfig.scripts.json calculate.ts us-east-1 <r3> <w3> <b3> <gb3> 0 false | tee /tmp/keyspaces-s3.json

SQL → CQL のマッピングと比較表については mode-4-sql-migration.md を読み込んでください。

6. PDF レポートを生成する（任意）

制約：

• JSON を表示した後、PDF が必要かどうかをユーザーに確認する必要があります。
• 料金データを描画する材料がないため、モード 3 では PDF を生成してはなりません。

この処理を自分で実行するコマンド：

cd scripts && npx ts-node --project tsconfig.scripts.json generate-pdf.ts \
  --input /tmp/keyspaces-calc.json --output /tmp/keyspaces.pdf

複数の入力とラベルの構文については pdf-reporting.md を読み込んでください。

トラブルシューティング

接続エラー / NoNodeAvailableException / HeartbeatException / PerConnectionRequestExceeded

connection-troubleshooting.md を読み込んでください。application.conf の検証、エラー診断ツリー、接続プールのサイジング、ドライバー 3.x と 4.x の違いについて扱っています。ユーザーがドライバー設定を共有した場合は、そのリファレンスの §1 のすべての項目を確認し、すべての設定ミスを指摘してください。

スロットリング / WriteThrottleEvents / ReadThrottleEvents / キャパシティプランニング

pre-warming.md を読み込んでください。ウォームスループットの評価、事前ウォーミングの判断フレームワーク、サイジングの計算式、ホットパーティションとテーブルレベルのスロットリングの診断について扱っています。ユーザーがスロットリングを報告した場合、または今後のトラフィックイベントに向けたキャパシティについて質問した場合は、判断フレームワークを使用して、事前ウォーミング、自動スケーリング、パーティションキーの再設計、キャパシティモードの切り替えのどれが適切な修正方法かを判断してください。

Region not found: <region>

リージョンコードが間違っているか、そこでは Keyspaces が利用できません。assets/data/regions.json を確認してください。

parse-cassandra.ts が "Usage: …" で終了する

--tablestats または --info が不足しています。再取得するか、モード 1 を使用してください。

has_issues: false だがユーザーは検出結果を期待していた

keyspaces-unsupported-features.md に記載されている機能のみが指摘されます。ALLOW FILTERING、TRUNCATE、およびほとんどのデータ型はサポートされています。

診断情報を読み込む際のコンテキストオーバーフロー

大きな診断ファイルを file_read でコンテキストに読み込まないでください。代わりにディレクトリを parse-cassandra.ts --dir <path> に渡してください。

リモート診断情報の取得時にアクセスが拒否される

Cassandra の認証情報または SigV4 プラグインが不足しています。security-considerations.md を参照してください。

scripts/ で npm install が失敗する

Node < 18 または古い lockfile が原因です。scripts/node_modules/ と scripts/package-lock.json を削除し、再実行してください。

UNLOGGED BATCH 内の LWT はサポートされていません

UNLOGGED BATCH 内の LWT（IF NOT EXISTS、IF EXISTS、条件付き更新）は Amazon Keyspaces ではサポートされていません。LWT ステートメントは個別に（スタンドアロンで）実行する必要があります。LOGGED BATCH も Keyspaces ではサポートされていません。LWT ステートメントを 1 つずつ発行するようにリファクタリングするか、アトミックな複数行のセマンティクスが必要な場合はアプリケーションレベルでの調整を使用することを推奨します。

追加リソース

• Keyspaces デベロッパーガイド
• Cassandra との機能上の違い
• Keyspaces の料金
• CQL サポート
• Keyspaces の IAM
• references/ 内のリファレンスファイル: mode-1-manual-inputs、mode-2-cassandra-diagnostics、mode-3-compatibility、mode-4-sql-migration、pdf-reporting、keyspaces-unsupported-features、cassandra-capture-commands、security-considerations。

aws-database-selection からの引き継ぎ

このスキルは直接呼び出すことも、aws-database-selection 親スキルで要件の聞き取りを行い、requirements.json 成果物を作成した後に、そのスキルから移行することもできます。最近の会話に aws_dbs_requirements/*/requirements.json に一致するバッククォートで囲まれたパスがある場合は、aws-database-selection/references/handoff-contract.md のエントリープロトコルに従ってください。

1. file_read を使って成果物を読み取ります。
2. aws-database-selection/references/workload-primary-artifact.schema.json に照らして検証します。形式が不正、または読み取れない場合はユーザーに伝え、成果物なしで進めてください。
3. 関連する内容について、成果物の概要レベルの事実（支配的な形状、厳格な制約、移行の背景）を引用しながら、太字の文を1～2文で述べます。成果物全体をそのまま繰り返してはいけません。
4. スコープを確認します。このスキルの対象は、Amazon Keyspaces（Cassandra）のコスト見積もり、スキーマ互換性、SQL から Cassandra への変換です。成果物の workload_primaries.dominant_shapes または migration_context がこのスコープに合わない場合は、ハンドオフ契約に従って、Cassandra 互換性の要件がないキーアクセス型の NoSQL には dynamodb-skill を、支配的な形状がワイドカラムではない場合は aws-database-selection に戻るよう提案し、戻るかそのまま進めるかをユーザーに尋ねてください。成果物を黙って不適切に使用してはいけません。
5. このスキル本来のワークフローを進め、要件に基づく推奨事項では、根拠として成果物のパスを引用してください。

このスキルのユーザー向け出力はすべて、ハンドオフ契約の Markdown プリミティブのみを使用する書式規約に従います。ラベルには太字、パスや列挙値にはバッククォート、選択肢には箇条書きを使い、ASCII アートや罫線文字は使用しません。