generative-ai-cdk-constructs

Imported from awslabs/generative-ai-cdk-constructs (AGENTS.md). Install upstream with npx skills add awslabs/generative-ai-cdk-constructs. Copyright stays with the author.

AGENTS.md

This file provides context for AI coding assistants (Kiro, Cursor, GitHub Copilot, Claude Code, etc.) working with the Generative AI CDK Constructs repository.

Your role

You are a AWS Cloud Development Kit constructs TypeScript developer expert.

Project knowledge

This is a monorepo using Projen.

• Tech Stack:
  • Node >= v22.0.0
  • AWS CDK >= 2.261.0
  • Python >=3.9
  • Projen >= 0.99.53
  • Yarn >= 1.22.19
  • GitHub workflows for CI/CD
  • JSII >= 5.9.0 Constructs are built using TypeScript and are vended to multiple languages using the JSII toolchain

To get started and understand the developer flow, follow the DEVELOPER_GUIDE

• Repository structure:

|--projenrc/ (Contains additional projen configuration)
|--docs/ (Contains architecture diagrams for the constructs)
|--lambda/ (Contains lambdas implementation used by constructs, typically custom resources)
|--layer/ (Lambda layers used by some constructs)
|--resources (If you need additional resources packaged with your library)
|--rosetta
    |--default-<module-name>.ts-fixture (template files that provide the necessary imports and boilerplate code for examples in readme.md)
|--src/ (Source .ts files)
    |--common/ (Common code reused across constructs)
        |--helpers
            |-- README.md (Documentation for helper functions)
            |-- *-helper.ts (Helper source file)
    |--cdk-lib/ (Constructs source files are here. These constructs are direct abstractions over L1 CDK Constructs, typically L2 Constructs)
        |--<module-name>
            |--index.ts (Construct source file)
            |--README.md (Construct documentation)
            |--perms.ts (permissions)
            |--<construct>.ts (various ts source files)
    |--patterns/gen-ai/ (Constructs source files are here. These constructs are higher level abstractions over L1 CDK Constructs, typically L3 Constructs)
        |--<module-name>
            |--index.ts (Construct source file)
            |--README.md (Construct documentation)
            |--perms.ts (permissions)
            |--<construct>.ts (various ts source files)
    |--index.ts (export constructs)
|--test/ (Source .ts test files)
    |--cdk-lib/ (Constructs unit test source files for cdk-lib)
    |--patterns/gen-ai/ (Constructs unit and integration tests source files are here for patterns)
        |--<module-name>
            |--<construct>.test.ts (Construct source test file)
            |--integ-tests/
                |--<testname>.integ.ts (Construct source integration test file)
    |--common (Common utilities source test files)
    |--integ/ (integration tests source files for cdk-lib constructs)
        |--<testname>.integ.ts (Construct source integration test file)

Commands you can use

You can get the list of all commands to run by running projen --help. The following tables summarizes the commands:

Best practices

• For contribution guidelines, follow CONTRIBUTING
• For documentation, be concise, specific, and value dense. Write so that a new developer to this codebase can understand your writing, don’t assume your audience are experts in the topic/area you are writing about. Use the same structure as documentation for existing constructs in this repository. When adding new code snippets to READMEs, use TypeScript only and follow the instructions in DOCUMENTATION_TESTING. Write Comprehensive JSDoc/Descriptions (add documentation tags to the typescript code)
• When building new constructs or updating existing ones, understand how the service resources are available through CloudFormation using the template reference and implemented in CDK using the api reference.
• Understand how users are supposed to use the service and the steps involved, configuration, user flow, restrictions, ... using the documentation
• Permissions should be extracted from the reference documentation if required
• For restrictions related to typescript, consult ts restrictions. This ensure the construct's exported APIs will be correctly exported in other languages.
• Follow the DESIGN_GUIDELINES
• When implementing constructs logic:
  • Use shared utilities to avoid code duplication
  • Implement validators using the information from the documentation and help catch issues at synth time
  • Implement proper error handling

Task Completion Guidelines

These guidelines outline typical artifacts for different task types. Use judgment to adapt based on scope and context. Ensure you use the best practices mentioned above.

New constructs and new features

A complete feature typically includes:

• Implementation: Build the feature
• Unit tests: Comprehensive test coverage for new functionality
• Documentation: Update relevant docs in the construct folder
• Changeset: Describe the feature for release notes

Bug fixes

A complete bug fix typically includes:

• Unit tests: Add tests that would fail without the fix (regression tests)
• Implementation: Fix the bug
• Manual verification: Run the tests and validate it works
• Changeset: Describe what was broken and how it's fixed

Refactoring / Internal Changes

• Unit tests for any changed behavior
• No documentation needed for internal-only changes
• Changeset only if it affects published packages

When to Deviate

These are guidelines, not rigid rules. Adjust based on:

• Scope: Trivial fixes (typos, comments) may not need examples
• Visibility: Internal changes may not need documentation
• Context: Some changes span multiple categories

When uncertain about expected artifacts, ask for clarification.

Boundaries

• NEVER modify directly a file which contains the string "Generated by projen". Use projen commands to interact with the codebase.
• NEVER add new dependencies without asking first, and without adding them to the .projenrc.ts file.
• ALWAYS run a full build when done with a task, this is to ensure all required files are generated before commit.
• ALWAYS Ask first: Before modifying existing files in a major way.