The useful version of this article is not another plea to make CLAUDE.md shorter. Shorter can be worse if the wrong rule is removed. The better question is whether the team knows which instructions are global, which are project-wide, which are repo-specific, which are personal, and which are duplicated by imports or path-scoped rules.
please-optimize-my-claude is worth saving because it treats Claude Code instructions as a hierarchy that can be audited. It discovers files, estimates loaded context, flags duplication and misplacement, checks stale commands, scans for secrets, and offers a read-only analyze mode before anything is changed. That is a distinct contribution from simple prompt compression.
Why this seed is worth saving
The original article failed because it leaned on efficiency language. The source is stronger than that. The README explains a real failure mode: global ~/.claude/CLAUDE.md, project CLAUDE.md, subdirectory CLAUDE.md, CLAUDE.local.md, .claude/rules/, and @import references can all stack together. If the same rule appears at several levels, Claude Code sees repeated instruction surface. If an organization-specific rule lives in global, every unrelated project pays for it and may follow it.
This is a hierarchy audit, not a delete button
The right adoption path starts with /please-optimize-my-claude analyze. That mode reports without editing files. It is the safe first step because CLAUDE.md often contains hard-earned local knowledge: release rituals, broken commands to avoid, migration warnings, permission boundaries, and repo-specific hazards. A good audit separates duplicate boilerplate from useful context. A bad cleanup removes the warning that prevents a production mistake.
What the skill actually discovers
The skill definition describes a discovery pass over global CLAUDE.md, global rules, the project root, subdirectory CLAUDE.md files, CLAUDE.local.md, project rules, and imports up to five levels deep. It resolves symlinks and strips HTML block comments before token counting. That matters because a human looking at one file rarely sees the effective prompt surface loaded from the current working directory. The tool's strongest feature is the 'What Claude Sees' simulator.
The detector set is the article
The README and changelog list nine detectors: duplication, misplacement, bloat, stale content, contradictions, token budget audit, best-practices comparison, missing repository index, and security scan. That breadth is the real news. Duplicates waste context. Misplaced rules pull project assumptions into the wrong repo. Stale commands cause failed tool calls. Contradictions make Claude choose arbitrarily. Security findings matter because internal URLs, credentials, and API keys sometimes end up in instruction files that are meant to guide every session.
Use the budgets as smoke alarms
The best-practices reference gives budgets: under 1,000 estimated tokens for global, under 3,000 for project root, and under 2,500 for subdirectory files. Treat those as smoke alarms, not law. A mature monorepo may need a larger root file. A personal global file should usually be lean. The useful behavior is not the exact number; it is seeing which layer is overweight and why. The estimate is word count times 1.5, so it should not be presented as precise billing data.
The sample report proves the shape
The sample report is synthetic, which is good editorially because it should not be sold as a universal benchmark. In that fabricated four-repo organization, the tool found 27 issues and estimated a 1,982-token reduction, including duplication, misplacement, stale content, a contradiction, and a low-severity internal URL. The lesson is not that every team will save 44.4%. The lesson is that the report gives issue categories a reviewer can inspect before deciding what to move, delete, or keep.
Where it differs from concise-rule projects
This should not be merged conceptually with claude-token-efficient. A concise CLAUDE.md file is about a smaller standing instruction set. please-optimize-my-claude is about file placement and hierarchy. It can tell you that a rule belongs in frontend/CLAUDE.md instead of root, that a global commit format is actually client-specific, or that a .claude/rules/ file only needs to load for matching paths. Those are architectural decisions about context, not just compression decisions.
Run order for a real team
Install with npx skills add thedoublejay/please-optimize-my-claude, then run /please-optimize-my-claude analyze from a representative project directory. Read security findings first. Next, review contradictions and stale commands because they can create wrong behavior, not just higher token use. Then review duplication and misplacement. Only after that should a maintainer try interactive mode. Auto mode belongs at the end of the process, after backups and restore have been verified.
A concrete first run
Use this sequence for the first audit. Step one: create a branch named something like audit/claude-md-hierarchy. Step two: install the skill with npx skills add thedoublejay/please-optimize-my-claude. Step three: run /please-optimize-my-claude analyze and save the report output in the issue or planning doc. Step four: copy the report's 'What Claude Sees' totals into a small table by working directory. Step five: mark every finding as keep, move, delete, or verify. Step six: fix only security findings, stale commands, and obvious exact duplicates in the first pass. Step seven: run analyze again and compare the before/after report. Do not run /please-optimize-my-claude auto until those steps are boring.
How to judge each finding
A duplicate is safe to remove only when the lower-level copy adds no local exception. A misplaced rule should move to the narrowest directory where it remains true. A stale command should be checked against the nearest package.json, not guessed from memory. A contradiction should be resolved by deciding which layer owns the rule. A security finding should be fixed before any token-saving work. A bloat finding should be rewritten only when it still preserves the specific command, file path, or constraint that made the text useful.
Backups are part of the quality bar
The README documents scope-matched backups: global changes under ~/.claude/backups/ and project changes under .claude-md-backup/. That is not a convenience footnote. It is the threshold for trusting any automated rewrite of standing instructions. Before running auto mode, confirm the backup path, run restore on a throwaway copy, and commit the project-level before/after diff. A cleaned instruction hierarchy should be reviewable like code.
Where not to use it
Do not run auto mode on a shared repo if no one has read the report. Do not treat token savings as the only goal. Do not use it to delete long but necessary architecture warnings. Do not expect full behavior outside Claude Code; the README says analyze mode works best in other agents because interactive tools may not exist. Do not move personal CLAUDE.local.md content into committed project files just because it appears in the inventory.
The Codex angle
Codex users should care because the same discipline applies to AGENTS.md, skill instructions, and repo memory. An agent's standing context becomes product infrastructure when it shapes every task. The practical bridge is to use the report as a model for your own instruction review: inventory the layers, classify rule scope, verify commands, remove stale history, and keep security-sensitive details out of broad context. Claude Code has CLAUDE.md; Codex has its own instruction surfaces that deserve the same audit.
Save please-optimize-my-claude as a CLAUDE.md hierarchy audit article. It is useful when instruction sprawl, duplicated guidance, stale commands, or misplaced project rules are the real problem; it is dangerous when treated as an automatic context cutter without reading the report.
Practical takeaway
Create a branch, install the skill, run /please-optimize-my-claude analyze, and save the report. Triage in this order: security, contradictions, stale commands, misplaced rules, duplicates, then bloat. Move rules to the narrowest correct layer, remove only verified duplicates, confirm backup and restore paths, and reserve auto mode for a reviewed branch where the before/after diff can be inspected.