chore: add CLAUDE.md files

[opieter-aws]

Description

Two unrelated-looking but mutually reinforcing gaps in our agent guidance, fixed together because they share a root cause: the rules agents rely on either weren't stated clearly or weren't reliably loaded.

Sharpened naming conventions. strands-py/AGENTS.md only said "Private members: Prefix with _". Read literally, "members" suggests class attributes, and the adjacent "Variables/Functions" line covers casing only — so an agent had no explicit instruction that private functions and modules take a leading underscore. It now reads "Private members, functions, and modules" with examples. On the TypeScript side, @internal is already used in ~70 places across the SDK to mark exported-but-non-public symbols, yet strands-ts/AGENTS.md never mentioned it; the TSDoc section now documents the convention so agents apply it consistently instead of inferring it from surrounding code.

Reliable AGENTS.md loading. The harness auto-loads CLAUDE.md from the repo root and any subdirectory it touches, but it does not reliably auto-load nested AGENTS.md. Our per-package guides were therefore only entering context via a soft, monorepo-ambiguous nudge ("go read the repo's AGENTS.md"). This adds a one-line CLAUDE.md (@AGENTS.md) at the root and in each package that has an AGENTS.md (strands-py, strands-ts, site, test-infra). Each file just imports its sibling AGENTS.md, so the correct package guide loads automatically based on which subtree is being edited, with zero content duplication — AGENTS.md remains the single source of truth.

To make those import files trackable, this also removes the CLAUDE.md entries from .gitignore, site/.gitignore, and strands-py/.gitignore.

Note

CLAUDE.md was previously gitignored on purpose. Un-ignoring it is a deliberate reversal: it means these import stubs are shared with everyone, and any contributor's previously-ignored local CLAUDE.md will now surface as untracked. Flagging for explicit sign-off rather than slipping it in.

Related Issues

Documentation PR

No site/ documentation changes. The edits are to agent-facing guidance files (AGENTS.md), not the published docs site.

Type of Change

Documentation update

Testing

Documentation- and config-only change; no runtime behavior is affected.

• Verified git check-ignore no longer matches any CLAUDE.md, so the new import files are trackable.
• Confirmed each new CLAUDE.md contains exactly @AGENTS.md and sits beside an existing AGENTS.md.
• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have reviewed and understand every line of code in this PR, including any generated by AI tools, and I can explain why it works
• My change is focused and reasonably small; I have split unrelated work into separate PRs
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[github-actions]

Assessment: Comment (no blocking issues)

Small, well-scoped, and the description does an excellent job explaining the why. I verified every claim against the tree and they hold up. The only thing genuinely needing a decision is the .gitignore reversal, which you've already correctly surfaced for explicit sign-off.

Review Categories

• Correctness: All 5 packages that have an AGENTS.md (root, strands-py, strands-ts, site, test-infra) get a matching @AGENTS.md stub, and packages without one get none — no orphans, no missing files. git check-ignore confirms all stubs are now trackable. Each stub is exactly @AGENTS.md + newline.
• Doc accuracy: The TS @internal convention is real and widely used (74 occurrences across 29 files — the "~70 places" claim is accurate). The Python naming clarification is consistent with the existing "Private modules prefixed with _" line earlier in the same file.
• Scope: Technically three edits (py wording, ts @internal, and the CLAUDE.md loading mechanism) in one PR, which brushes against "one logical change per PR." At ~9 lines and with a clear shared rationale, splitting would be overkill — calling it out only for awareness.
• Sign-off needed: The global un-ignore of CLAUDE.md has side effects for contributors' local files — see the inline note on .gitignore. You already flagged this; just confirming it warrants a maintainer's explicit OK before merge.

Nicely reasoned change — the zero-duplication "import sibling AGENTS.md" approach is the right call.