docs: add CLAUDE.md shim importing AGENTS.md

[mattmillerai]

ELI-5

Claude Code reads CLAUDE.md, not AGENTS.md, and does not fall back. This repo
already keeps all agent instructions in AGENTS.md (the cross-tool standard).
This adds a tiny CLAUDE.md that just imports AGENTS.md, so Claude Code picks
up the exact same instructions instead of finding nothing.

What changed

• New root CLAUDE.md containing only the canonical shim: an HTML comment
  explaining the pattern plus @AGENTS.md (which resolves relative to the shim's
  directory).
• AGENTS.md is left byte-for-byte unchanged.

Verification

• CLAUDE.md matches the canonical shim exactly (verified via cat -A).
• AGENTS.md unchanged: git diff origin/main -- AGENTS.md is empty.
• public-repo-hygiene gate passes locally
  (python3 scripts/check_public_repo_hygiene.py → OK); the shim contains no
  ticket-shaped ids, internal links, or repo refs.
• The commands AGENTS.md documents were cross-checked against
  .github/workflows/ci.yml and match (ruff check ., ruff format --check .,
  mypy src, pytest -v, python scripts/check_drift.py). No source, tests,
  generated models, or the sdist allowlist are touched, so the test,
  codegen-drift, and build-check jobs are unaffected by this doc-only file.

Residual

• The org-standard task described authoring AGENTS.md too, but it already
  exists on the default branch (197 lines, under the 200-line cap). The audited
  "no AGENTS.md" snapshot predates its authoring and is now stale. Per acceptance
  ("AGENTS.md content unchanged unless told to trim/merge"), it was left intact;
  this PR adds only the missing CLAUDE.md shim.
• No .cursorrules exists anywhere in the tree (nothing to remove).
• No nested AGENTS.md exists, so no nested sibling shims are needed.
• The parent epic is named-only in the brief; its body was not fetched and is not
  reachable from this sandbox, so it was not exercised.

Provenance

• Authored by: agent-work loop
• Verified: public-repo-hygiene passed locally; AGENTS.md confirmed
  byte-unchanged vs origin/main; CLAUDE.md confirmed to match the canonical
  shim exactly; documented commands cross-checked against CI config.
• Deviations: AGENTS.md was not authored because it already exists on the
  default branch; only the CLAUDE.md shim was added.

Summary by CodeRabbit

• Documentation
  • Updated contributor guidance to reference shared instructions in AGENTS.md.
  • Clarified that ongoing instruction updates should be maintained in AGENTS.md.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Team

Run ID: 872455ff-dfc7-4053-b092-06417bbc5168

📥 Commits

Reviewing files that changed from the base of the PR and between addfd9f and 2a6fd4b.

📒 Files selected for processing (1)

• CLAUDE.md

Included review availability: 0 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

---

📝 Walkthrough

Walkthrough

CLAUDE.md now imports the shared AGENTS.md instructions and directs contributors to maintain instructions in AGENTS.md.

Changes

Instruction synchronization

Layer / File(s)	Summary
Claude Code instruction shim CLAUDE.md	Adds an AGENTS.md import reference and directs contributors not to add instructions directly to CLAUDE.md.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~2 minutes

Change: Other

Suggested reviewers: alexisrolland

Merge Risk: ⚪ Minimal · up to 2a6fd

This change only adds the documented instruction shim and introduces no identified production or workflow risk.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a CLAUDE.md shim that imports AGENTS.md.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch matt/be-3574-claude-md-shim

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🔍 Cursor Review — Consolidated panel

Triggered by @mattmillerai.

✅ No high-signal findings.

Panel: 6/6 reviewers contributed findings.

[wei-hai]

Reviewed the CLAUDE.md import shim; its AGENTS.md target exists and remains the instruction source. No blocking findings.

[robinjhuang]

Auto-approved under the full-autonomy policy.

Gates verified at 2a6fd4bd39d167a36bc4be30f9a0673af2dca95c:

• full-autonomy label present
• assigned to, or review requested from, @robinjhuang
• not a draft
• 8 required check(s) green — none failing, none pending

This approval attests
that the machine gates above passed at this commit. It does not attest that a
human read the diff.