Prune the Rules File

Before diving in, complete Track Three Numbers so you can see which rules are actually improving acceptance rate before deciding what to cut.

Your CLAUDE.md has 140 lines. You wrote 40 of them in the first week, copying best practices from a blog post. You wrote another 60 over the following months from real failures. The remaining 40 are somewhere in between, and you are not sure which rules are still true. This is the rules file at month three.

After 30 sessions of consistent codification, a rules file has a new problem: it is too long. Rules written in month one may conflict with rules written in month three. Rules written for a feature that no longer exists still fire on every session and eat tokens. Rules written speculatively (best practices you copied from an article before you had a real failure that needed them) are taking up space without doing work.

Here is the before and after: Staleness is the most common category. A rule that says 'use React 17 class component patterns' in a codebase that migrated to React 18 hooks six months ago is not neutral. It is actively wrong, and the model will follow it. Rule rot is silent. Nothing alerts you when a rule becomes false.

Conflicts are the second category and harder to spot. 'Always write unit tests before implementation' and 'focus on shipping working code before adding tests' are both reasonable rules to write at different points in a project. Together they are a coin flip. The model picks one at random.

The audit question for every rule is: if a new session loaded this rule cold and followed it literally, would that be correct behavior today? Rules that fail that test get deleted. Not archived, not commented out. Deleted. Git has history.

Paste this into Claude:

Here is my current CLAUDE.md: [paste your full CLAUDE.md]. Audit it for me. For each rule, tell me: (1) whether it is still valid given what I've described about my current project state, (2) whether it conflicts with any other rule in the file, (3) whether it was likely written speculatively rather than from a real failure. Give me a list of rules to delete with a one-line reason for each, and a list of rules to tighten with a suggested revision. Do not suggest keeping anything out of caution. If a rule is not earning its tokens, cut it.

What good looks like:

• You deleted at least 3 rules that were stale, conflicting, or speculative
• You identified at least one pair of rules that were in direct conflict
• You revised at least one rule that was too vague to be actionable
• Your CLAUDE.md is shorter after the audit than before it
• You can state in one sentence the deletion test you applied to each rule

What a good response looks like:

Audit results for your 22-rule CLAUDE.md. 8 rules flagged for action.

DELETE LIST (5 rules):
1. 'Always write comprehensive comments explaining what each function does.' Reason: stale + vague. You told me you switched to TypeScript 8 months ago. Types document intent better than prose comments. This rule now produces comment noise.
2. 'Use React class components for stateful logic.' Reason: stale. You are on React 18 hooks. This rule will cause the model to write class components in a hooks codebase.
3. 'Always run the full test suite before committing.' Reason: conflict. Rule 14 says 'use pre-commit hooks to run only affected tests for speed.' These two instructions cancel each other out. Delete the broader one, keep the specific one.
4. 'Write clean, readable code.' Reason: speculative + meaningless. Zero guidance. The model cannot act on this without inventing its own definition of clean.
5. 'Consider performance implications of every change.' Reason: speculative. No incident generated this. It was likely copied from a style guide. It fires on every session and produces boilerplate performance caveats that waste output tokens.

TIGHTEN LIST (3 rules):
1. 'Handle errors properly.' Revise to: 'Use typed error responses. Never empty catch blocks. Log errors with console.error(err) before rethrowing.'
2. 'Keep functions small.' Revise to: 'Split any function over 40 lines unless it is a pure data transformation or a single-responsibility switch statement.'
3. 'Test edge cases.' Revise to: 'For any function that accepts user input, write at least one test for: empty input, null/undefined, and max-length input.'

After deletions: 17 rules. Estimated token savings per session: 380-420 tokens.

Paste this into Claude:

I want to audit my CLAUDE.md for speculative rules: rules I wrote as general best practices before I had a real failure that needed them. Here is my full CLAUDE.md: [paste it]. For each rule, answer: can I name a specific session incident that generated this rule? If not, it is probably speculative. Flag all speculative rules, explain why they are lower-value than provenance-backed rules, and give me a recommendation: delete it, or keep it only if I can find the session that generated it within 5 minutes of looking.

What good looks like:

• You identified which rules have clear provenance and which do not
• You deleted or flagged every speculative rule that you cannot trace to a real incident
• You understand the difference between a provenance rule and a best-practice rule
• You added a short provenance note to at least two rules you kept, so future-you knows where they came from

What a good response looks like:

Provenance audit of your 17 remaining rules.

CLEAR PROVENANCE (9 rules, keep):
- 'Never use aws-sdk v2. Use @aws-sdk/client-* v3 modules only.' Provenance: traceable. This pattern has strong provenance smell (specific package version, direct negative instruction). Likely generated by a real re-introduction incident.
- 'Do not import Lodash. Use native Array methods instead.' Same pattern. Keep.
- 'Never use empty catch blocks. Log and rethrow.' Keep. Specific negative pattern + two explicit alternatives.

SPECULATIVE (8 rules, flagged):
- 'Follow SOLID principles in all class design.' Speculative. SOLID is a blog-post best practice. No incident generated this. No specific behavior is prescribed. Delete or find the session within 5 minutes.
- 'Use semantic HTML elements.' Speculative. Copied from an accessibility guide. You have no failing accessibility test that generated this. If you cannot find the incident, delete it.
- 'Prefer composition over inheritance.' Speculative. Classic best practice. Has never fired productively in your workflow because your codebase barely uses classes. Delete.
- 'Always document API endpoints.' Speculative. No session where missing docs caused a real problem. If docs matter to your workflow, replace with: 'Every new API route must have a JSDoc comment with: method, path, required params, and response shape.'

Speculative rules in your file: 8 of 17 (47%). Healthy target: under 20%. Recommended action: delete 6, convert 2 to specific instructions.