a4967df815
Conventions, community best practices research (Sept 2025 - March 2026), and prioritized improvement backlog for Claude Code workflows. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
66 lines
3.0 KiB
Markdown
66 lines
3.0 KiB
Markdown
# 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
|