docs: trim AGENTS.md to the non-derivable core and add CLAUDE.md

[mattbodle]

Why

AGENTS.md had grown to 556 lines / 21.1 KiB, past the point where agents reliably follow it. It is now 162 lines / 8.2 KiB.

Every major agent vendor now publishes a budget for instruction files, and this one blew through them:

Consumer	Published budget	Before	After
Claude Code	target under 200 lines; longer files "consume more context and reduce adherence"	556 lines	162
Codex	project_doc_max_bytes = 32 KiB for the whole merged root→cwd chain	21.1 KiB (66%)	8.2 KiB (26%)
Copilot	"no longer than 2 pages"	~11 pages	~3

The failure mode isn't an error, it's dilution: past the budget the rules that matter get lost among the ones that don't, and Codex starts silently dropping nested, more-specific files once the chain fills.

CLAUDE.md symlink — the part that unblocks something

Claude Code reads CLAUDE.md, not AGENTS.md. There was no CLAUDE.md, so all 556 lines were invisible to it — while the repo ships seven .claude/skills/ definitions, i.e. it is clearly being used with Claude Code.

Anthropic's documented fix is a symlink or an @AGENTS.md import. This adds the symlink (create mode 120000), matching the convention already used elsewhere in our SDK estate. Copilot independently accepts a root CLAUDE.md as a substitute for AGENTS.md, so one file serves every consumer with nothing to keep in sync.

The rule applied to every line

If a config file already states it, delete it. The config can't go stale; this file can.

That is also Anthropic's /doctor trim rule — cut directory layouts, dependency lists and architecture overviews; keep pitfalls, rationale, and conventions that differ from tool defaults.

Deleted because a config file says it:

• the commit-type → version-bump table → release.config.js
• every .prettierrc value → .prettierrc, and .eslintrc already sets "prettier/prettier": "error"
• tsconfig target / lib / moduleResolution → tsconfig.json
• the .nvmrc version, and every file count (60 .ts / 1 .js, 34 / 7, ~30 kits, ~58 src files) — all drift on the next migration PR
• the ~40-line src/ tree, the 13-row Key Files table, the 13-term glossary, the private-module listing, five ASCII flow diagrams (ARCHITECTURE.md has the real ones), and the per-skill descriptions that ls .claude/skills/ already shows
• the generic "read first, modify later" / "check existing tests" steps

Kept: the commands whose names don't tell you what they cover, the conventions no config encodes (naming — verified that no lint rule enforces it), and the traps.

Two things the sweep caught

1. The version-bump table was wrong. It claimed docs, test, refactor, perf, style, chore, ci, build and revert produce "no release". release.config.js gives ci, docs, test, refactor, style, build, chore and revert a patch release. Hand-copying a config into prose is how that happens, which is the argument for deleting it rather than fixing it.

2. Nothing checks the TypeScript. The first pass repeated the old file's claim that ".ts uses ESLint + GTS". Measured, that is false:

• npm run lint is eslint src/ test/src/ with no --ext, so ESLint reports .js files only and never a .ts one (measured by running it)
• npm run prettier globs "**/*.js"
• gts:check exists as a script but no hook or workflow calls it
• build:types runs tsc -p tsconfig.types.json || true — the || true swallows type errors
• the pre-commit hook is "pre-commit": ["lint"], so it inherits the same .js-only scope

So neither CI nor the pre-commit hook catches a type error or a formatting slip in a .ts file, in a src/ that is now TypeScript throughout. That is trap 6, and npm run build:ts / npm run gts:check are surfaced in the commands table as the manual gates they are. Worth a look independently of this PR.

Other stale claims fixed

