# 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