Conversation
alvazjor
force-pushed
the
feat/agent-facing-doc
branch
from
bf62df1 to
ced432e
Compare
Add AGENTS.md with contributor guidelines for AI agents, plus two linked reference files for construct design and implementation rules. - AGENTS.md: main entry point with quick reference, coding patterns, testing, PR conventions, and anti-patterns - docs/AGENTS_CONSTRUCT_DESIGN.md: design decisions for mixins, facades, traits, API shape, interfaces, type hierarchy, and naming - docs/AGENTS_CONSTRUCT_IMPLEMENTATION.md: implementation details for grants, metrics, events, connections, IAM, L1/L2 mapping, and more
alvazjor
force-pushed
the
feat/agent-facing-doc
branch
from
ced432e to
72096fc
Compare
alvazjor
changed the title
alvazjor
changed the title
aws-cdk-automation
dismissed
their stale review
✅ Updated pull request passes all PRLinter validations. Dismissing previous PRLinter review.
aws-cdk-automation
added
the
pr/needs-maintainer-review
aws-cdk-automation
temporarily deployed
to
automation
GitHub Actions
Inactive
aws-cdk-automation
temporarily deployed
to
automation
GitHub Actions
Inactive
| - **Don't add speculative abstractions** — add what customers need today; unused abstractions become maintenance burden and API surface that can't be removed ([DESIGN_GUIDELINES.md#general-principles](./docs/DESIGN_GUIDELINES.md#general-principles)) | ||
| - **Don't change construct IDs** — logical IDs derive from the full construct path; any change replaces all resources in scope, causing data loss ([DESIGN_GUIDELINES.md#construct-ids](./docs/DESIGN_GUIDELINES.md#construct-ids)) | ||
| - **Don't leave commented-out code, dead code, or `eslint-disable` directives** — they rot, confuse future contributors, and mask real lint violations | ||
| - **Don't add validation to existing constructs without a feature flag** — adding validation that rejects previously accepted input is a breaking change, even if the input was invalid. You MUST gate new validation on existing constructs behind feature flags so existing apps continue to synthesize |
There was a problem hiding this comment.
even if the input was invalid.
Does this mean it's a condition that causes deployment failure?
If so, I disagree with this description. An CDK app that meets the conditions for deployment failure should not be deployable even if the build succeeds, and I believe adding validation to prevent that should be recommended.
vishaalmehrishi
left a comment
vishaalmehrishi
left a comment
There was a problem hiding this comment.
The content looks quite good, but I think we should discuss the organisation a bit.
Here's an alternative approach which is a combination of single-source-of-truth and agent-friendly setup:
- A single markdown file for each high-level topic (construct design, implementation, security, contributing, etc) with the relevant guidelines which both humans and agents can read.
- The AGENTS.md contains the top 2-3 items for each topic (so the agent does not always need to read a full topic file), and says "for more on , please see .
If we choose to stick with the current approach in the PR, then there should be some mechanism to make sure multiple files are correctly updated every time we change a guideline.
| | Mixin guidelines | `docs/MIXINS_DESIGN_GUIDELINES.md` | | | ||
| | New construct guide | `docs/NEW_CONSTRUCTS_GUIDE.md` | | |
There was a problem hiding this comment.
Looks like these are missing notes
| 1. Modifies resource's own L1 props, no logic → `CfnPropsMixin`, STOP | ||
| 2. Modifies resource's own L1 props, has logic → standalone `Mixin`, STOP |
There was a problem hiding this comment.
I'm wondering if examples will help here, especially for what logic looks like in CDK
| @@ -0,0 +1,300 @@ | |||
| # Construct Design Rules — Mixins, Facades, Traits & API Design | |||
There was a problem hiding this comment.
Is this a reformatted DESIGN_GUIDELINES doc or are there different instructions? I think it would be best to have one doc which both humans and agents can reference, otherwise we need to keep updating two docs as guidelines change.
| - KMS grants SHOULD include `kms:ViaService` | ||
| - Emit synthesis-time warnings via `Annotations.of(construct).addWarningV2()` when configuration results in public access | ||
|
|
||
| ## Implementation Patterns |
There was a problem hiding this comment.
Is there overlap between this and the construct implementation guidelines?
|
|
||
| Required for: new CFN resource types, new CFN properties, cross-service integrations, new versions, Custom Resources. | ||
|
|
||
| ## PR Conventions |
There was a problem hiding this comment.
Should this just go in the CONTRIBUTING.md file instead?
4 participants
Issue # (if applicable)
NA
Reason for this change
We're adding structured guidelines for AI agents contributing to the CDK codebase. Right now there's no single reference that tells an agent how to write constructs, follow naming conventions, or avoid common mistakes — this fills that gap.
Description of changes
Three new markdown files that give AI agents (and humans) a practical reference for CDK contribution:
The files cross-reference each other and link to existing docs (DESIGN_GUIDELINES.md, MIXINS_DESIGN_GUIDELINES.md, etc.).
Describe any new or updated permissions being added
NA
Description of how you validated changes
Checklist