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/mcp-servers.md

@@ -0,0 +1,42 @@
+# MCP Servers
+
+## Why This Matters
+
+MCP (Model Context Protocol) servers extend Claude Code with external tool integrations. Community consensus: "If you're not using MCPs, you're driving a Ferrari in first gear." However, each registered MCP consumes context tokens even when unused, so be selective.
+
+## Current State
+
+- No MCP servers configured
+
+## Must-Have (Community Consensus)
+
+### Context7
+
+The single most-recommended MCP server. Provides real-time, version-specific documentation for any library/framework. Solves the knowledge-cutoff problem — Claude gets accurate docs for the exact version you're using.
+
+Particularly valuable for:
+- Helm chart values schemas (change between versions)
+- Kubernetes API changes
+- Any rapidly-evolving ecosystem
+
+### Sequential Thinking
+
+Structured problem-solving for complex architectural decisions. Described as "like having a senior architect who thinks before coding." Useful for planning phases.
+
+## Worth Considering
+
+| MCP Server | Purpose | Relevance |
+|---|---|---|
+| **Playwright** | Browser automation, UI testing, screenshot capture | Useful if doing web projects |
+| **GitHub/Gitea** | PR/issue management from terminal | Would need a Gitea-compatible MCP |
+| **Supabase** | Database ops, migrations, SQL queries | If using Supabase |
+
+## Key Insights
+
+- **Start with 2-3 MCPs, not all of them.** Each one adds to context overhead.
+- **MCP Tool Search (lazy loading)** reduces context usage by up to 95% — register many, only load what's needed.
+- **Prefer Skills over MCPs for stateless tools.** MCPs are best for stateful environments (browser sessions, database connections, auth boundaries). Stateless CLI wrappers are better as Skills.
+
+## Migration Pattern
+
+The community is trending toward moving stateless tools from MCPs to simple CLIs documented in SKILL.md files. The "wrapper pattern" uses commands as thin entry points (~93 tokens) + skills as full implementations loaded on-demand, reducing startup context by ~64%.