AWS インフラストラクチャを CDK（クラウド開発キット。コードでインフラを構築するツール）を使って TypeScript または Python で作成・デプロイ（本番環境への配置）し、問題を解決します。ベストプラクティス（最適な実装方法）、スタック（インフラの単位）アーキテクチャ、コンストラクト（再利用可能な部品）パターンに対応しています。 次のような場合に使用: CDK コンストラクトを書く、環境のセットアップを行う、cdk deploy／synth／diff を実行する、CDK または CloudFormation（インフラ構築サービス）のエラーを修正する、スタック構造を計画する、既存のリソース（インフラの構成要素）を取り込む、ドリフト（設定のずれ）を解決する、リソース置き換えなしでスタックをリファクタリング（整理・改善）する場合。
Authors, deploys, and troubleshoots AWS infrastructure using CDK with TypeScript or Python. Covers best practices, stack architecture, and construct patterns. Always use when writing CDK constructs, bootstrapping environments, running cdk deploy/synth/diff, fixing CDK or CloudFormation errors, planning stack structure, importing existing resources, resolving drift, or refactoring stacks without resource replacement.
AWS CDK（構成コード定義ツール）を使った以下の領域の専門知識を提供します： 構成要素（コンポーネント）の開発、デプロイメント（展開）ワークフロー、コンプライアンス（規制対応）、ドリフト（設定のずれ）、既存リソースの取り込み、安全なコード改修、CDK CLI / CloudFormation エラーのトラブルシューティング。
使用しない場合: 生のCloudFormation YAML/JSON、SAM、Terraform/Pulumi、CDK Pipelines以外のCI/CD。これらについては標準機能または専用スキルを使用してください。
デプロイメントの膠着状態（クロススタック参照の削除）: クロススタック参照（スタック間での値参照）を削除するとデプロイが止まります（Export ... cannot be deleted as it is in use by ...というエラー）。推奨される修正方法：参照を段階的に弱くします — CrossStackReferences.of($RESOURCE).produce(ReferenceStrength.BOTH) → WEAK に変更 → 削除（3回のデプロイが必要）。従来の方法：this.exportValue() を使う2回デプロイ方式。詳細はデプロイメントのトラブルシューティングを参照。
構成要素IDの変更でリソースが置き換わる: 構成要素の名前や位置を変更するとCloudFormation上の論理IDが変わり、リソースが置き換わります（ステートフル（状態を保持する）リソースではデータ損失が発生）。デプロイ前に必ず cdk diff を実行してください。詳細は安全な改修と置き換え防止を参照。
UPDATE_ROLLBACK_FAILED: スタックが停止状態になります。cdk rollback $STACK または cdk rollback $STACK --orphan <LogicalId> で修正できます。詳細はデプロイメントのトラブルシューティングを参照。
削除後も残るS3バケット: 中身が入っているS3バケットは削除後も残ります。必ず removalPolicy: DESTROY と autoDeleteObjects: true の両方を設定してください。バージョン管理が有効なバケットはさらに厄介です — 削除済みマーカーが残ることがあります。
| タスク | コマンド | 詳細 |
|---|---|---|
| ブートストラップ（初期設定） | cdk bootstrap aws://$ACCOUNT/$REGION |
ブートストラップとプロジェクト設定 |
| TypeScript新規プロジェクト | cdk init app --language typescript — tsx、eslint-plugin-awscdk を使用 |
ブートストラップとプロジェクト設定 |
| Python新規プロジェクト | cdk init app --language python — 依存関係を固定、仮想環境を使用 |
ブートストラップとプロジェクト設定 |
| デプロイ | cdk synth --strict → cdk diff → cdk deploy |
本番環境へのデプロイ前に必ず diff で確認 |
| cdk-nag | Aspects.of(app).add(new AwsSolutionsChecks()) |
コンプライアンスと設定のずれ検出 |
| ドリフト（設定のずれ）検出 | cdk drift $STACK（CI内では --fail を使用） |
コンプライアンスと設定のずれ検出 |
| 既存リソースの取り込み | cdk import（対話型またはCI用に --resource-mapping を使用）、cdk deploy --import-existing-resources |
リソース取り込みと移行 |
| 安全な改修 | cdk refactor --unstable=refactor — 同じデプロイ内でプロパティを変更しない |
安全な改修と置き換え防止 |
| エラー | 原因と対処方法 |
|---|---|
| DeployFailed / DeploymentError | CDKのエラーが根本原因ではない可能性があります。cdk deploy $STACK --verbose を実行し、次に cdk --unstable=diagnose diagnose $STACK（CLI ≥ 2.1120.0）を実行します。それ以外の場合は aws cloudformation describe-events --stack-name $STACK --filters FailedEvents=true で、最初の _FAILED イベントが原因です。詳細 |
| NoCredentials / ExpiredToken / AssumeRoleFailed | aws sts get-caller-identity と cdk doctor で確認。SSO期限切れ、env 設定漏れ、sts:AssumeRole 権限漏れなど。詳細 |
| アセット（リソースファイル）エラー （CannotFindAsset、FailedToBundleAsset、AssetBuildFailed、AssetPublishFailed） | ファイルパスが間違っている、Dockerが起動していない、またはブートストラップバケットの権限不足。path.join(__dirname, ...) を使用してください。詳細 |
| AppRequired | cdk.json に "app": "npx tsx bin/my-app.ts" を追加してください。詳細 |
| AnnotationErrors | 根本的な問題を修正してください。抑制は NagSuppressions で最後の手段としてのみ使用。詳細 |
| ConcurrentReadLock / ConcurrentWriteLock | rm -rf cdk.out を実行してから再度実行。並列CI環境では --output ./cdk.out.$BUILD_ID を使用。詳細 |
| BootstrapVersionValidation | ブートストラップをやり直してください。すべての場所で --qualifier を一致させてください。詳細 |
| DependencyCycle | 共有リソースを第3のスタックに抽出するか、SSMパラメータストア（後処理のための値保存）を使用。詳細 |
| UnresolvedAccount | スタックに明示的に env: { account, region } を設定。cdk.context.json をコミット。詳細 |
| NoStacksMatched | CDKは CloudFormation の名前ではなく論理ID（コンストラクタの第2引数）を使用。cdk list でIDを確認。詳細 |
| Cannot find module（合成時） | npx tsc --noEmit を実行、cdk.json のアプリパスが tsconfig.json の outDir と一致することを確認、古い .js ファイルを削除。Python：仮想環境を有効化。詳細 |
| V1のインポートパス / 重複した aws-cdk-lib | V1形式の @aws-cdk/* インポート、誤った Construct インポート、モノレポ内での重複したライブラリ。詳細 |
| Lambda Cannot find module（実行時） | ハンドラー値が間違っている、SDK v3への移行漏れ、Pythonの依存パッケージがバンドルされていない。詳細 |
| API Gateway マルチステージ（段階）の競合 | RestApi に deploy: false を設定、Deployment と Stage を明示的に作成。詳細 |
L2（より高レベルな抽象化）を優先してください。L2に必要なプロパティがない場合は、Mixins/Facades（設計パターン）を使ったL1（低レベル）を使用。回避策：node.defaultChild → addPropertyOverride。詳細は構成要素のパターンを参照。
--custom-permissions-boundary で権限制限grant*() メソッドを使用cdk-nag と --strict を実行terminationProtection: true で保護cdk.context.json をコミットDomain expertise for CDK construct authoring, deployment workflows, compliance, drift, importing resources, safe refactoring, and troubleshooting CDK CLI / CloudFormation errors.
When NOT to use: Raw CloudFormation YAML/JSON. SAM. Terraform/Pulumi. CI/CD beyond CDK Pipelines. Use builtin knowledge or specialized skills for these.
Deadly embrace: Removing a cross-stack reference deadlocks deployment (Export ... cannot be deleted as it is in use by ...). Preferred fix: weaken the reference first — CrossStackReferences.of($RESOURCE).produce(ReferenceStrength.BOTH) then WEAK, then remove (three deploys). Legacy fallback: two-deploy this.exportValue() recipe. See troubleshooting-deployment.
Construct ID changes cause replacement: Renaming/moving a construct changes its logical ID → CloudFormation replaces the resource (data loss for stateful resources). Always cdk diff before deploy. See refactor-and-prevent-replacement.
UPDATE_ROLLBACK_FAILED: Stack is stuck. Fix with cdk rollback $STACK or cdk rollback $STACK --orphan <LogicalId>. See troubleshooting-deployment.
Non-empty S3 buckets persist after destroy: You MUST set both removalPolicy: DESTROY and autoDeleteObjects: true. Versioned buckets are worse — delete markers persist even after apparent deletion.
| Task | Quick Command | Details |
|---|---|---|
| Bootstrap | cdk bootstrap aws://$ACCOUNT/$REGION |
bootstrap-and-project-setup |
| New TS project | cdk init app --language typescript — use tsx, eslint-plugin-awscdk |
bootstrap-and-project-setup |
| New Python project | cdk init app --language python — pin deps, use virtualenv |
bootstrap-and-project-setup |
| Deploy | cdk synth --strict → cdk diff → cdk deploy |
Always diff before deploy to prod |
| cdk-nag | Aspects.of(app).add(new AwsSolutionsChecks()) |
compliance-and-drift |
| Drift | cdk drift $STACK (use --fail in CI) |
compliance-and-drift |
| Import resource | cdk import (interactive or --resource-mapping for CI), cdk deploy --import-existing-resources |
import-and-migrate |
| Refactor safely | cdk refactor --unstable=refactor — no property changes in same deploy |
refactor-and-prevent-replacement |
| Error | Cause → Fix |
|---|---|
| DeployFailed / DeploymentError | CDK error isn't the root cause. cdk deploy $STACK --verbose, then cdk --unstable=diagnose diagnose $STACK (CLI ≥ 2.1120.0); else aws cloudformation describe-events --stack-name $STACK --filters FailedEvents=true — the first _FAILED event is the cause. Details |
| NoCredentials / ExpiredToken / AssumeRoleFailed | aws sts get-caller-identity + cdk doctor. Expired SSO, missing env, missing sts:AssumeRole. Details |
| Asset errors (CannotFindAsset, FailedToBundleAsset, AssetBuildFailed, AssetPublishFailed) | Path wrong, Docker not running, or bootstrap bucket perms. Use path.join(__dirname, ...). Details |
| AppRequired | Add "app": "npx tsx bin/my-app.ts" to cdk.json. Details |
| AnnotationErrors | Fix the underlying issue; suppress with NagSuppressions only as last resort. Details |
| ConcurrentReadLock / ConcurrentWriteLock | rm -rf cdk.out then re-run. Parallel CI: --output ./cdk.out.$BUILD_ID. Details |
| BootstrapVersionValidation | Re-bootstrap. Match --qualifier everywhere. Details |
| DependencyCycle | Extract shared resource into third stack or use SSM for late-binding. Details |
| UnresolvedAccount | Set explicit env: { account, region } on stack. Commit cdk.context.json. Details |
| NoStacksMatched | CDK uses logical ID (2nd constructor arg), not CFN name. cdk list to find IDs. Details |
| Cannot find module (synth time) | Run npx tsc --noEmit, check cdk.json app path matches tsconfig.json outDir, delete stale .js files. Python: activate venv. Details |
| V1 import paths / duplicate aws-cdk-lib | V1 @aws-cdk/* imports, wrong Construct import, duplicate lib copies in monorepos. Details |
| Lambda Cannot find module (runtime) | Wrong handler value, missing SDK v3 migration, Python deps not bundled. Details |
| API Gateway multi-stage conflicts | Set deploy: false on RestApi, create Deployment and Stage explicitly. Details |
Prefer L2. Use L1 with Mixins/Facades when L2 lacks a property. Escape hatches: node.defaultChild → addPropertyOverride. See construct-patterns.
--custom-permissions-boundary on bootstrapgrant*() for inter-resource IAMcdk-nag + --strict in CIterminationProtection: truecdk.context.json原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。