Cursor Rules Template: AWS CDK v2 TypeScript Infrastructure

Overview

This Cursor rules configuration is a Cursor Rules Template for AWS CDK v2 in TypeScript. It defines safe IAAC (infrastructure as code) patterns, enforceable conventions, and guardrails that Guide Cursor AI in generating, validating, and refactoring CDK stacks. It targets AWS CDK v2 with TypeScript and covers common infra concerns such as networking, IAM, storage, and deployment pipelines.

When to Use These Cursor Rules

• When initiating a new AWS CDK v2 TypeScript infrastructure project.
• When enforcing least-privilege IAM and secureStack patterns across constructs.
• When generating CDK constructs and stacks via Cursor AI to ensure consistency.
• When validating architecture, directory layout, and CI/CD integration for CDK synth/deploy.

Copyable .cursorrules Configuration

// Cursor Rules for AWS CDK v2 TypeScript Infrastructure
framework: 'aws-cdk-v2'
language: 'typescript'
stack: 'infra'
workspaceRoot: './infra'

roleContext: 'You are a cloud infrastructure engineer using AWS CDK v2 with TypeScript. You design secure, scalable, and reusable stacks. You ensure idempotent provisioning and follow CDK best practices.'

codeStyle:
  prettier: '2-space'
  eslint: 'recommended'
  tsconfig: 'strict'

architecture:
  directoryTree:
    - bin/
    - lib/
    - constructs/
    - test/
    - cdk.json

stackPatterns:
  stackPerFile: true
  exportConstructs: true

authSecurity:
  - 'No hard-coded secrets; use AWS Secrets Manager or SSM Parameter Store'
  - 'Always grant least privilege; avoid wildcard actions'
  - 'Prefer managed policies vs inline policies when possible'

database:
  dynamodb:
    enabled: true
    tableName: 'AppData'
    partitionKey: 'pk'
    sortKey: 'sk'
    readCapacity: 5
    writeCapacity: 5
  ormUsage: 'No ORM usage in CDK code; use AWS SDK or application layer outside CDK'

testing:
  unit: 'jest + ts-jest'
  integration: 'cdk synth, cdk diff, stack validation in CI'
  linting: 'eslint + prettier'

antiPatterns:
  - 'Hard-coded AWS credentials or secrets in code'
  - 'Inline policies with * permissions'
  - 'Mutating stacks during synthesis or deployment in ad-hoc ways'
  - 'Mutual dependencies across stacks without explicit interfaces'

notes:
  - 'Cursor AI will generate code snippets for CDK constructs; validate in CI'
  - 'Ensure constructs are exported, typed, and well-documented'

Recommended Project Structure

infra/
  bin/
    infra.ts
  lib/
    stacks/
      networking-stack.ts
      compute-stack.ts
    constructs/
      vpc-construct.ts
      ecs-construct.ts
      rds-construct.ts
  test/
    unit/
      networking-stack.test.ts
      compute-stack.test.ts
  cdk.json
  package.json
  tsconfig.json

Core Engineering Principles

• Idempotent, deterministic CDK synth with clear, typed interfaces.
• Least privilege IAM and secure secret handling (Secrets Manager, Parameter Store).
• Modular constructs with single-responsibility stacks and clear boundaries.
• Clear directory structure and documentation for maintainability.
• Automated testing; linting and formatting enforced in CI.

Code Construction Rules

• Use a dedicated lib/stacks directory with one stack per file and explicit exports.
• Define reusable constructs in lib/constructs and compose in stacks.
• Use TypeScript types for all CDK props; avoid any for stack inputs.
• Prefer existing CDK v2 patterns for networking (VPC, subnets) and security (KMS, Security Groups).
• Use environment-agnostic stacks; parameterize region/account through CDK contexts or environments.
• Document resource naming conventions and avoid hard-coded names; use StackName suffixes.

Security and Production Rules

• Grant least privilege; avoid wildcard actions in IAM policies.
• Do not embed secrets in code; fetch at runtime from Secrets Manager or Parameter Store.
• Enable drift detection and automated CI checks; require CDK synth and diff checks before deploy.
• Use secure networking patterns (VPC with private subnets, NAT gateways, and proper SG rules).
• Audit and rotate credentials; avoid hard-coded credentials or access keys in repo.

Testing Checklist

• Unit tests for utility Constructs (jest + ts-jest).
• Integration tests via CDK synth and diff in CI; ensure stacks render as expected.
• Linting with ESLint and Prettier; enforce formatting and rules.
• Guardrails to prevent unsafe patterns (no inline policies, no wildcard principals).

Common Mistakes to Avoid

• Embedding secrets or credentials directly in CDK code.
• Using wildcard permissions in IAM roles for long-lived stacks.
• Overlapping constructs without clear interfaces or versioned contracts.
• Skipping synth/diff checks in CI and deploying uncontrolled changes.

FAQ

What is included in the Copyable .cursorrules Configuration for AWS CDK v2 TypeScript?

The block contains Framework Role & Context, Code Style, Architecture & Directory Rules, Authentication & Security, Database patterns, Testing & Linting, and Prohibited Actions tailored to AWS CDK v2 with TypeScript.

How do I integrate this Cursor Rules Template into my project?

Copy the block into the project root as .cursorrules. Cursor AI then guides code generation within the constraints defined here. Ensure the tooling reads the file at project root so synth and lint workflows honor the rules.

Does this template enforce security best practices?

Yes. It emphasizes least-privilege IAM, Secrets Manager usage, and avoiding hard-coded credentials, with guardrails to prevent unsafe CDK patterns.

Can I adapt this for other stacks or regions?

Yes. The Template is stack-specific by default but can be extended for other stacks by updating the stack_name, directories, and resource patterns while preserving core Cursor rules.

What testing workflows are recommended?

Use Jest for unit tests, ts-jest for TypeScript, and CDK diff/synth checks in CI for integration validation and deployment gating.