Add CLAUDE.md to help AI coding assistants and first-time contributors follow XDM conventions

[ejsuncy]

Problem

Reviewers currently spend time sending PRs back for the same handful of missed conventions, e.g.:

• Missing meta:enum entries when enum values are added
• Example files with fields that aren't defined in the schema
• Free-form string properties being converted to hard enum arrays without need
• Fields removed or renamed instead of deprecated
• Missing Closes #<issue> reference in the PR body
• Missing needs review label on the PR
• New schemas without a *.example.*.json
• Relative $ref instead of absolute $id-style URLs

A growing share of PRs is authored with help from AI coding assistants (Claude, Copilot, Cursor, etc.). These assistants have no persistent memory of repo conventions between sessions, so every new session rediscovers the same mistakes.

Proposal

Add a root-level CLAUDE.md that supplements (not replaces) CONTRIBUTING.md with the operational knowledge reviewers enforce in practice:

• Non-negotiables — the short list of things that get PRs sent back
• Contribution workflow — fork → issue → branch → change → examples → validate → draft PR → needs review label
• Reuse-over-reinvent best practice — look for existing classes / fieldgroups / datatypes before creating something new (this echoes CONTRIBUTING.md "Schema design general guidelines" and XDM's internal design-review guidance)
• Schema design rules — meta:enum documentation, hard vs. soft enums, deprecate-don't-remove, file placement, naming conventions, absolute $ref
• Example-file rules — every field must exist in the schema, no invented fields, sweep neighboring examples
• Validation commands — npm install, npm test, npm run lint, npm run validate, npm run incompatibility-check
• PR body template — matching what reviewers approve
• Common pitfalls list — running log of what PRs get sent back for

Audience is explicitly both AI coding assistants and first-time human contributors. The file is written so that either audience can produce a reviewer-ready PR on the first try.

Companion follow-up

A separate issue will be filed proposing programmatic CI checks for the same conventions (so contributors aren't dependent on reading a doc). CLAUDE.md is the guide; CI is the guardrail.

Why this repo, why now

[Discussion on the XDM team Slack, 2026-04-22] identified this as a valuable contribution to reduce reviewer load as contribution volume grows.

PR to follow that implements this issue.