infrastructure-code-synthesis

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AWS CDK Development

AWS CDK开发

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.

本技能为使用Cloud Development Kit（CDK）开发AWS基础设施提供全面指导，集成了MCP服务器以获取最新的AWS知识和CDK实用工具。

AWS Documentation Requirement

AWS文档要求

CRITICAL: This skill requires AWS MCP tools for accurate, up-to-date AWS information.

至关重要：本技能需要AWS MCP工具来获取准确、最新的AWS信息。

Before Answering AWS Questions

回答AWS问题之前

Always verify using AWS MCP tools (if available):

mcp__aws-mcp__aws___search_documentation

mcp__*awsdocs*__aws___search_documentation

- Search AWS docs

mcp__aws-mcp__aws___read_documentation

mcp__*awsdocs*__aws___read_documentation

- Read specific pages

mcp__aws-mcp__aws___get_regional_availability

- Check service availability

If AWS MCP tools are unavailable:
- Guide user to configure AWS MCP: See AWS MCP Setup Guide
- Help determine which option fits their environment:
  - Has uvx + AWS credentials → Full AWS MCP Server
  - No Python/credentials → AWS Documentation MCP (no auth)
- If cannot determine → Ask user which option to use

始终通过AWS MCP工具验证（如果可用）：

mcp__aws-mcp__aws___search_documentation

或

mcp__*awsdocs*__aws___search_documentation

- 搜索AWS文档

mcp__aws-mcp__aws___read_documentation

或

mcp__*awsdocs*__aws___read_documentation

- 阅读特定页面

mcp__aws-mcp__aws___get_regional_availability

- 检查服务可用性

如果AWS MCP工具不可用：
- 引导用户配置AWS MCP：查看AWS MCP设置指南
- 帮助确定哪种选项适合他们的环境：
  - 拥有uvx + AWS凭证 → 完整AWS MCP服务器
  - 无Python/凭证 → AWS文档MCP（无需认证）
- 如果无法确定 → 询问用户使用哪种选项

Integrated MCP Servers

集成的MCP服务器

This skill includes the CDK MCP server automatically configured with the plugin:

本技能包含自动配置了插件的CDK MCP服务器：

AWS CDK MCP Server

AWS CDK MCP服务器

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.

使用场景：获取CDK专属指导和实用工具

获取CDK构造推荐
检索CDK最佳实践
获取CDK模式建议
验证CDK配置
获取CDK专属API的帮助

重要提示：利用该服务器获取CDK构造指导和高级CDK操作支持。

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

在以下场景使用本技能：

创建新的CDK栈或构造
重构现有CDK基础设施
在CDK中实现Lambda函数
遵循AWS CDK最佳实践
部署前验证CDK栈配置
验证AWS服务能力和区域可用性

Core CDK Principles

核心CDK原则

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.

typescript

// ❌ 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.

至关重要：当CDK构造中资源名称为可选项时，请勿显式指定。

原因：CDK生成的名称支持：

可复用模式：无需冲突即可多次部署相同的构造/模式
并行部署：多个栈可在同一区域同时部署
更简洁的共享逻辑：模式和共享代码可多次初始化而无命名冲突
栈隔离：每个栈自动获得唯一标识的资源

模式：让CDK通过CloudFormation的命名机制自动生成唯一名称。

typescript

// ❌ 不良实践 - 显式命名会阻碍复用性和并行部署
new lambda.Function(this, 'MyFunction', {
  functionName: 'my-lambda',  // 避免这样做
  // ...
});

// ✅ 良好实践 - 让CDK生成唯一名称
new lambda.Function(this, 'MyFunction', {
  // 未指定functionName - CDK会生成：StackName-MyFunctionXXXXXX
  // ...
});

安全提示：针对不同环境（开发、预发布、生产），遵循AWS安全支柱最佳实践，使用独立的AWS账户，而非依赖单账户内的资源命名。账户级隔离能提供更强的安全边界。

Lambda Function Development

Lambda函数开发

Use the appropriate Lambda construct based on runtime:

TypeScript/JavaScript: Use

@aws-cdk/aws-lambda-nodejs

typescript

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

typescript

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

根据运行时使用合适的Lambda构造：

TypeScript/JavaScript：使用

@aws-cdk/aws-lambda-nodejs

