claude-foundations/improvements/claude-md-refinements.md

CLAUDE.md Refinements

Why This Matters

CLAUDE.md is the agent's "constitution." Community consensus is clear: bloated files cause Claude to ignore instructions. The sweet spot is under 200 lines / 1,000 tokens. Your current file is 187 lines — right at the boundary.

Current State

• 187 lines in ~/dev/claude/CLAUDE.md
• Contains project conventions, secrets rules, scripting standards, process principles
• Well-structured but could benefit from pruning and restructuring

What To Keep (High Value)

These earn their place because Claude cannot infer them:

• Bash commands with specific flags (build, test, deploy recipes)
• Code style rules that differ from defaults (only deviations)
• Architectural decisions specific to your project
• Common gotchas and non-obvious behaviours
• Testing instructions and preferred test runners
• Repository etiquette (branch naming, commit format)
• Lessons from past mistakes

What To Remove or Move

These can be pruned because Claude discovers them automatically or they belong elsewhere:

Item	Why Remove	Where It Goes
Folder structure descriptions	Claude reads directories	Nowhere — discoverable
Technology stack	Visible in package.json/imports	Nowhere — discoverable
Generic advice ("write clean code")	No actionable signal	Delete
Formatting/linting rules	Deterministic tools do this better	Hooks
Detailed process that's project-specific	Only relevant in that project	Project-level CLAUDE.md or skills
Secrets rules (repeated across projects)	Cross-project concern	Global ~/.claude/CLAUDE.md
Gitea/SSH conventions	Cross-project concern	Global ~/.claude/CLAUDE.md

Structural Improvements

Guidance Over Prohibition

Change "Never do X" to "Prefer Y instead of X." Claude follows positive guidance better than negative constraints.

Before: "Never use placeholder values with -e for vars that template config files" After: "Always source template variables from inventory.yml, not ad-hoc -e flags"

Add Verification Commands

Boris from the Claude Code team says giving Claude explicit ways to check its own work "2-3x's output quality." Add a section listing verification commands per project type:

• helm template for Helm values
• kustomize build for overlays
• curl --resolve for endpoint testing
• Test commands, lint commands

Use Emphasis for Critical Rules

Adding "IMPORTANT" or "YOU MUST" measurably improves adherence for rules that matter most. Use sparingly — if everything is critical, nothing is.

Attention Distribution

Claude focuses most on the beginning and end of CLAUDE.md. Middle sections get less attention. Put your most critical rules at the top.

Maintenance Cadence

• Review every 2-3 weeks (ask Claude to audit and suggest improvements)
• Growth pattern: catch mistake -> add rule -> promote frequent rules to permanent status
• Prune aggressively: if a rule hasn't prevented an issue in a month, remove it
• Each model release, review and remove rules the new model handles natively