AN-447038 Add CLAUDE.md contributor guide for AI coding assistants

[ejsuncy]

Summary

Closes #2147 · Companion issue: #2148 · Jira: AN-447038

Adds a root-level CLAUDE.md that supplements (does not replace) CONTRIBUTING.md with the reviewer-enforced conventions that live outside the written spec — the ones first-time contributors (and AI coding assistants) only learn by having a PR sent back.

Non-breaking, documentation-only. No schema changes.

Motivation

From a discussion on the XDM team Slack (2026-04-22): a growing share of PRs is authored with help from AI coding assistants (Claude, Copilot, Cursor), and those assistants have no persistent memory of repo conventions between sessions. Reviewers end up repeating the same feedback PR after PR — missing meta:enum entries, examples with invented fields, removals instead of deprecations, missing needs review label, etc.

Adding a single root-level CLAUDE.md gives AI assistants and first-time human contributors a reviewer-shaped checklist they can internalize in one read.

What's in the file

• Audience — explicitly targets AI coding assistants and first-time human contributors.
• Non-negotiables — the nine reviewer feedback themes that come up the most (issue link / Closes #, reuse-over-reinvent, meta:enum coverage, deprecate-not-remove, every example validates, every new schema has an example and meta:status, don't hand-edit docs/reference/, add the needs review label).
• Contribution workflow — a single end-to-end path (sync → issue → branch → change → examples → validate → draft PR → label → review).
• Validation commands — exact commands with expectations and gotchas (prettier-write-then-diff, pre-existing validate failures baseline, etc.).
• Schema design rules — reuse-over-reinvent (with pointers to components/datatypes/, components/fieldgroups/, schemas/, docs/standards.md), meta:enum documentation for hard and soft enums, deprecation patterns, file placement, absolute $ref, naming conventions.
• Example-file rules — every field must be defined in the schema, xdm: prefixing, enum value coverage, sweep neighbors.
• PR requirements — template matching what reviewers approve (Summary / Motivation / Changes / Validation / Breaking changes sections).
• Common pitfalls list — a running log of what PRs get sent back for.
• Repository layout — quick reference pointer to components/, schemas/, extensions/, generated docs/reference/.

Companion issue

#2148 — separate proposal for automated CI checks so contributors don't have to depend on reading a doc. CLAUDE.md is the guide; CI is the guardrail. The two are complementary.

Validation

• npm test — 2387 passing, 1 pending
• npm run lint — clean (CLAUDE.md is prettier-formatted; verified with npx prettier --check CLAUDE.md)
• npm run validate — zero new failures vs master baseline (58 pre-existing, all unrelated to this change — confirmed by stash-compare)
• npm run incompatibility-check — clean

Breaking changes

None. Documentation-only; no schema files, example files, or build config changed.

Non-goals

• Changing CONTRIBUTING.md — CLAUDE.md explicitly defers to it and says so in the first paragraph. If the two disagree, CONTRIBUTING.md wins.
• Adding CI enforcement — that's Proposal: automated PR validation checks for common XDM contribution mistakes #2148.
• Targeting only Claude. The file name CLAUDE.md is the emerging convention for "AI-assistant context file at repo root" (mirrors AGENTS.md, GEMINI.md). The content is tool-agnostic.