Was	Now
"Create PRs against the master branch"	main. Check PR for semantic target branch accepts only main and build/*. GitHub still offers master as the default base, and CONTRIBUTING.md:8 still says master.
"npm run test — Full suite (Karma + Jest)"	npm test is Karma only; Jest is npm run test:jest.
tree listing identity.js, events.js, forwarders.js, persistence.js	src/ is TypeScript throughout apart from the stub entry point (#1370 finished that migration).
tree had no kits/ at all	kits/ is a top-level directory of vendored integrations, each with its own build and tests.
"Check ARCHITECTURE.md if available"	It exists. Hedge dropped.
Only /verify listed	All 7 skills named.

Traps added

1. npm test needs a Firefox binary — test/karma.config.js runs ['ChromeHeadless', 'FirefoxHeadless']; without it the launcher crashes and takes karma-server with it.
2. Karma's exit code can lie when the launcher dies — read the TOTAL: line, not $?.
3. Both runners need a built dist/ — Karma serves ../dist/mparticle.js, Jest loads it via setupFiles. npm test builds first; npm run test:jest and a bare karma start do not, so Jest fails on a fresh clone for reasons unrelated to your diff.
4. dist/ is committed and every build rewrites it — git checkout -- dist/ before committing.
5. Prettier is pinned at 1.18.2 (exact, no caret), which predates optional chaining: x?.[key] makes it report Parsing error: Expression expected and silently stop formatting the whole file.
6. Nothing checks your TypeScript — see above.
7. Jest skips two kits by design — kits/adobe (kit-level Jest) and kits/rokt (Vitest, whose .spec.ts names Jest would falsely match).

Verification

• Every path and config claim was checked against the tree at 8288cc96, and the ESLint scope was measured by running it rather than inferred.
• Docs and one symlink only, no behaviour change. npm run prettier globs **/*.js and there is no markdown linter in CI.
• No bare @path tokens, so Claude Code won't treat anything as an unintended import when reading through the symlink.
• Re-verified end to end on the current head (a26824a2): every backticked path exists, eslint is still eslint src/ test/src/ with no --ext under eslint 8 (eslintrc mode, so the default extension really is .js only), .eslintrc uses @babel/eslint-parser which could not parse a .ts file even if it were passed one, tsconfig.types.json sets noEmitOnError: false so the || true genuinely swallows type errors, pre-commit is still ["lint"], prettier is still 1.18.2 exact, and release.config.js still gives a patch release to all nine non-feat types. One claim of my own was wrong and is fixed in a26824a2: I had written "/verify runs lint, build and Jest in one step". .claude/skills/verify/SKILL.md actually runs lint, then npm run test:jest and npm test (Karma), with no standalone build step. Corrected, and pointed at trap 3.

For the SDK team to decide

1. The COMMON SECTION is hand-synced across SDK repos and its banner was stamped Last Updated: 2026-02-16. I trimmed within the markers and kept them, but I can only see this repo — the trim needs mirroring, or the convention wants replacing with a shared file. I also moved the branch-target rule out of the shared block, since master was wrong here precisely because it lived in the block every SDK copies.
2. CONTRIBUTING.md:8 still says "PR into the mParticle SDK master branch". Left alone as out of scope; happy to fix here if preferred.
3. .github/workflows/reusable-workflows.yml still passes base_branch: "development" to security-checks.yml@stable — another master-era leftover.
4. The TypeScript gap in finding 2 is a CI question, not a docs one. Documented as a trap so agents compensate, but the real fix is --ext .ts on the lint script, dropping the || true, or wiring up gts:check.
5. .claude/skills/verify/SKILL.md contains the same mistake I just fixed, and one more. Its comment reads "Each suite handles its own build internally" — true for npm test, false for npm run test:jest, which is exactly trap 3. So /verify can report a spurious Jest failure on a fresh clone. Left alone because this PR is scoped to AGENTS.md/CLAUDE.md; the skill wants an explicit npm run build step.

[cursor]

PR Summary

Low Risk
Documentation-only changes plus a symlink; no runtime or CI behavior changes.

Overview
Shrinks agent instructions so they stay within common context budgets (~556 lines → ~161). The file now states upfront that it only holds traps and conventions not encoded in config, and points architecture/API detail to ARCHITECTURE.md and public docs.

Removes duplicated derivable content (glossary, full src/ tree, build/test command catalogs, ASCII flows, generic SDK patterns) and replaces it with web-specific PR workflow (main vs stale master), a compact layout/commands table, instance model, gotchas, and seven documented command traps (Firefox for Karma, lying exit codes, dist/ build/commit expectations, old Prettier vs optional chaining, JS-only lint/CI for .ts, Jest kit exclusions).

Corrects misleading guidance in the old doc: PR base branch, npm test vs Jest, commit types vs release.config.js release behavior, and that TypeScript is not enforced by lint/CI.

Adds CLAUDE.md so Claude Code (and Copilot) load the same instructions as AGENTS.md, which they do not read by default.

^{Reviewed by Cursor Bugbot for commit a26824a. Bugbot is set up for automated code reviews on this repo. Configure here.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud