chore(agents): trim root CLAUDE.md by ablation; AGENTS.md links to it

Merged
WA
3d ago
+50-281

Summary

  • Trimmed root CLAUDE.md from 22.6KB to 11.5KB (-49%) by treating it as an ablation: traced every section to the commit that added it, bucketed each rule, then replayed tasks against old vs new guidance
  • Buckets: facts the model can't infer and scar-tissue rules stay (Application Operation Boundary, deployment flags, tools.config.params coercion, testing culture, the local gate); rules already enforced by a check:* audit or biome become one-line pointers (the audit message names the fix); narrow area rules move to their path-scoped rule file; the repo tree and generic coaching are gone
  • Common utilities keeps the ID rule (named randomUUID imports slip past check:utils) and the helpers check:utils can't catch (toArray, scalar coercions, compareStrings, backoffWithJitter/parseRetryAfter), with their typed-source and stricter-local-helper exceptions
  • Opening paragraph now lists the sections and says how to read a failing audit, so rules near the end aren't missed
  • AGENTS.md is now a symlink to CLAUDE.md (same as apps/sim/CLAUDE.md -> AGENTS.md). Drops the Turborepo agent block: the installed turbo 2.9.14 ships no docs/ it points at and never writes the block
  • sim-styling.md now also loads for packages/workflow-renderer tsx, and sim-testing.md for apps/sim/scripts/test-*-e2e.ts, so the rules that left the root still reach those files
  • Chip-family list and "no global styles" moved into .claude/rules/sim-styling.md (loads for every apps/sim/**/*.tsx); two skills that cited CLAUDE.md "Styling and EMCN" now point there

Type of Change

  • Chore (agent guidance)

Testing

  • Ablation probes: 9 tasks phrased as normal dev requests, each tempting a rule that was cut or condensed (retry backoff, deterministic key order, hosted/billing gating in a client component, logging ids, untyped payload coercion, settings toggle via emcn, context-menu item, numeric tool param, small lib feature + "make sure it works"). Opus 5.5 headless, project settings only, no Bash, once per variant from the same staging base
    • Old guidance: 9/9 followed, 326 prod lines, $6.77, 135 turns
    • New guidance: 9/9 followed, 312 prod lines, $5.93, 120 turns
    • All 18 diffs pass check:utils, check:source-conventions, check:client-boundary, check:file-names, check:explicit-any, check:comment-hygiene; neither variant wrote after-the-fact unit tests
    • Limits: one run per variant; no Bash, so this doesn't measure whether agents still run the local gate
  • Coverage audit: mapped each of ~120 old rules to where it lives now (new root file, a rule file whose paths: cover the files it matters for, a skill the root points to, or an audit whose failure message states the fix). A separate blind review against the old file found 12 gaps (dropped exceptions, softened wording, rule files scoped narrower than the root rule); all are restored in the second commit
  • check:guidance-refs (78 docs, every CLAUDE.md "<Section>" citation still resolves), check:skills, bun run lint

Checklist

  • Code follows project style guidelines
  • Self-reviewed my changes
  • Tests added/updated and passing (new tests pass the test-audit authoring gate)
  • No new warnings introduced
  • I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

šŸ¤– Generated with Claude Code