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/hooks-and-automation.md

@@ -0,0 +1,58 @@
+# Hooks & Automation
+
+## Why This Matters
+
+Hooks are the #1 "why didn't I do this sooner" recommendation across the community. Unlike CLAUDE.md rules (which Claude can forget mid-session), hooks **always execute**. They provide deterministic guardrails around non-deterministic AI behaviour.
+
+Key principle: "Never send an LLM to do a linter's job. LLMs are expensive and slow compared to traditional linters."
+
+## Current State
+
+- No hooks configured in `~/.claude/settings.json`
+- Formatting/linting rules live in CLAUDE.md as prose instructions
+
+## Community Recommendations
+
+### PostToolUse: Auto-Formatting
+
+Run formatters automatically after every `Edit`/`Write` tool call. Eliminates all formatting rules from CLAUDE.md.
+
+- `prettier --write` for JS/TS/JSON/YAML/MD
+- `shfmt -w` for shell scripts
+- `ruff format` for Python
+- Plugin: `ryanlewis/claude-format-hook` supports multi-language detection
+
+Configuration goes in `~/.claude/settings.json` under `hooks.PostToolUse`.
+
+### PreToolUse: Security Gates
+
+Block dangerous operations before they execute:
+
+- Block writes to `.env`, `.key`, `.pem`, `secrets/`, lockfiles
+- Block destructive commands (`rm -rf /`, `dd`, `mkfs`)
+- Scan for API keys/credentials in file content before writes
+- Block commits that include sensitive file patterns
+
+### PreToolUse: Commit Validation
+
+Wrap `Bash(git commit)` with test/lint validation. Only allow commits if checks pass. Forces Claude into "test-and-fix" loops until the build is green. This is considered the single most effective quality gate.
+
+Important: **Don't block at write time** — blocking on `Edit`/`Write` confuses Claude mid-plan. Validate at commit time instead.
+
+### PreCompact: Transcript Backup
+
+Save conversation transcript before auto-compaction so context is never lost. Creates a timestamped backup in a known location. Pairs well with the auto-memory system.
+
+Reference: https://yuanchang.org/en/posts/claude-code-auto-memory-and-hooks/
+
+### Notification Hook
+
+Desktop notifications when Claude finishes a long task or needs input. Useful when running background agents.
+
+Plugin: `CC Notify` from awesome-claude-code.
+
+## Anti-Patterns
+
+- Don't add too many hooks — each one adds latency to every tool call
+- Don't block on `Edit`/`Write` for linting — do it on `PostToolUse` (non-blocking) or at commit time
+- Don't duplicate hook logic in CLAUDE.md — if a hook handles it, remove the prose rule