Skip to content

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

Merged
waleedlatif1 merged 3 commits into
stagingfrom
chore/agents-md-ablation
Nov 6, 2026
Merged

waleedlatif1 merged 3 commits into
stagingfrom
chore/agents-md-ablation

Conversation

@waleedlatif1

@waleedlatif1 waleedlatif1 commented Nov 6, 2026 •

Copy link
Copy Markdown
Collaborator

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

@vercel

vercel Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment
Project Deployment Actions Updated
docs Ignored Ignored Preview Nov 6, 2026 7:45pm UTC

Request Review

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No issues found across 7 files

Confidence score: 5/5

  • Automated review surfaced no issues in the provided summaries.
  • No files require special attention.

Turn on auto-fix | Re-trigger cubic

@greptile-apps

greptile-apps Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] This PR appears safe to merge.

Summary

Trims root agent guidance and makes AGENTS.md link to CLAUDE.md.

  • Agents now share a shorter guide for repo-wide rules.
  • Styling rules now cover workflow-renderer and name the shared chip family.
  • Testing rules now reach Sim's standalone E2E scripts.

Reviews (3) · Last reviewed commit: "chore(agents): keep auth-ui off the emcn..." · Reviewed by Greptile

Comment thread CLAUDE.md Resolved
Comment thread CLAUDE.md Resolved
@waleedlatif1

Copy link
Copy Markdown
Collaborator Author

@greptile

@waleedlatif1

Copy link
Copy Markdown
Collaborator Author

@cubic-dev-ai review this PR

@cubic-dev-ai

cubic-dev-ai Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

@cubic-dev-ai review this PR

@waleedlatif1 I have started the AI code review. It will take a few minutes to complete.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 9 files

Reply with feedback, questions, or to request a fix.

Turn on auto-fix | Re-trigger cubic

Comment thread .cursor/rules/sim-styling.mdc Resolved
Comment thread .claude/rules/sim-styling.md Resolved
Comment thread .cursor/rules/sim-testing.mdc Resolved
Comment thread .claude/rules/sim-styling.md Resolved
@waleedlatif1

Copy link
Copy Markdown
Collaborator Author

@greptile

@waleedlatif1

Copy link
Copy Markdown
Collaborator Author

@cubic-dev-ai review this PR

@cubic-dev-ai

cubic-dev-ai Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

@cubic-dev-ai review this PR

@waleedlatif1 I have started the AI code review. It will take a few minutes to complete.

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No issues found across 9 files

Confidence score: 5/5

  • Automated review surfaced no issues in the provided summaries.
  • No files require special attention.

Turn on auto-fix | Re-trigger cubic

@waleedlatif1
waleedlatif1 merged commit 4f89a61 into staging Nov 6, 2026
43 checks passed
@waleedlatif1
waleedlatif1 deleted the chore/agents-md-ablation branch November 6, 2026 19:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant