What's new
We added structured documentation for AI coding assistants working on the CDK codebase. If you use Copilot, Cursor, Claude Code, Codex, Kiro, or a similar tool when contributing to CDK, these files help your agent follow CDK conventions and avoid common mistakes.
Four files were added in #37565:
| File |
Purpose |
AGENTS.md |
Main entry point. Build/test commands, codebase layout, L1/L2/L3 model, construct anatomy, naming, props design, security rules, implementation patterns, documentation standards, testing conventions, PR format, anti-patterns. Most AI tools auto-discover this file at the repo root. |
CLAUDE.md |
One-line pointer to AGENTS.md for Claude Code users. |
docs/AGENTS_CONSTRUCT_DESIGN.md |
Design rules for L2 constructs: feature placement (mixin vs facade vs trait), API shape, interface design, type hierarchy, naming. |
docs/AGENTS_CONSTRUCT_IMPLEMENTATION.md |
Implementation patterns: grants, metrics, events, connections, IAM integration, L1/L2 mapping, mixin implementation. |
How to use them
Human contributors: These files are useful as a quick reference even without an AI assistant. The rules are the same ones in DESIGN_GUIDELINES.md, written in a structured, prescriptive format with explicit MUST/SHOULD/MAY severity levels.
Using an AI coding assistant: Most tools automatically pick up AGENTS.md from the repo root. Point your tool at the repo root and it will discover the file on its own. For deeper design or implementation questions, the agent can follow references to the two supplementary files in docs/.
Building or configuring an AI agent for CDK work: Start with AGENTS.md as the primary context file. It covers the common case. Add docs/AGENTS_CONSTRUCT_DESIGN.md when the agent is designing new constructs or extending existing ones, and docs/AGENTS_CONSTRUCT_IMPLEMENTATION.md when it is implementing cross-cutting patterns like grants or metrics.
Relationship to existing docs
These files do not replace anything. DESIGN_GUIDELINES.md, MIXINS_DESIGN_GUIDELINES.md, NEW_CONSTRUCTS_GUIDE.md, and CONTRIBUTING.md remain the authoritative references for human contributors. The agent-facing files are a structured interpretation of the same rules, optimized for how AI tools process instructions.
When rules change, DESIGN_GUIDELINES.md is updated first, and the agent-facing files are updated to match.
Feedback
If you notice gaps, incorrect rules, or places where your AI assistant still gets things wrong despite these files, open an issue or comment here. This is a first iteration and we expect to refine the content based on real-world usage.
What's new
We added structured documentation for AI coding assistants working on the CDK codebase. If you use Copilot, Cursor, Claude Code, Codex, Kiro, or a similar tool when contributing to CDK, these files help your agent follow CDK conventions and avoid common mistakes.
Four files were added in #37565:
AGENTS.mdCLAUDE.mdAGENTS.mdfor Claude Code users.docs/AGENTS_CONSTRUCT_DESIGN.mddocs/AGENTS_CONSTRUCT_IMPLEMENTATION.mdHow to use them
Human contributors: These files are useful as a quick reference even without an AI assistant. The rules are the same ones in DESIGN_GUIDELINES.md, written in a structured, prescriptive format with explicit MUST/SHOULD/MAY severity levels.
Using an AI coding assistant: Most tools automatically pick up
AGENTS.mdfrom the repo root. Point your tool at the repo root and it will discover the file on its own. For deeper design or implementation questions, the agent can follow references to the two supplementary files indocs/.Building or configuring an AI agent for CDK work: Start with
AGENTS.mdas the primary context file. It covers the common case. Adddocs/AGENTS_CONSTRUCT_DESIGN.mdwhen the agent is designing new constructs or extending existing ones, anddocs/AGENTS_CONSTRUCT_IMPLEMENTATION.mdwhen it is implementing cross-cutting patterns like grants or metrics.Relationship to existing docs
These files do not replace anything. DESIGN_GUIDELINES.md, MIXINS_DESIGN_GUIDELINES.md, NEW_CONSTRUCTS_GUIDE.md, and CONTRIBUTING.md remain the authoritative references for human contributors. The agent-facing files are a structured interpretation of the same rules, optimized for how AI tools process instructions.
When rules change,
DESIGN_GUIDELINES.mdis updated first, and the agent-facing files are updated to match.Feedback
If you notice gaps, incorrect rules, or places where your AI assistant still gets things wrong despite these files, open an issue or comment here. This is a first iteration and we expect to refine the content based on real-world usage.