typescript

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

new NodejsFunction(this, 'MyFunction', {
  entry: 'lambda/handler.ts',
  handler: 'handler',
  // 自动处理打包、依赖和转译
});

Python：使用

@aws-cdk/aws-lambda-python

typescript

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

new PythonFunction(this, 'MyFunction', {
  entry: 'lambda',
  index: 'handler.py',
  handler: 'handler',
  // 自动处理依赖和打包
});

优势:

自动打包和依赖管理
自动处理转译
无需手动打包
一致的部署模式

Pre-Deployment Validation

部署前验证

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

使用多层验证策略进行全面的CDK质量检查：

Layer 1: Real-Time IDE Feedback (Recommended)

第一层：实时IDE反馈（推荐）

For TypeScript/JavaScript projects:

Install cdk-nag for synthesis-time validation:

bash

npm install --save-dev cdk-nag

Add to your CDK app:

typescript

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 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.

针对TypeScript/JavaScript项目:

安装cdk-nag用于合成时验证：

bash

npm install --save-dev cdk-nag

添加到你的CDK应用中：

typescript

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

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

可选 - VS Code用户：安装CDK NAG Validator扩展，在保存文件时获得更快的反馈。

针对Python/Java/C#/Go项目：cdk-nag支持所有CDK语言，提供相同的合成时验证。

Layer 2: Synthesis-Time Validation (Required)

第二层：合成时验证（必需）

Synthesis with cdk-nag: Validate stack with comprehensive rules
bash
```
cdk synth  # cdk-nag runs automatically via Aspects
```

Suppress legitimate exceptions with documented reasons:

typescript

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'
  }
]);

使用cdk-nag合成：通过全面规则验证栈
bash
```
cdk synth  # cdk-nag通过Aspects自动运行
```

记录原因后合法抑制异常:

typescript

import { NagSuppressions } from 'cdk-nag';

// 记录为何需要该异常
NagSuppressions.addResourceSuppressions(resource, [
  {
    id: 'AwsSolutions-L1',
    reason: 'Lambda@Edge需要特定运行时以兼容CloudFront'
  }
]);

Layer 3: Pre-Commit Safety Net

第三层：提交前安全网

Build: Ensure compilation succeeds

bash

npm run build  # or language-specific build command

