aws-sst-development

AWS 向け SST v4

SST v4（「Ion」エンジン）は、Pulumi を基盤とする IaC フレームワークです。TypeScript で AWS リソースを記述すると、SST/Pulumi がアカウント内の状態を調整します。高水準の sst.aws.* コンポーネント（Function、Bucket、Dynamo、Cron、Service など）を利用でき、これらは多数の基盤リソースに展開されます。また、対象範囲が広い要件に対応するため、任意の生の Pulumi aws.* リソースを利用する手段もあります。このスキルには、AWS 上の SST スタックを作成、リンク、テスト、デプロイ、トラブルシューティングする、実運用で実証済みの方法がまとめられています。実際の複数スタックプロジェクトで、本番インシデントを通じて得られた教訓に基づいています。

SST と Pulumi はサードパーティ製です。不明なコンポーネントのオプションがある場合は、Context7（resolve-library-id → query-docs で sst または pulumi-aws を検索）を使って、現在の構文を確認してください。 AWS 側の情報（サービスの制限、モデル ID、IAM アクション名、リージョンでの提供状況）は、記憶に頼らず、AWS ドキュメント MCP で確認してください。ここに記載されているのは「方法」であり、ドキュメントに記載されているのは「内容」です。

呼び出されたとき

状況に応じてモードを判断し、該当するリファレンスに進んでください。

状況	参照先
新しいプロジェクト、または既存の SST アプリへのリソース／モジュールの追加	作成 → references/authoring.md
あるモジュールの出力を別のモジュールに接続する（リンク、SSM、IAM のスコープ設定）	作成 → references/authoring.md § 共有
変更によるインフラの予期しない破損を防ぐためのテスト作成	テスト → references/testing.md
デプロイの実行、またはデプロイ失敗への対応	デプロイ／運用 → references/deploy-and-troubleshoot.md
Pulumi の型間でのリソース移行、物理名の変更	デプロイ／運用 → references/deploy-and-troubleshoot.md § 移行

編集を始める前に、必ず該当するリファレンスを読んでください。各ルールの背景にある「理由」が記載されており、これはルールそのものよりも重要です。

事前確認：変更を加える前にリポジトリを読む

SST プロジェクトには一般的な慣習がありますが、すべてが同じというわけではありません。編集前に簡単な全体像を把握し、プロジェクト固有のスタイルに合わせて変更してください。

1. sst.config.ts — アプリ名、home、プロバイダー／リージョン、defaultTags、グローバルな $transform（Node ランタイムの固定、バンドルの調整）、および run() が infra/ モジュールを読み込む順序。読み込み順は依存関係の順序でもあるため、これに従ってください。
2. infra/ — ドメインごとに 1 つのファイル（ストレージ、関数、API、可観測性など）。ここでリソースを宣言します。infra/CLAUDE.md があるか確認してください。これらのプロジェクトでは IaC 固有のルールが記載されており、最初に読む価値が最も高いファイルです。
3. infra/tests/ — リソースの不変条件を固定する、ソースレベルの Vitest アサーションです。存在する場合は、変更後もテストをすべて通し、新しいアサーションも追加する必要がある可能性があります。
4. package.json / .nvmrc — パッケージマネージャー（npm と pnpm のどちらか）、Node のバージョン、実際にインストールされている sst／pulumi のバージョン。

npx sst version を実行して、v4/Ion（$config と .sst/platform/ がある構成）を使用していることを確認してください。v2/v3（「SST Classic」、CDK ベース）は別のフレームワークであり、ここにある方法は適用できません。

規約と、普遍的なもの／調整可能なもの

このスキルの基になったプロジェクトには、意図的に統一されたスタイルがあります。その一部は普遍的（あらゆる SST v4 + AWS プロジェクトに当てはまるため、どこでも適用してください）で、残りはプロジェクト固有（これらのプロジェクトが選んだ妥当な既定値であり、一貫性のために採用しつつ、プロジェクトによって異なる場合がある点に留意してください）です。

普遍的 — あらゆる SST v4 + AWS プロジェクトに当てはまる原則：

• Node ランタイムは意図的に一か所で制御します。 インストールされている SST のデフォルト任せにしないでください。イディオムは、run() 内の単一のグローバルな $transform(sst.aws.Function, (args) => { args.runtime ??= "nodejs24.x" }) です。??= が適切なのは、コンポーネントが独自のデフォルトを適用する前に変換が実行され、ユーザーが設定していない場合にのみ値を補うためです。最近の SST はすでに現行の Node ランタイムをデフォルトにしているので、まずインストール済みのデフォルトを確認してください（Context7）。この変換は、将来 SST をダウングレードしても、フリートのランタイムが気付かないうちに変更されないようにするバージョン非依存の保険です。references/authoring.md を参照してください。
• Pulumi の Output<T> を通常の JS テンプレートリテラルに埋め込まないでください。 $interpolate（または pulumi.interpolate）を使ってください。トップレベルで単独の `${bucket.arn}/*` を使うと、Output が [Output<T>] というプレースホルダーに文字列化され、壊れた ARN が生成されます。これはデプロイ時にしか失敗しません（型チェックは通り、sst dev も問題なく実行できます）。修正方法は $interpolate​`${bucket.arn}/*` です。これが原因で本番デプロイの障害が発生したことがあります。references/authoring.md の § Outputs を参照してください。
• Pulumi の型間でリソースを移行する場合は、原則として 2 つの PR に分けてください — Pulumi は作成してから削除するため、一意性が必要な AWS 名（バケット、IAM ロール、ゲートウェイ）では、古いリソースが引き続きその名前を使用しており、作成が ConflictException で失敗します。2 回に分けて順番にデプロイ（削除してから再作成）するのが保守的なデフォルトです。場合によっては aliases: / pulumi import / 状態の直接操作で ID を引き継げますが、レビュー済みのプランがある場合に限ります。references/deploy-and-troubleshoot.md の § Migrations を参照してください。
• aws.cloudcontrol.Resource という代替手段より、型付けされた sst.aws.* / aws.* リソースを優先してください。 CloudControl の出力は文字列型であり、oneOf フィールドは適切にパッチできません。型付けされたリソースがまだ存在しない場合に限って使用し、提供されたらそちらへ移行してください。

