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/session-and-context-management.md

@@ -0,0 +1,38 @@
+# Session & Context Management
+
+## Why This Matters
+
+Context is the most precious resource in a Claude Code session. The 200k token window seems large but fills fast — especially with MCP tools, long files, and multi-step tasks. Community consensus: managing context deliberately is a 2-3x productivity multiplier.
+
+## Current State
+
+- No explicit context management practices documented
+- Auto-memory system is configured (built-in)
+- No compaction hooks
+
+## Key Practices
+
+### Session Hygiene
+- **Use `/clear` between unrelated tasks.** A fresh session costs ~20k tokens (10% of budget), leaving ~180k for work. Polluted context from failed approaches actively degrades output quality.
+- **After two failed corrections, `/clear` and start fresh.** Context is now polluted with failed approaches. Write a better initial prompt instead.
+- **One task per session.** The "kitchen sink session" (start task A, ask about B, return to A) is a documented anti-pattern.
+
+### Context Budgeting
+- **Use `/context` to audit token usage.** MCP tools consume context even when unused. Browser automation tools alone can eat 8-30% of available context.
+- **Remove unused MCP servers** from settings when not actively needed.
+- **Compact proactively at 60-70% usage** — don't wait for auto-compact.
+
+### Extended Thinking
+- **Only `ultrathink` activates extended thinking** as of Claude Code v2.0.0. Previous keywords like "think" or "think hard" no longer work.
+- Use `ultrathink` for complex reasoning tasks, architectural decisions, and debugging subtle issues.
+
+### Compaction Strategy
+- Default reserves 32k tokens (22.5% of 200k) for auto-compact buffer.
+- Setting `CLAUDE_CODE_MAX_OUTPUT_TOKENS` to 64k increases the buffer to ~40%.
+- **PreCompact hook** (see hooks-and-automation.md) saves transcript before compaction.
+- Pair with auto-memory: gradual learning via memory, emergency snapshots via PreCompact hooks.
+
+### Handoff Between Sessions
+- Before ending a long session, create a handoff document: goals, progress, blockers, next steps.
+- A `/handoff` or `/catchup` skill (see skills-and-progressive-disclosure.md) automates this.
+- "Context is like milk — keep it fresh and condensed."