chore: add agent-facing design guidelines#37565
Conversation
bf62df1 to
ced432e
Compare
ced432e to
72096fc
Compare
✅ Updated pull request passes all PRLinter validations. Dismissing previous PRLinter review.
| - **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.
There was a problem hiding this comment.
Good catch, this needs to be reformated to explain better the condition. From a pure technical perspective, even tho the original input never worked as intended, a change modifying how a validation used to work will be considered a breaking change. But is a valid breaking change, and then a feature flag will not be rquired, and the validation alone is enough. But, imo, we still need a way to alert consumers that the change was done, and justify why the breaking change was permitted without a flag.
Will rewrite this in a new revision
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 topic, please see topic-specific md file".
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.
| @@ -0,0 +1,326 @@ | |||
| # AGENTS.md — AWS CDK | |||
|
|
|||
| > Contributor-focused guide for AI agents working on the AWS CDK codebase. | |||
There was a problem hiding this comment.
The main difference between this and other documents is the enforcement language used.
The other two documents use MUST, MUST NOT and SHOULD which are better keywords to guide agents.
Meanwhile this document used keywords like NEVER, Don't etc. which not be interpreted as strictly as the keywords in other documents.
Is this intentional ? Are we going to be using this as mainly context file for an agents meanwhile the other two act as exact prescriptive guidance ?
There was a problem hiding this comment.
Is this intentional ? Are we going to be using this as mainly context file for an agents meanwhile the other two act as exact prescriptive guidance ?
Yes and yes. The language here is a bit more natural because this file is more for general context, tho there are some rules here that follow the imperative language. The other 2 are loaded based on what the agent defines for the task it is implementing, and they are a repository of rules of instructions that need to be followed to comply with our expectations, so the language used is more unambiguous
72096fc to
39f8fa6
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
39f8fa6 to
793bbfb
Compare
|
|
||
| ## Anti-Patterns — Things NOT To Do | ||
|
|
||
| - **MUST NOT use jsii-incompatible patterns** — mapped types, conditional types, overloaded functions, TypeScript namespaces, `export const` objects (use `public static readonly` on classes). MUST NOT move public types between files — file location is part of the external contract in jsii bindings |
|
Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork). |
Merge Queue Status
This pull request spent 1 hour 3 minutes 5 seconds in the queue, including 51 minutes 12 seconds running CI. Required conditions to merge
|
|
Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork). |
|
Comments on closed issues and PRs are hard for our team to see. |
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