Initial commit: Claude Code foundations and improvements research

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>

improvements/claude-md-refinements.md

@@ -0,0 +1,65 @@
+# 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