onboarding: cut CLAUDE.global.md's context tax by a third - #61
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
Reduces the always-loaded onboarding global guidance footprint by tightening prose and removing duplicated/low-signal content, while preserving the existing rule set and correcting the silent-stall guidance to work across AGY vs standalone Claude Code setups.
Changes:
- Adds maintainer guidance in
MAINTAINING.mdto keepCLAUDE.global.mdsmall and to record what content belongs in maintainer docs vs member runtime rules. - Refactors
CLAUDE.global.mdto remove duplicated subagent role tables and compress several sections without changing the underlying rules. - Updates the silent-stall section to be agent-agnostic (AGY
/schedulevs Claude Codecc-deadman).
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| onboarding/MAINTAINING.md | Documents a size target and explicit guidance for keeping CLAUDE.global.md lean during future syncs. |
| onboarding/CLAUDE.global.md | Tightens member-facing global guidance, removes duplicated subagent role descriptions, and updates silent-stall guidance for AGY vs Claude Code. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+148
to
+151
| - Before ending a turn while background or external work is still pending, arm a timer for the | ||
| expected duration plus 50%: `/schedule <seconds> <what to check>` on AGY (ONBOARDING step 12), or | ||
| `cc-deadman set <minutes> "<reason>"` if you run the standalone cc-watchdog under Claude Code. | ||
| Clear or re-arm it as your first action after the wait. |
The file is loaded into every session a member ever runs, so its size is a standing tax. It had drifted to 11.4 KB against the PI's own 7.7 KB. Now 9.2 KB, with no rule dropped: - Subagent roles: the four model/effort descriptions were a second copy of onboarding/agents/*.md. CLAUDE.global.md keeps the routing boundary and points there; MAINTAINING.md now names those files sole source of truth, so there is one less pair to hold in lockstep. - Probe-the-premise: dropped five PI-run war stories (the dead channel, the MW that didn't survive the boundary, the empty core) — persuasive to whoever lived them, opaque to a new member. - Skills: dropped the "this used to list ~35 skills and went stale" rationale; that is a maintenance decision, moved to MAINTAINING.md. - Response format, Asking, Git, Handoff: tightened prose, same rules. Silent-stall was a cut candidate but was rewritten instead: it told members to run `cc-deadman`, which AGY members never install (ONBOARDING step 12 gives them native /schedule). It had been pointing at commands they do not have, so it is now agent-agnostic and correct. Both timer placeholders now carry the +50% margin the bullet asks for, instead of reading as the bare expected duration. Also drops a stray `</content>` tag from the end of the file — a leaked tool-call closing tag that reached main in #60. MAINTAINING.md gains a "Keeping it small" section: the size target, the three kinds of content that belong in the maintainer file rather than the member's, and the caveat against trimming a rule to nothing to hit it.
alongd
force-pushed
the
claude-global-trim
branch
from
August 8, 2026 19:53
d3a57aa to
e0ed0fd
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #60.
CLAUDE.global.mdis loaded into the context of every session a member ever runs, so its size is a standing tax — and it had drifted to 11,379 B against the PI's own~/.claude/CLAUDE.mdat 7,732 B. This brings it to 9,171 B (~2,300 tokens, down from ~2,900) without dropping a single rule.What went:
onboarding/agents/*.md. The file keeps the routing boundary (implementer vs executor, and theautodevceiling) and points at the agent files. MAINTAINING.md now names those files the sole source of truth for model/effort — one less pair to keep in lockstep.What deliberately stayed — one deviation from a pure size cut:
The silent-stall section was on the chopping block, but reading ONBOARDING step 12 showed it was wrong, not just heavy: it instructed members to run
cc-deadman set …, and AGY members never install cc-watchdog — they get AGY's native/schedule. So it had been pointing at commands they don't have. Rewritten agent-agnostically (/scheduleon AGY,cc-deadmanfor anyone still on standalone Claude Code) at half the length. Deleting a silent-stall guard to save 400 B would have been the wrong trade.The remaining ~1.4 KB over the PI's file is the two things members carry that the PI does not: the
request-handoff.shno-op caveat and the silent-stall section.MAINTAINING.md gains a Keeping it small section recording the size target (
wc -cagainst both files when syncing), the three content types that belong in the maintainer file rather than the member's, and the caveat above — so the next sync doesn't re-inflate it.