AgentSkillsCN

mastering-aws-cdk

提供基于 TypeScript 的 AWS CDK v2 基础设施即代码开发指南，涵盖模式设计、故障排除与部署流程。适用于创建或重构 CDK 堆栈、调试 CloudFormation 或 CDK 部署错误、通过 GitHub Actions OIDC 配置 CI/CD，或集成 AWS 服务（Lambda、API Gateway、ECS/Fargate、S3、DynamoDB、EventBridge、Aurora、MSK）时使用。

SKILL.md
--- frontmatter
name: mastering-aws-cdk
description: Guides AWS CDK v2 infrastructure-as-code development in TypeScript with patterns, troubleshooting, and deployment workflows. Use when creating or refactoring CDK stacks, debugging CloudFormation or CDK deploy errors, setting up CI/CD with GitHub Actions OIDC, or integrating AWS services (Lambda, API Gateway, ECS/Fargate, S3, DynamoDB, EventBridge, Aurora, MSK).

Mastering AWS CDK v2 (TypeScript)

Focused guidance for building, deploying, and troubleshooting AWS CDK v2 infrastructure in TypeScript.

Contents

Use This Skill When

  • •Building new CDK apps or stacks in TypeScript
  • •Refactoring or splitting stacks to manage limits
  • •Debugging synth/diff/deploy failures or CloudFormation rollbacks
  • •Importing existing resources into CDK management
  • •Driving stacks from JSON/YAML configuration files
  • •Setting up GitHub Actions OIDC deployments
  • •Implementing service patterns across AWS managed services
  • •Writing CDK tests and running security checks

Trigger Terms

Use for queries mentioning: cdk, cdk deploy, cdk diff, cdk synth, cdk import, cdk watch, cdk refactor, cdk bootstrap, cdk-nag, hotswap, CloudFormation, stack rollback, cdk.context.json, cdk.json, SSM Parameter Store, hnb659fds, or OIDC GitHub Actions.

Quick Start

  1. •Confirm target account, region, and environment (dev/stage/prod).
  2. •Run cdk synth then cdk diff to validate changes.
  3. •Deploy with cdk deploy --require-approval=never in CI.

Workflow

1) Intake

Collect:

  • •account and region
  • •environment name and stage
  • •target services and integrations
  • •existing resources to import or avoid replacement

2) Stack Design

  • •Keep stacks under 500 resources (split or use nested stacks)
  • •Pass outputs via props or explicit exports
  • •Set removal policies for stateful resources (retain by default)

3) Implement

  • •Prefer L2 constructs; use L1 only for gaps
  • •Apply least-privilege IAM grants
  • •Keep resource names deterministic

4) Validate

  • •cdk synth to inspect the template
  • •cdk diff to review changes
  • •cdk doctor for environment issues

5) Deploy

  • •Ensure bootstrap completed for the account/region
  • •Review CloudFormation events on failure
  • •Use --require-approval=never only for CI

6) Observability

  • •Add log retention, alarms, and dashboards early
  • •Use X-Ray where distributed tracing matters
  • •See observability.md

Reference Map

TaskReference
Troubleshooting errorstroubleshooting.md
CI/CD with GitHub Actionscicd-github.md
Service-specific patternsservices.md
Observability setupobservability.md
Architecture and operationsarchitecture-ops.md
Testing and securitytesting-security.md
Latest featureslatest-features.md

Guardrails

  • •Do not modify CloudFormation-managed resources in the console
  • •Avoid dynamic values (Date.now, random) in resource definitions
  • •Use env: { account, region } for lookups (VPC/AZ/AMI)
  • •Use stable IDs when generating constructs from config data
  • •Use cdk import (adopt) for existing resources; use fromXxx only for read-only references
  • •Do not use hotswap in production pipelines

Debugging Checklist

Copy and track progress:

code
Debugging Progress:
- [ ] Check CloudFormation events (Console -> Stack -> Events)
- [ ] Re-run with verbose output: `cdk deploy --progress events`
- [ ] Inspect template: `cdk synth > template.yaml`
- [ ] Run diff: `cdk diff`
- [ ] Check service logs (Lambda: CloudWatch, ECS: task events)
- [ ] Run `cdk doctor`

When Not to Use

  • •Terraform/Pulumi or raw CloudFormation templates
  • •Manual console-driven resource management
  • •CDK in Python/Java/Go/C# (TypeScript only)

Reference Files