/aws-cdk-development

name: aws-cdk-development
description: AWS Cloud Development Kit (CDK) expert for building cloud infrastructure with TypeScript/Python. Use when creating CDK stacks, defining CDK constructs, implementing infrastructure as code, or when the user mentions CDK, CloudFormation, IaC, cdk synth, cdk deploy, or wants to define AWS infrastructure programmatically. Covers CDK app structure, construct patterns, stack composition, and deployment workflows.

AWS CDK Development

This skill provides comprehensive guidance for developing AWS infrastructure using the Cloud Development Kit (CDK), with integrated MCP servers for accessing latest AWS knowledge and CDK utilities.

Integrated MCP Servers

This skill includes two MCP servers automatically configured with the plugin:

AWS Documentation MCP Server

**When to use**: Always verify AWS service information before implementation

• Search AWS documentation for latest features and best practices
• Check regional availability of AWS services
• Verify service limits and quotas
• Confirm API specifications and parameters
• Access up-to-date AWS service information

**Critical**: Use this server whenever AWS service features, configurations, or availability need verification.

AWS CDK MCP Server

**When to use**: For CDK-specific guidance and utilities

• Get CDK construct recommendations
• Retrieve CDK best practices
• Access CDK pattern suggestions
• Validate CDK configurations
• Get help with CDK-specific APIs

**Important**: Leverage this server for CDK construct guidance and advanced CDK operations.

When to Use This Skill

Use this skill when:

• Creating new CDK stacks or constructs
• Refactoring existing CDK infrastructure
• Implementing Lambda functions within CDK
• Following AWS CDK best practices
• Validating CDK stack configurations before deployment
• Verifying AWS service capabilities and regional availability

Core CDK Principles

Resource Naming

**CRITICAL**: Do NOT explicitly specify resource names when they are optional in CDK constructs.

**Why**: CDK-generated names enable:

• **Reusable patterns**: Deploy the same construct/pattern multiple times without conflicts
• **Parallel deployments**: Multiple stacks can deploy simultaneously in the same region
• **Cleaner shared logic**: Patterns and shared code can be initialized multiple times without name collision
• **Stack isolation**: Each stack gets uniquely identified resources automatically

**Pattern**: Let CDK generate unique names automatically using CloudFormation's naming mechanism.

// ❌ BAD - Explicit naming prevents reusability and parallel deployments
new lambda.Function(this, 'MyFunction', {
  functionName: 'my-lambda',  // Avoid this
  // ...
});

// ✅ GOOD - Let CDK generate unique names
new lambda.Function(this, 'MyFunction', {
  // No functionName specified - CDK generates: StackName-MyFunctionXXXXXX
  // ...
});

**Security Note**: For different environments (dev, staging, prod), follow AWS Security Pillar best practices by using separate AWS accounts rather than relying on resource naming within a single account. Account-level isolation provides stronger security boundaries.

Lambda Function Development

Use the appropriate Lambda construct based on runtime:

**TypeScript/JavaScript**: Use `@aws-cdk/aws-lambda-nodejs`

import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';

new NodejsFunction(this, 'MyFunction', {
  entry: 'lambda/handler.ts',
  handler: 'handler',
  // Automatically handles bundling, dependencies, and transpilation
});

**Python**: Use `@aws-cdk/aws-lambda-python`

import { PythonFunction } from '@aws-cdk/aws-lambda-python-alpha';

new PythonFunction(this, 'MyFunction', {
  entry: 'lambda',
  index: 'handler.py',
  handler: 'handler',
  // Automatically handles dependencies and packaging
});

**Benefits**:

• Automatic bundling and dependency management
• Transpilation handled automatically
• No manual packaging required
• Consistent deployment patterns

Pre-Deployment Validation

Use a **multi-layer validation strategy** for comprehensive CDK quality checks:

Layer 1: Real-Time IDE Feedback (Recommended)

**For TypeScript/JavaScript projects**:

Install [cdk-nag](https://github.com/cdklabs/cdk-nag) for synthesis-time validation:

npm install --save-dev cdk-nag

Add to your CDK app:

import { Aspects } from 'aws-cdk-lib';
import { AwsSolutionsChecks } from 'cdk-nag';

const app = new App();
Aspects.of(app).add(new AwsSolutionsChecks());

**Optional - VS Code users**: Install [CDK NAG Validator extension](https://marketplace.visualstudio.com/items?itemName=alphacrack.cdk-nag-validator) for faster feedback on file save.

**For Python/Java/C#/Go projects**: cdk-nag is available in all CDK languages and provides the same synthesis-time validation.

Layer 2: Synthesis-Time Validation (Required)

1. **Synthesis with cdk-nag**: Validate stack with comprehensive rules

   cdk synth  # cdk-nag runs automatically via Aspects

2. **Suppress legitimate exceptions** with documented reasons:

   import { NagSuppressions } from 'cdk-nag';

   // Document WHY the exception is needed
   NagSuppressions.addResourceSuppressions(resource, [
     {
       id: 'AwsSolutions-L1',
       reason: 'Lambda@Edge requires specific runtime for CloudFront compatibility'
     }
   ]);

Layer 3: Pre-Commit Safety Net

1. **Build**: Ensure compilation succeeds

   npm run build  # or language-specific build command

2. **Tests**: Run unit and integration tests

   npm test  # or pytest, mvn test, etc.

3. **Validation Script**: Meta-level checks

   ./scripts/validate-stack.sh

The validation script now focuses on:

• Language detection
• Template size and resource count analysis
• Synthesis success verification
• (Note: Detailed anti-pattern checks are handle