プロジェクト固有のデフォルト — 一貫性のために採用しますが、リポジトリごとに確認してください。

• リージョンは ap-northeast-1、home: "aws" とし、Project / Stage / ManagedBy: "sst" を含む defaultTags を設定します。
• ステージに応じたライフサイクル：removal: stage === "prod" ? "retain" : "remove" および protect: stage === "prod" とし、本番リソースはスタックの削除後も保持され、非本番のプレビューではクリーンアップされるようにします。
• グラフ外との連携には、SSM Parameter Store を契約として使用します。Pulumi グラフに含まれない利用者（CI スクリプト、兄弟アプリ、運用担当者）が対象です。同じアプリ内の Lambda では SST の link: を優先してください（実際の依存関係エッジを作り、IAM 権限を付与します）。同じアプリ内の共有に SSM を経由させないでください。references/authoring.md の § Sharing を参照してください。
• run() 内で遅延的に await import("./infra/<module>") を行い、sst dev のホットリロードを軽快に保ちます。（テストでは、モジュールのエクスポートもファクトリー関数内にラップされていない限り、トップレベルの new sst.aws.* を実行します。インフラをテストする方法については references/testing.md を参照してください。）
• すべてのインフラモジュールにソースレベルの Vitest テストを用意します — 軽量なプロジェクト標準の回帰検出網として、ソーステキスト（リソース名、インデックスの形状、IAM のスコープ）を検証します。これは意図的な選択であり、SST の制限ではありません。モジュールに実際のロジックがある場合、Pulumi は動作グラフテスト用のランタイムモック（@pulumi/pulumi/runtime）をサポートしています。ソースのアサーションは、プレビューデプロイとスモークテストの代わりにはなりません。references/testing.md を参照してください。
• オブザーバビリティのゲートを設けます：新しい Lambda／キュー／スケジュールにはすべて、マージ前にアラームと構造化ログを用意します。これを必須にするかどうかはプロジェクトによりますが、低コストの保険になります。references/deploy-and-troubleshoot.md の § Observability を参照してください。

規約を導入するときは、それが「普遍的なもの」なのか「このリポジトリの標準スタイルに合わせたもの」なのかを明示し、ユーザーがプロジェクト固有のものを意図的に変更できるようにしてください。

作業の進め方

1. 全体を把握する（上記）— 設定、モジュール、テスト、ツールを確認します。
2. 不明点があれば Context7 / AWS docs MCP で構文を確認します。 コンポーネントのオプション名を推測してはいけません。
3. references/authoring.md に従ってリソース／モジュールを作成します。周囲のファイルに合わせて、コメントの量や命名をそろえます。これらのプロジェクトでは「なぜそうするのか」を詳しくコメントしているため、コメントが多いファイルに簡潔な一行コメントだけを書くと、品質が後退したように見えます。
4. テスト — ソースレベルのアサーション（references/testing.md）を追加または更新し、npx vitest（またはリポジトリの test スクリプト）を実行します。デプロイ前に npx sst diff および／または tsc --noEmit を実行し、型やプランのエラーを検出します。
5. references/deploy-and-troubleshoot.md に従ってデプロイ／運用します。sst deploy の前に aws sts get-caller-identity を実行し、対象アカウントを確認します。
6. エクスポートされた状態ファイルはクリーンアップします。これらのファイルにはアカウント ID と ARN が含まれており、/tmp やチャット履歴に残してはいけません。

適切な変更の条件

• 要件を満たす最小限の差分であり、適切な infra/ モジュールに追加され、依存関係の順序に従って run() に組み込まれていること。
• グローバル変換を通じて、すべての Lambda に適切なランタイムが設定されていること（Python 関数など、意図的に異なる設定にする場合を除き、runtime を手動で設定していないこと）。
• リソース間の参照には link:（グラフ内）および／または $interpolate スコープの IAM を使用し、他のツールが利用する出力はステージのプレフィックス配下の SSM に公開していること。
• 新しいインフラには対応するソースレベルのテストがあり、既存のテストスイートが引き続き成功すること。
• AWS 側の事実は docs MCP で、SST / Pulumi の構文は Context7 で確認し、記憶に頼っていないこと。
• デプロイ、sst remove、リソースタイプの移行など、取り消せない操作は、対象アカウントとともにユーザーに事前に伝えていること。また、移行は 1 つではなく 2 つの PR に分けて計画していること。