chore: clarify and prune design guidelines

[otaviomacedo]

Editorial pass over docs/DESIGN_GUIDELINES.md (with a small companion fix in
AGENTS.md) to make the guidance clearer, self-explanatory, and free of stale
references. No behavioral or code changes.

Highlights:

• Static type checks / instanceof: explain why instanceof is
  unreliable in CDK (multiple copies of a package in node_modules, multiple
  versions in one tree, jsii cross-language boundaries) rather than just
  asserting the rule. AGENTS.md updated to match: L1 Cfn* checks are
  auto-generated via spec2cdk; core classes like App/Stack/Stage
  implement the pattern by hand.
• Versioning: replaced the cryptic bullet "Semantic versioning Construct ID
  changes or scope hierarchy" with a full explanation — changing a construct's
  ID or scope position changes the derived logical ID, which replaces resources
  and causes data loss, so such changes are breaking and only allowed in
  -alpha modules.
• Fn::Sub: replaced the bare "Do not use FnSub" with the rationale (it
  embeds logical IDs as literal strings, bypassing CDK's reference/dependency
  tracking) and the recommended alternatives.
• Removed stale content: obsolete CDKv1→v2 note about removing pattern
  libraries, the deCDK prop-type restrictions, and dangling awslint rule tags
  ([_awslint:...]) that no longer correspond to active lint rules.
• Trait/Facade section: trimmed duplicated explanation of Facades providing
  Trait implementations.
• Misc: removed a leftover "Suggestion for alternative syntax?" author note
  (replaced with a proper explanation of static factory methods), de-duplicated
  the "be concise" props guidance, and minor wording/typo fixes.

---

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.

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

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-08-07 09:15 UTC · Rule: default-squash · triggered by rule automatic merge
• ✅ Checks passed · in-place
• ✅ Merged — 2026-08-07 10:11 UTC · at fc44a3fcc389bf022e9061fb1a72580d4112f406 · squash

This pull request spent 55 minutes 14 seconds in the queue, including 54 minutes 45 seconds running CI.

Required conditions to merge

• github-review-approved [🛡 GitHub branch protection]
  • chore: clarify and prune design guidelines #38463
• 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.