docs(claude-code): slim AI instructions (~54% token reduction)#1491
Merged
Conversation
Reduces the text Claude Code auto-injects at every session start from ~6,802 tokens to ~3,097 tokens (−3,705 tokens / −54.5%, measured with char/3.5 approximation) by: - Moving the full agent catalog out of custom-instructions.md. Agent metadata is now fetched on demand via mcp__codingbuddy__get_agent_details / list_agent_stacks, and the canonical list lives in packages/rules/.ai-rules/agents/README.md. Saves ~2,590 tokens/session. - Relocating permission-presets.md from .claude/rules/ (auto-loaded into every session) to docs/claude-code/ (reference material, not auto-loaded). Saves ~1,073 tokens/session. CLAUDE.md gets a one-line pointer to the new location so discoverability stays intact. The file move is byte-identical and git detects it as a rename. - Trimming CLAUDE.md's Tool Priority section to a layered summary with a link to .claude/rules/tool-priority.md for the full matrix. Saves ~42 tokens/session. All three MANDATORY rules are preserved verbatim in custom-instructions.md: - TDD_CONTINUITY_RULE (line 31) - CODINGBUDDY_CRITICAL_RULE — keyword mode detection (line 48) - SPECIALIST_COUNCIL_RULE (line 61) No behavioral change for any Claude Code session. Only the per-session context size drops. Cache-invalidation note: the first few sessions after this merge will re-cache the new prompt, so initial savings apply from roughly the second session onward. Also gitignores .claude/worktrees/ and .local-backups/ — both are local runtime/backup artifacts that were incorrectly surfacing as untracked and should never be committed. Original work by Codex running a token-reduction prompt; verified by Claude Code for mandatory-rule preservation, path consistency, downstream references, and actual token measurement.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
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
1 participant
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.
Summary
Reduces the text Claude Code auto-injects into every session start from 6,802 → 3,097 tokens (−3,705 / −54.5%, char/3.5 approximation).
Originally produced by Codex running a token-reduction prompt, then verified by Claude Code for rule preservation, path consistency, and actual token measurement.
What moved
.claude/rules/custom-instructions.mdmcp__codingbuddy__get_agent_details/list_agent_stacks. Canonical list atpackages/rules/.ai-rules/agents/README.md..claude/rules/permission-presets.md→docs/claude-code/permission-presets.mdCLAUDE.md.claude/rules/tool-priority.mdfor the full matrix. New Permission Presets pointer..gitignore.claude/worktrees/and.local-backups/— local runtime/backup artifacts that should never surface as untracked.Mandatory rules preserved (verbatim)
TDD_CONTINUITY_RULE—.claude/rules/custom-instructions.md:31CODINGBUDDY_CRITICAL_RULE(keyword mode detection) —.claude/rules/custom-instructions.md:48SPECIALIST_COUNCIL_RULE—.claude/rules/custom-instructions.md:61Behavioral impact
None. The project CLAUDE.md and
parse_modeMCP response still control actual workflow behavior. Dropping the agent catalog from the auto-load layer does not remove any behavior — theactivateMCP tool still recommends primaryAgent + specialists per task, and users who need freestyle selection canlist_agent_stackson demand.Cache note: first 1–2 sessions after merge will re-cache the new prompt (one-time re-cache cost). Net savings apply from roughly the second session onward.
Cost impact (Opus 4.6 user, ~10 sessions/day)
Test plan
yarn workspace codingbuddy npm audit --severity high— ✅ No audit suggestionsyarn workspace codingbuddy-claude-plugin npm audit --severity high— ✅ No audit suggestionsyarn workspace landing-page npm audit --severity high— ✅ No audit suggestionsajv-cli validate packages/rules/.ai-rules/agents/*.json— ✅ all validmarkdownlint-cli2 packages/rules/.ai-rules/**/*.md— ✅ 102 files, 0 errors.claude/rules/permission-presetsreferences — only CLAUDE.md hit, already updatedcustom-instructions.md— all presentgit diffverifiesdocs/claude-code/permission-presets.mdis byte-identical to the old.claude/rules/permission-presets.md(git rename detection confirms)mcp__codingbuddy__get_agent_details("<name>")still returns full agent metadata when needed