Skip to content

[Due for payment 2026-08-31] Trim CLAUDE.md to remove derivable / non-actionable content (362 → 125 lines) #98570

Closed

Description

@MelvinBot

Proposal
Cut the parts of the repo-root CLAUDE.md that shouldn't be there — anything Claude can easily derive from the codebase, or that the agent doesn't need.

Background
CLAUDE.md is our project instruction file for Claude Code, loaded into context at the start of every session for every contributor. Today it is 362 lines, ~2,850 tokens. Much of it either repeats what's easy to find in the code (e.g. an npm run … script list from package.json) or isn't something the agent needs (e.g. a "Core Functionality" feature rundown). Anthropic's context-engineering guidelines call out exactly this kind of content as something to keep out of an instruction file.

Problem
That bloat is not free — we pay for it three ways:

  • Tokens (money): ~2,850 billed on every session, for every contributor, even when not relevant to the task.
  • Attention (quality): probably the bigger cost, and harder to measure than tokens. The extra context competes for the model's attention with the rules that matter.
  • Maintenance (time): duplicated content drifts out of date when the code changes. Keeping it correct costs engineer hours, and when it isn't kept correct it silently feeds the agent wrong context.

Solution
Improve CLAUDE.md with Anthropic's own tooling. Claude Code v2.1.206 added a /doctor check for exactly this. It generated a trimmed CLAUDE.md per the newest Anthropic guidelines, reviewed line by line, in draft PR #98560. Result: 362 → 125 lines, ~2,850 → ~1,630 tokens per session.

Every removed part came from the file's initial commit (#68547), a "comprehensive overview" meant as a baseline with no targeted intention behind any particular section. Everything added deliberately since then was kept.

cc @roryabraham @mountiny

Reported in Slack.

Activity

  1. roryabraham commented on Aug 13, 2026

    @roryabraham
    Contributor

    Reviewed the draft PR

  2. mountiny commented on Aug 14, 2026

    @mountiny
    Contributor

    Happy to let you handle this one since you already put in the review 🙌

  3. melvin-bot commented on Aug 17, 2026

    @melvin-bot

    @roryabraham Whoops! This issue is 2 days overdue. Let's get this updated quick!

  4. roryabraham commented on Aug 19, 2026

    @roryabraham
    Contributor

    Awaiting for my requested changes to be implemented in the draft PR

  5. adamgrzybowski commented on Aug 19, 2026

    @adamgrzybowski
    Contributor

    @roryabraham Sorry, I had to switch my focus to other tasks for a moment. I will go back to this today

  6. roryabraham commented on Aug 21, 2026

    @roryabraham
    Contributor

    PR merged. No payments due.

  7. changed the title [-]Trim `CLAUDE.md` to remove derivable / non-actionable content (362 → 125 lines)[/-] [+][Due for payment 2026-08-31] Trim `CLAUDE.md` to remove derivable / non-actionable content (362 → 125 lines)[/+] on Aug 24, 2026
  8. melvin-bot commented on Aug 24, 2026

    @melvin-bot

    @roryabraham @adamgrzybowski

    The solution for this issue has been 🚀 deployed to production 🚀 in version 9.4.59-5 and is now subject to a 7-day regression period 📆. Here is the list of pull requests that resolve this issue:

    If no regressions arise, payment will be issued on 2026-08-31. 🎊

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions