docs: clarify fluent API guideline rationale

[alvazjor]

Reason for this change

The stated rationale for the no-fluent-API rule was wrong. It claimed jsii languages cannot chain methods that return this, but chaining works fine in all jsii targets (verified in Python, Java, C#, and Go). The actual reason is API consistency: the library configures through props objects at construction time.

Description of changes

Correct the rationale and soften the rule from a hard prohibition to SHOULD NOT, in both docs/DESIGN_GUIDELINES.md and AGENTS.md. A fluent API is now allowed with a written justification, accepted at maintainer discretion.

Description of how you validated changes

Docs-only change.

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[github-actions]

⚠️ This pull request description does not follow the correct template structure.

PRs without a linked issue will receive lower priority for review and merging. Please update the description to follow the PR template and include a line like Closes #123 in the Issue section. If no existing issue matches your change, create one first.

[maintainer-for-aws]

Automated review

A maintainer will still review this — treat the notes below as a starting point.

This docs-only PR clarifies the CDK design guideline on fluent APIs across two files. In docs/DESIGN_GUIDELINES.md, the terse "No fluent APIs" bullet is expanded into a paragraph reframing the rule as a consistency preference (configure through props objects; chaining that returns this reserves the method's return value), with a PolicyStatement example and a written-justification-at-maintainer-discretion clause. In AGENTS.md, the corresponding anti-pattern bullet is softened from MUST NOT to SHOULD NOT and re-explained on the same consistency basis, instructing that a discovered fluent API be surfaced as a warning rather than a blocking issue. The two documents are consistent with each other, keep the #general-principles cross-reference intact, and the PolicyStatement example accurately reflects the real props-based API. No issues found on this change.

🔴 0 blocking · 🟡 0 recommended · ⚪ 0 optional

---

Generated automatically. React 👍 or 👎 to tell us whether this review helped, so we can improve these reviews.

[alvazjor]

@Mergifyio queue

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-09-11 14:00 UTC · Rule: default-squash · triggered by @alvazjor with the @mergifyio queue command
• ✅ Checks skipped · PR is already up-to-date
• ✅ Merged — 2026-09-11 14:00 UTC · at aa360a66e08207d8f587cac208595fce0e22549b · squash

This pull request spent 26 seconds in the queue, including 2 seconds running CI.

Required conditions to merge

• github-review-approved [🛡 GitHub branch protection]
  • docs: clarify fluent API guideline rationale #38811
• any of [🛡 GitHub branch protection]:
  • check-success = validate-pr
  • check-neutral = validate-pr
  • check-skipped = validate-pr
• any of [🛡 GitHub branch protection]:
  • check-success = build
  • check-neutral = build
  • check-skipped = build

[mergify]

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).

[github-actions]

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.