Tests: Run unit and integration tests
bash
```
npm test  # or pytest, mvn test, etc.
```
Validation Script: Meta-level checks
bash
```
./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 handled by cdk-nag)

构建：确保编译成功

bash

npm run build  # 或对应语言的构建命令

测试：运行单元和集成测试
bash
```
npm test  # 或pytest、mvn test等
```
验证脚本：元级检查
bash
```
./scripts/validate-stack.sh
```

验证脚本现在专注于：

语言检测
模板大小和资源数量分析
合成成功验证
（注意：详细的反模式检查由cdk-nag处理）

Workflow Guidelines

工作流指南

Development Workflow

开发工作流

Design: Plan infrastructure resources and relationships
Verify AWS Services: Use AWS Documentation MCP to confirm service availability and features
- Check regional availability for all required services
- Verify service limits and quotas
- Confirm latest API specifications
Implement: Write CDK constructs following best practices
- Use CDK MCP server for construct recommendations
- Reference CDK best practices via MCP tools
Validate: Run pre-deployment checks (see above)
Synthesize: Generate CloudFormation templates
Review: Examine synthesized templates for correctness
Deploy: Deploy to target environment
Verify: Confirm resources are created correctly

设计：规划基础设施资源和关系
验证AWS服务：使用AWS文档MCP确认服务可用性和功能
- 检查所有所需服务的区域可用性
- 验证服务限制和配额
- 确认最新的API规范
实现：遵循最佳实践编写CDK构造
- 使用CDK MCP服务器获取构造推荐
- 通过MCP工具参考CDK最佳实践
验证：运行部署前检查（见上文）
合成：生成CloudFormation模板
评审：检查合成模板的正确性
部署：部署到目标环境
验证：确认资源已正确创建

Stack Organization

栈组织

Use nested stacks for complex applications
Separate concerns into logical construct boundaries
Export values that other stacks may need
Use CDK context for environment-specific configuration

复杂应用使用嵌套栈
将关注点分离到逻辑构造边界
导出其他栈可能需要的值
使用CDK上下文处理环境特定配置

Testing Strategy

测试策略

Unit test individual constructs
Integration test stack synthesis
Snapshot test CloudFormation templates
Validate resource properties and relationships

对单个构造进行单元测试
对栈合成进行集成测试
对CloudFormation模板进行快照测试
验证资源属性和关系

Using MCP Servers Effectively

有效使用MCP服务器

When to Use AWS Documentation MCP

何时使用AWS文档MCP

Always verify before implementing:

New AWS service features or configurations
Service availability in target regions
API parameter specifications
Service limits and quotas
Security best practices for AWS services

Example scenarios:

"Check if Lambda supports Python 3.13 runtime"
"Verify DynamoDB is available in eu-south-2"
"What are the current Lambda timeout limits?"
"Get latest S3 encryption options"

实现前务必验证:

新的AWS服务功能或配置
目标区域的服务可用性
API参数规范
服务限制和配额
AWS服务的安全最佳实践

示例场景:

“检查Lambda是否支持Python 3.13运行时”
“验证DynamoDB是否在eu-south-2区域可用”
“当前Lambda的超时限制是多少？”
“获取最新的S3加密选项”

When to Use CDK MCP Server

何时使用CDK MCP服务器

Leverage for CDK-specific guidance:

CDK construct selection and usage
CDK API parameter options
CDK best practice patterns
Construct property configurations
CDK-specific optimizations

Example scenarios:

"What's the recommended CDK construct for API Gateway REST API?"
"How to configure NodejsFunction bundling options?"
"Best practices for CDK stack organization"
"CDK construct for DynamoDB with auto-scaling"

用于CDK专属指导:

CDK构造选择和使用
CDK API参数选项
CDK最佳实践模式
构造属性配置
CDK专属优化

示例场景:

“API Gateway REST API推荐使用哪种CDK构造？”
“如何配置NodejsFunction的打包选项？”
“CDK栈组织的最佳实践”
“带自动扩缩容的DynamoDB的CDK构造”

MCP Usage Best Practices

MCP使用最佳实践

Verify First: Always check AWS Documentation MCP before implementing new features
Regional Validation: Check service availability in target deployment regions
CDK Guidance: Use CDK MCP for construct-specific recommendations
Stay Current: MCP servers provide latest information beyond knowledge cutoff
Combine Sources: Use both skill patterns and MCP servers for comprehensive guidance

先验证：实现新功能前始终检查AWS文档MCP
区域验证：检查目标部署区域的服务可用性
CDK指导：使用CDK MCP获取构造专属推荐
保持最新：MCP服务器提供知识截止日期之后的最新信息
结合来源：结合技能模式和MCP服务器获取全面指导

CDK Patterns Reference

CDK模式参考

For detailed CDK patterns, anti-patterns, and architectural guidance, refer to the comprehensive reference:

File:

references/cdk-patterns.md

This reference includes:

Common CDK patterns and their use cases
Anti-patterns to avoid
Security best practices
Cost optimization strategies
Performance considerations

如需详细的CDK模式、反模式和架构指导，请参考综合参考文档：

文件:

references/cdk-patterns.md

该参考文档包含：

常见CDK模式及其使用场景
需要避免的反模式
安全最佳实践
成本优化策略
性能考量

Additional Resources

额外资源

Validation Script:
```
scripts/validate-stack.sh
```
- Pre-deployment validation
CDK Patterns:
```
references/cdk-patterns.md
```
- Detailed pattern library
AWS Documentation MCP: Integrated for latest AWS information
CDK MCP Server: Integrated for CDK-specific guidance

验证脚本:
```
scripts/validate-stack.sh
```
- 部署前验证
CDK模式:
```
references/cdk-patterns.md
```
- 详细的模式库
AWS文档MCP: 集成以获取最新AWS信息
CDK MCP服务器: 集成以获取CDK专属指导

GitHub Actions Integration

GitHub Actions集成

When GitHub Actions workflow files exist in the repository, ensure all checks defined in

.github/workflows/

pass before committing. This prevents CI/CD failures and maintains code quality standards.

当仓库中存在GitHub Actions工作流文件时，确保

.github/workflows/

中定义的所有检查在提交前通过。这可以防止CI/CD失败并维持代码质量标准。