From a4967df815e4291be94562b2cf6056679b3c1eda Mon Sep 17 00:00:00 2001 From: Paul O'Reilly Date: Thu, 12 Mar 2026 23:02:54 +1300 Subject: [PATCH] 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 --- CLAUDE.md | 187 ++++++++++++++++++ IMPROVEMENTS.md | 22 +++ TODO.md | 53 +++++ improvements/ci-cd-integration.md | 34 ++++ improvements/claude-md-refinements.md | 65 ++++++ improvements/community-resources.md | 41 ++++ improvements/global-configuration.md | 42 ++++ improvements/hooks-and-automation.md | 58 ++++++ improvements/mcp-servers.md | 42 ++++ improvements/multi-agent-patterns.md | 46 +++++ improvements/planning-and-workflow.md | 44 +++++ improvements/plugins-and-language-servers.md | 34 ++++ .../session-and-context-management.md | 38 ++++ .../skills-and-progressive-disclosure.md | 59 ++++++ 14 files changed, 765 insertions(+) create mode 100644 CLAUDE.md create mode 100644 IMPROVEMENTS.md create mode 100644 TODO.md create mode 100644 improvements/ci-cd-integration.md create mode 100644 improvements/claude-md-refinements.md create mode 100644 improvements/community-resources.md create mode 100644 improvements/global-configuration.md create mode 100644 improvements/hooks-and-automation.md create mode 100644 improvements/mcp-servers.md create mode 100644 improvements/multi-agent-patterns.md create mode 100644 improvements/planning-and-workflow.md create mode 100644 improvements/plugins-and-language-servers.md create mode 100644 improvements/session-and-context-management.md create mode 100644 improvements/skills-and-progressive-disclosure.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..704ae6b --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,187 @@ +# CLAUDE.md — General Project Guidelines + +## Session Start + +1. **Immediately** (without waiting for user input) list the project directories under `~/dev/claude/` (excluding `secrets/`) and present a numbered menu like: + + > What are we working on today? + > + > 1. **cluster-bootstrap** — Kubernetes homelab cluster + > 2. **custom-claude-skills** — Reusable Claude Code skills + > ... + > N-1. **No project right now** — just chat + > N. **New project!** — start something new + + Scan the directories at runtime so the list is always current. Include a brief description if the project has a CLAUDE.md or README.md you can glean one from. + +2. Based on the user's choice: + - **Existing project**: `cd` into the directory, read all `.md` files, and read `~/dev/claude/secrets/` (read-only reference — review every file to refresh context). Ask clarifying questions if anything is unclear or incomplete, and note context in MEMORY.md. + - **No project right now**: Do nothing further — just respond normally. + - **New project!**: Follow the "New Projects" section below. Also read `~/dev/claude/secrets/` as above. + +## Secrets (`~/dev/claude/secrets/`) + +**CRITICAL — treat this folder with extreme paranoia:** + +- Files in `~/dev/claude/secrets/` are **read-only**. Never edit them. +- **Never** copy, echo, write, or reproduce secret values into any other file — not MEMORY.md, not CLAUDE.md, not commit messages, not scripts, not tool output, nowhere. +- **Never** include secret values in git commits, diffs, or changelogs of any project. +- **Never** pass secret values as command-line arguments (visible in `ps` output). Use `@file` references, environment variables sourced at runtime, or stdin. +- When a task requires a secret, read it at execution time from the secrets folder and use it ephemerally. Do not cache or persist the value. +- It is acceptable to reference the **existence** of a secret file (e.g., "credentials are in `~/dev/claude/secrets/gitea/ai_enablement`") but never its contents. + +## New Projects + +If this is a new project: + +1. Create a new directory under `~/dev/claude//` +2. **Ask the user** which Gitea user/org the repo should be created under (e.g., `homelab`, a personal user, etc.) before setting up the remote +3. Create the initial standard files: + - **CLAUDE.md** — Project-specific architecture, conventions, repo structure, and working instructions for Claude + - **MEMORY.md** — Persistent learnings, gotchas, reflections, and process improvements + - **FUTURE.md** — Ideas and improvements not on the active roadmap (Problem/Idea/Open questions/Depends on format) + - **README.md** — Human-readable overview, quick start, milestones, and scripts reference +4. Parse the other CLAUDE.md files from sibling project folders in `~/dev/claude/`, and based on the type of project being considered, bring over related practices, guidelines, and learnings + +## Source Control + +- All projects are hosted on **Gitea** (`gitea.oreillyit.nz`) as the primary remote — prefer this hostname over `gitea.homelab.internal` (same instance, but the public name enables external access) +- Migrate existing remotes from `gitea.homelab.internal` to `gitea.oreillyit.nz` when convenient +- AI-focused projects go under the **`skynet`** org; infrastructure projects under **`homelab`** +- SSH workflows preferred. SSH config uses host aliases per Gitea user: + - `gitea.oreillyit.nz-homelab` → authenticates as `cluster-administrator` (key: `~/.ssh/gitea-cluster-admin`) + - `gitea.oreillyit.nz-ai-enablement` → authenticates as `ai_enablement` (key: `~/.ssh/gitea.ai-enablement`) +- Git remote URLs use the alias: `git@gitea.oreillyit.nz-:/.git` + - Example: `git@gitea.oreillyit.nz-ai-enablement:skynet/custom-claude-skills.git` +- Optionally push-mirror to GitHub for public visibility +- Use meaningful commit messages; prefer small, focused commits over large batches +- Enable pre-commit hooks where appropriate (secret detection, linting, formatting) +- Never commit secrets in plaintext — use SOPS + age or equivalent encryption + +## Documentation Standards + +Every project maintains four core markdown files: + +### CLAUDE.md (per-project) +The primary reference for Claude sessions. Should contain: +- Project overview and architecture +- Repository structure (keep updated as the project evolves) +- Key design decisions with rationale +- Conventions and coding standards +- Environment details (IPs, URLs, credentials references) +- Common operations / how-to recipes + +### MEMORY.md (Tiered Memory System) +Long-running projects accumulate significant context. To keep MEMORY.md useful rather than bloated, use a **tiered memory** structure: + +**MEMORY.md** is a **thin index only** — one-line descriptions with links to topic files in `memory/`. No content lives in MEMORY.md itself. Think of it as a card catalog. Keep it under ~50 lines. + +**memory/** contains the actual content, split by topic: +- `memory/project-status.md` — Current milestone, what's next, blockers +- `memory/network.md` — IPs, VIPs, subnets, topology +- `memory/gotchas-.md` — Gotchas grouped by technology (e.g., `gotchas-cilium.md`, `gotchas-authelia.md`) +- `memory/process-lessons.md` — How-to-work-with-this-repo lessons for Claude +- `memory/m-reflection.md` — One file per milestone reflection (these are time-bound, so per-file is natural) +- `memory/decisions.md` — Architecture and design decisions made during planning + +**Principles:** +- **Split by topic, not by time.** A Cilium gotcha belongs in `gotchas-cilium.md` whether discovered in M5 or M8. +- **Milestone reflections are the exception** — inherently time-bound, one file per milestone. +- **Index descriptions matter.** They're used to decide what to read. "Cilium L2/LB gotchas and externalTrafficPolicy quirks" beats "cluster stuff". +- **Prune aggressively.** If a gotcha was fixed (e.g., chart version upgraded past the bug), delete it. Stale memory is worse than no memory. +- **Each memory file should be self-contained and greppable.** Include enough context that the file makes sense on its own. +- **Deduplicate with CLAUDE.md.** Conventions and patterns that are stable should live in CLAUDE.md. Memory files are for learnings, gotchas, and reflections that accumulate over time. If something in memory has graduated to a stable convention, move it to CLAUDE.md and remove it from memory. + +**When reading memory at session start:** Read MEMORY.md (the index), then selectively read topic files relevant to the current task. Don't read all memory files unless doing a broad review. + +**When writing memory after a milestone:** Create the reflection file, update any affected topic files (new gotchas, updated status), and update the index. + +### FUTURE.md +Backlog of improvement ideas, each with: +- **Problem:** What's painful or manual today +- **Idea:** What the improvement looks like +- **Open questions:** Unknowns to research before starting +- **Depends on:** Other items or milestones that should come first + +### README.md +Human-readable project documentation: +- Architecture summary +- Quick start / setup instructions +- Milestone table with status +- Scripts section listing every script with purpose and usage + +## Milestones + +Break projects into numbered milestones (M1, M2, ...). Every milestone completion MUST include: + +1. **Verification script** (`scripts/verify-m.sh`) — automated checks confirming all milestone outcomes. Scripts should be idempotent, non-destructive, and return non-zero on failure. Use colour output (green/red) for pass/fail. +2. **Milestone reflection** in `memory/m-reflection.md` — review the entire conversation and capture: + - Process improvements (what slowed us down, wrong assumptions, backtracking) + - Key knowledge for reproduction (gotchas, version quirks, debugging detours) + - Scripts and automation opportunities (repeated command sequences → scripts) + - Future improvement ideas (add to FUTURE.md) + - Update affected topic files in `memory/` (new gotchas, updated status) and the MEMORY.md index +3. **Updated README.md** — scripts section, milestone table, any new setup steps +4. **Updated CLAUDE.md** — repo structure, conventions, new patterns discovered + +## Validate Before Deploying + +Every new config, manifest, or template should be validated locally before deploying. The target environment is not a test environment — each deploy-crash-fix cycle wastes time and clutters Git history. Batch fixes locally, push once. + +Examples: +- `helm template` for Helm values +- `kustomize build` for Kustomize apps +- `docker run validate-configuration` for app configs +- `docker inspect` for unfamiliar container images +- Lint/typecheck/test for application code +- `curl --resolve` for the full request chain after deployment + +## Version Management + +- Use the latest stable version of dependencies unless pinned for a reason +- Verify versions from live sources (`helm search repo`, upstream docs, package registries) — don't rely on memory +- Document the reason in a comment if a version is intentionally pinned below latest +- Check compatibility matrices before upgrading (e.g., Talos ↔ Kubernetes, framework ↔ runtime) + +## Secrets Management + +- SOPS + age is the standard encryption tool across all projects +- The `.sops.yaml` at the repo root defines path-based encryption rules +- Filenames containing `secret` trigger SOPS encryption via pre-commit hooks +- Non-secret files must NOT contain `secret` in their name +- Never pass secrets via command-line arguments (visible in `ps` output) — use `@file` references or environment variables +- Keep unencrypted secrets in `local_secrets/` (gitignored) + +## Scripting Conventions + +- All scripts live in `scripts/` and run from the repository root +- Scripts should be idempotent and safe to re-run +- Use colour output for pass/fail indicators in verification scripts +- Verification scripts should check for default/insecure credentials and print remediation instructions on failure +- Scripts should exit non-zero on failure so `&&` chains work naturally + +## Process Principles + +These are hard-won lessons from real project work: + +- **Validate locally, deploy once.** Don't use the live environment as a test bed. Catch errors with local validation tools before pushing. +- **Check before you act.** Before writing firewall/network rules, check actual routing (`ip route get`). Before running config management with variables, ensure values are real, not placeholders. Before assuming a container has a shell, `docker inspect` it. +- **Test the full chain immediately.** After wiring up a new service or endpoint, test end-to-end from the user's perspective right away. Don't assume intermediate steps working means the whole chain works. +- **Verify scripts should be environment-resilient.** Avoid needing sudo or special access. Test from the accessible side of a connection. Use `curl --resolve` to bypass DNS/proxy layers when testing direct connectivity. +- **Automate repeated sequences.** If you run the same 3+ commands in sequence more than once, it should become a script. +- **Reflect after milestones.** Don't just finish — review what happened, what went wrong, what can be improved. Write it down so future sessions benefit. + +## Ansible Conventions (where applicable) + +- Roles follow standard structure: `tasks/main.yml`, `templates/*.j2`, `handlers/main.yml` +- Jinja2 templates have `.j2` extension and include a "managed by Ansible" header comment +- Variables that need customisation go in `inventory.yml`, not scattered across role defaults +- Always pass `-i inventory.yml` explicitly or run from the directory containing `ansible.cfg` +- Never use placeholder values with `-e` for vars that template config files + +## Helm Chart Conventions (where applicable) + +- Always validate values against the chart schema before committing +- Run `helm show values / --version ` to check actual structure +- Schemas change between versions — field names and nesting can differ from docs or online examples +- A quick `helm template` test locally catches schema errors before deployment diff --git a/IMPROVEMENTS.md b/IMPROVEMENTS.md new file mode 100644 index 0000000..af77962 --- /dev/null +++ b/IMPROVEMENTS.md @@ -0,0 +1,22 @@ +# Improvements Index + +Research from Claude community (Reddit, HN, blogs, GitHub) — Sept 2025 to March 2026. +Each topic file contains context, community consensus, and actionable suggestions. + +## Topics + +- [Hooks & Automation](improvements/hooks-and-automation.md) — PreToolUse/PostToolUse hooks, auto-formatting, security gates, commit validation +- [MCP Servers](improvements/mcp-servers.md) — Context7, Sequential Thinking, and other high-value MCP integrations +- [Skills & Progressive Disclosure](improvements/skills-and-progressive-disclosure.md) — Building skills for context-on-demand, reducing token waste, recommended community skills +- [CLAUDE.md Refinements](improvements/claude-md-refinements.md) — What to add, remove, and restructure based on community best practices +- [Global Configuration](improvements/global-configuration.md) — Cross-project defaults via ~/.claude/CLAUDE.md and settings.json +- [Plugins & Language Servers](improvements/plugins-and-language-servers.md) — LSP integration, superpowers, commit-commands, pr-review-toolkit +- [Session & Context Management](improvements/session-and-context-management.md) — Context hygiene, compaction strategies, token budgeting, ultrathink +- [Planning & Workflow](improvements/planning-and-workflow.md) — Plan Mode, TDD loops, verification-driven development +- [Multi-Agent Patterns](improvements/multi-agent-patterns.md) — Subagents, git worktrees, orchestration tools, when (not) to use them +- [CI/CD Integration](improvements/ci-cd-integration.md) — Headless mode, GitHub Actions, automated PR review, cross-model validation +- [Community Resources](improvements/community-resources.md) — Curated repos, guides, and references worth bookmarking + +## Prioritised Actions + +See [TODO.md](TODO.md) for the top 10 items to implement, ranked by impact and effort. diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..d504537 --- /dev/null +++ b/TODO.md @@ -0,0 +1,53 @@ +# TODO: Top 10 Improvements + +Prioritised by impact and effort. Each item references its detailed topic file in `improvements/`. + +## 1. Configure PostToolUse auto-formatting hook +**Impact: High | Effort: Low** +Auto-format code after every Edit/Write. Removes all formatting rules from CLAUDE.md, saves tokens, and guarantees consistent output. Start with `shfmt` for shell and expand. +See: [hooks-and-automation.md](improvements/hooks-and-automation.md) + +## 2. Create global `~/.claude/CLAUDE.md` +**Impact: High | Effort: Low** +Move cross-project conventions (Gitea, secrets, SSH, commit format, response style) out of the project-level CLAUDE.md. Reduces duplication and frees ~40 lines from every project file. +See: [global-configuration.md](improvements/global-configuration.md) + +## 3. Configure PreToolUse security hook +**Impact: High | Effort: Low** +Block writes to secrets files, `.env`, lockfiles, and destructive commands. Deterministic protection vs. hoping Claude remembers the CLAUDE.md rule. +See: [hooks-and-automation.md](improvements/hooks-and-automation.md) + +## 4. Install Context7 MCP server +**Impact: High | Effort: Medium** +Real-time, version-specific documentation for Helm charts, Kubernetes APIs, and any library. Eliminates knowledge-cutoff guesswork — particularly valuable for cluster-bootstrap. +See: [mcp-servers.md](improvements/mcp-servers.md) + +## 5. Build `/catchup` skill +**Impact: Medium | Effort: Low** +Reads git diff, changed files, and relevant memory when resuming work. Automates the manual "what changed since last session?" flow. +See: [skills-and-progressive-disclosure.md](improvements/skills-and-progressive-disclosure.md) + +## 6. Build `/validate` skill +**Impact: Medium | Effort: Low** +Codifies the "validate before deploying" principle into a single command. Runs helm template, kustomize build, linting as appropriate. Prevents deploy-crash-fix cycles. +See: [skills-and-progressive-disclosure.md](improvements/skills-and-progressive-disclosure.md) + +## 7. Install Language Server plugin +**Impact: High | Effort: Medium** +`boostvolt/claude-code-lsps` gives Claude real-time types, go-to-definition, and find-references. "The single biggest productivity gain" per community consensus. +See: [plugins-and-language-servers.md](improvements/plugins-and-language-servers.md) + +## 8. Add PreCompact transcript backup hook +**Impact: Medium | Effort: Low** +Save conversation transcript before auto-compaction. Pairs with auto-memory to ensure no context is lost during long sessions. +See: [hooks-and-automation.md](improvements/hooks-and-automation.md) + +## 9. Prune and restructure project CLAUDE.md +**Impact: Medium | Effort: Medium** +After creating the global file (item 2), prune the project CLAUDE.md. Move discoverable info out, rewrite prohibitions as positive guidance, add verification commands section, put critical rules at the top. +See: [claude-md-refinements.md](improvements/claude-md-refinements.md) + +## 10. Adopt Plan Mode as default workflow +**Impact: High | Effort: Zero** +Use Shift+Tab twice before any non-trivial task. Iterate on the plan before executing. Boris from Anthropic says this "easily 2-3x's results." No tooling needed — just a habit change. +See: [planning-and-workflow.md](improvements/planning-and-workflow.md) diff --git a/improvements/ci-cd-integration.md b/improvements/ci-cd-integration.md new file mode 100644 index 0000000..c6d7139 --- /dev/null +++ b/improvements/ci-cd-integration.md @@ -0,0 +1,34 @@ +# CI/CD Integration + +## Why This Matters + +60%+ of teams adopting Claude Code now use headless mode (`claude -p`) for automation. The most productive pattern is interactive Claude for architecture/design while delegating routine reviews and migrations to headless CI. + +## Current State + +- No CI/CD integration with Claude Code +- Projects hosted on Gitea (not GitHub, so GitHub Actions patterns need adaptation) + +## Patterns + +### Headless Mode (`claude -p`) +Run Claude non-interactively in scripts or CI pipelines: +- `claude -p "Generate changelog from recent commits" --output-format json` +- `claude -p "Review this diff for security issues" < diff.txt` +- Useful for automated PR review, changelog generation, migration scripts + +### Automated PR Review +Claude reviews PRs automatically on open/update (15-45 seconds per review). Would need a Gitea webhook + runner setup rather than GitHub Actions. + +### Cross-Model Validation +Advanced pattern: global CLAUDE.md tells Claude to send diffs to Gemini/Codex for independent validation before committing. "High catch rate" reported by users. + +### Compounding Engineering +Autonomous CI where Claude handles routine tasks (dependency updates, code style fixes, doc generation) with manual review before merging. Creates a self-improving flywheel. + +## Gitea Considerations + +Most community examples use GitHub Actions with `@claude` mentions. For Gitea: +- Gitea Actions (compatible with GitHub Actions syntax) could run headless Claude +- Webhook-based triggers for PR review +- Would need to evaluate Gitea MCP compatibility or build a simple API wrapper skill diff --git a/improvements/claude-md-refinements.md b/improvements/claude-md-refinements.md new file mode 100644 index 0000000..ed0e85f --- /dev/null +++ b/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 diff --git a/improvements/community-resources.md b/improvements/community-resources.md new file mode 100644 index 0000000..45b42bd --- /dev/null +++ b/improvements/community-resources.md @@ -0,0 +1,41 @@ +# Community Resources + +## Curated Repositories + +| Repository | Description | +|---|---| +| [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) | The most comprehensive curated list of skills, hooks, commands, orchestrators, and tools | +| [awesome-claude-skills](https://github.com/travisvn/awesome-claude-skills) | Curated skills catalogue | +| [ykdojo/claude-code-tips](https://github.com/ykdojo/claude-code-tips) | 45 practical tips from basics to advanced, including custom skills | +| [claude-code-best-practice](https://github.com/shanraisshan/claude-code-best-practice) | Community best practices guide | +| [claude-code-showcase](https://github.com/ChrisWiles/claude-code-showcase) | Reference project with hooks, skills, agents, commands, and GitHub Actions | +| [VoltAgent/awesome-claude-code-subagents](https://github.com/VoltAgent/awesome-claude-code-subagents) | 100+ specialised subagent definitions | +| [solatis/claude-config](https://github.com/solatis/claude-config) | The Claude Code creator's personal setup and philosophy | + +## Guides and Articles + +| Resource | Key Insight | +|---|---| +| [Official Best Practices](https://code.claude.com/docs/en/best-practices) | Authoritative source, keep CLAUDE.md under 1,000 tokens | +| [HumanLayer Blog](https://www.humanlayer.dev/blog/writing-a-good-claude-md) | Under 60 lines ideal, 300 lines max | +| [alexop.dev Progressive Disclosure](https://alexop.dev/posts/stop-bloating-your-claude-md-progressive-disclosure-ai-coding-tools/) | Skills as context-on-demand, 82% token savings | +| [builder.io Claude MD Guide](https://www.builder.io/blog/claude-md-guide) | Layered configuration strategy | +| [okhlopkov.com Claude Code Setup](https://okhlopkov.com/claude-code-setup-mcp-hooks-skills-2026/) | MCP, hooks, and skills setup walkthrough | +| [blog.sshh.io Claude Code Features](https://blog.sshh.io/p/how-i-use-every-claude-code-feature) | Comprehensive feature walkthrough | +| [Boris (Anthropic) HN Tips](https://news.ycombinator.com/item?id=46256606) | Plan Mode 2-3x's results, verification 2-3x's quality | +| [24 Claude Code Tips Advent Calendar](https://dev.to/oikon/24-claude-code-tips-claudecodeadventcalendar-52b5) | Daily tips covering breadth of features | + +## Community Scale + +- **r/ClaudeCode**: 96K members, 4,200+ weekly contributors (3x r/Codex) +- **r/ClaudeAI**: Broader Claude discussion, usage limits are the dominant topic +- **r/vibecoding**: 89K members, rapid prototyping with Claude Code +- Claude Code generates 4x more Reddit discussion than competing tools + +## Plugins and Hook Repos + +| Resource | Description | +|---|---| +| [ryanlewis/claude-format-hook](https://github.com/ryanlewis/claude-format-hook) | Multi-language auto-formatting hook | +| [boostvolt/claude-code-lsps](https://github.com/boostvolt/claude-code-lsps) | Language Server integration for Python, TS, Rust, Go | +| [obra/superpowers](https://github.com/obra/superpowers) | 20+ production-proven workflow skills | diff --git a/improvements/global-configuration.md b/improvements/global-configuration.md new file mode 100644 index 0000000..2b05057 --- /dev/null +++ b/improvements/global-configuration.md @@ -0,0 +1,42 @@ +# Global Configuration + +## Why This Matters + +A global `~/.claude/CLAUDE.md` provides cross-project defaults, eliminating duplication across project-level files. The community has converged on a layered configuration strategy. + +## Current State + +- No global `~/.claude/CLAUDE.md` exists +- Cross-project conventions (Gitea, secrets, SSH) are in the project-level `~/dev/claude/CLAUDE.md` +- `~/.claude/settings.json` contains only `{"model": "opus"}` + +## Layered Configuration Model + +| Layer | File | Scope | Checked In | +|---|---|---|---| +| Personal defaults | `~/.claude/CLAUDE.md` | All projects | No | +| Project shared | `./CLAUDE.md` | Team, per-project | Yes | +| Directory-specific | `./subdir/CLAUDE.md` | Loaded when working in subdir | Yes | +| Local overrides | `CLAUDE.local.md` | Machine-specific, gitignored | No | +| Path-scoped rules | `.claude/rules/*.md` | Conditional on file patterns | Yes | +| On-demand knowledge | `.claude/skills/*/SKILL.md` | Loaded only when relevant | Optional | + +## Suggested Global CLAUDE.md Content + +Move these from the project-level file to global: + +- **Gitea conventions** — SSH aliases, remote URL format, org structure +- **Secrets folder rules** — read-only, never copy values, never pass as CLI args +- **Commit message format** — meaningful messages, small focused commits +- **Session behaviour** — "Do not allow implicit decisions — confirm with the user" +- **Response style** — concise, no trailing summaries, no unnecessary emojis +- **SOPS + age** as the standard encryption tool +- **Documentation standards** that apply across all projects (CLAUDE.md, MEMORY.md, FUTURE.md, README.md) + +## Settings.json Improvements + +Beyond `model`, consider: + +- Hook definitions (see hooks-and-automation.md) +- MCP server registrations (see mcp-servers.md) +- Permission preferences for common tool calls diff --git a/improvements/hooks-and-automation.md b/improvements/hooks-and-automation.md new file mode 100644 index 0000000..fa433ea --- /dev/null +++ b/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 diff --git a/improvements/mcp-servers.md b/improvements/mcp-servers.md new file mode 100644 index 0000000..c56e76a --- /dev/null +++ b/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%. diff --git a/improvements/multi-agent-patterns.md b/improvements/multi-agent-patterns.md new file mode 100644 index 0000000..da4b172 --- /dev/null +++ b/improvements/multi-agent-patterns.md @@ -0,0 +1,46 @@ +# Multi-Agent Patterns + +## Why This Matters + +Subagents are the most powerful tool for managing context — they explore in a separate context window, keeping the main conversation clean. However, multi-agent workflows are overkill for 95% of tasks and currently expensive. + +## Current State + +- Built-in subagent support available (Explore, Plan, general-purpose) +- No custom orchestration +- No multi-terminal patterns + +## Patterns (Simplest to Most Complex) + +### 1. Built-in Subagents (Already Available) +Delegate research, exploration, and file searches to subagents. They run in separate context windows and return summaries. This is the easiest win — just use the Agent tool more deliberately. + +### 2. Git Worktrees for Parallel Work +Use `git worktree` to let multiple Claude instances work on separate branches without conflicts. Each instance has its own working directory but shares the git history. + +### 3. The 4-Terminal Pattern +Simple but effective: 4 specialised Claude Code agents in separate VS Code / tmux terminals with distinct roles (e.g., planner, implementer, tester, reviewer). Often beats complex orchestrators. + +### 4. Master-Clone Architecture +Rather than custom subagents with rigid workflows, use Claude's built-in `Task(...)` to spawn general-agent clones. Put key context in CLAUDE.md and let the agent orchestrate delegation dynamically. + +### 5. Container Isolation +Local Claude Code controls another instance inside a Docker container via tmux — sandboxed autonomous worker for risky/destructive operations. + +## Orchestration Tools + +| Tool | Description | +|---|---| +| **Claude Squad** | Terminal app managing multiple Claude Code agents in separate workspaces | +| **Happy Coder** | Spawn and control multiple Claude Codes with push notifications | +| **Claude Swarm** | Launch a Claude Code session connected to a swarm of other agents | +| **Claude MPM** | 47+ specialised agents with PM orchestration and automatic task routing | + +## When NOT to Use Multi-Agent + +- Simple, single-file changes +- Tasks that take less than a few minutes +- When context window is not a constraint +- When the coordination overhead exceeds the work itself + +The community consensus: master the single-agent workflow first. Multi-agent adds complexity and cost that only pays off for genuinely parallel, independent workstreams. diff --git a/improvements/planning-and-workflow.md b/improvements/planning-and-workflow.md new file mode 100644 index 0000000..ea78218 --- /dev/null +++ b/improvements/planning-and-workflow.md @@ -0,0 +1,44 @@ +# Planning & Workflow + +## Why This Matters + +Boris from the Claude Code team: "Go back and forth with Claude until you like the plan before you let Claude execute. This easily 2-3x's results for harder tasks." The community-recommended paradigm is **PLAN -> TASK CREATION -> EXECUTE**. + +## Current State + +- CLAUDE.md mentions milestones and verification scripts (good) +- No explicit planning workflow documented +- Plan Mode available but not emphasised in workflow + +## Recommended Workflow + +### 1. Plan Mode (Shift+Tab twice) +Enter Plan Mode before any non-trivial task. Iterate on the plan until you're satisfied. Plans save to `~/.claude/plans/` for historical review. This is the single highest-ROI workflow change according to the Claude Code team. + +### 2. Verification-Driven Development +Give Claude explicit ways to check its own work. Boris says this alone "2-3x's output quality." + +- For Helm: `helm template` to validate values +- For Kubernetes: `kustomize build`, `kubectl --dry-run` +- For web: Playwright MCP or `curl --resolve` +- For code: test commands, lint commands, type-checking +- For infra: `scripts/verify-m.sh` (you already do this well) + +### 3. Test-Driven Development Loops +Let Claude write tests alongside code, then run them autonomously. The "write-test cycle" creates a self-healing loop: +1. Claude writes/modifies code +2. Runs tests +3. If tests fail, fixes code +4. Repeats until green + +This is especially powerful with commit-gate hooks that prevent commits until tests pass. + +### 4. The Stingraycharles Approach +The creator of Claude Code's personal workflow: +- "Do not allow the LLM to make any implicit decisions — confirm with the user" +- Planning phase takes 1+ hours for complex tasks, but catches issues early +- Structure code so AI can easily understand it ("LLM-friendly code") +- Document invisible knowledge that's difficult to infer from code alone +- Uses sub-agents plus reusable skills, with most skills invoking Python scripts + +Reference: https://github.com/solatis/claude-config/ diff --git a/improvements/plugins-and-language-servers.md b/improvements/plugins-and-language-servers.md new file mode 100644 index 0000000..da89977 --- /dev/null +++ b/improvements/plugins-and-language-servers.md @@ -0,0 +1,34 @@ +# Plugins & Language Servers + +## Why This Matters + +The community calls Language Server integration "the single biggest productivity gain" for Claude Code. LSPs give Claude real-time type information, go-to-definition, and find-references — dramatically improving code understanding over raw text analysis. + +## Current State + +- No LSP plugins installed +- No third-party plugins + +## Language Server Plugin + +**boostvolt/claude-code-lsps** — provides LSP integration for: +- Python (pyright) +- TypeScript (vtsls) +- Rust (rust-analyzer) +- Go (gopls) + +This gives Claude access to the same intelligence your IDE uses: types, definitions, references, diagnostics. Particularly valuable for large codebases and unfamiliar code. + +## Other Recommended Plugins + +| Plugin | Purpose | Value | +|---|---|---| +| **obra/superpowers** | 20+ structured workflow skills (TDD, debugging, root cause tracing) | "Transforms Claude from reactive helper to proactive senior developer" | +| **commit-commands** | Intelligent commit messages generated from diffs | Consistent, meaningful commit history | +| **pr-review-toolkit** | Multi-agent code reviews with confidence scoring | Automated quality gates on PRs | + +## Installation Considerations + +- Plugins add to context overhead — evaluate each one's token cost vs. value +- Start with the LSP plugin alone and measure the improvement before adding more +- `obra/superpowers` overlaps with custom skills — evaluate which skills you'd use before installing the full set diff --git a/improvements/session-and-context-management.md b/improvements/session-and-context-management.md new file mode 100644 index 0000000..bcb07c4 --- /dev/null +++ b/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." diff --git a/improvements/skills-and-progressive-disclosure.md b/improvements/skills-and-progressive-disclosure.md new file mode 100644 index 0000000..8dd2d90 --- /dev/null +++ b/improvements/skills-and-progressive-disclosure.md @@ -0,0 +1,59 @@ +# Skills & Progressive Disclosure + +## Why This Matters + +Progressive disclosure is the single most powerful technique for managing context. Instead of putting everything in CLAUDE.md (which competes with Claude's ~50 built-in system instructions for attention), skills load domain knowledge **on demand** — only when relevant. + +Token savings: ~15,000 tokens per session recovered vs. loading everything upfront (82% improvement in one benchmark). + +## Current State + +- One custom skill: `reflect` +- Skills symlinked from `~/dev/claude/custom-claude-skills/skills/` into `~/.claude/skills/` + +## Architecture + +``` +CLAUDE.md # <200 lines, universal rules only +.claude/skills/ # Domain knowledge loaded on demand +.claude/rules/ # Path-scoped rules (YAML frontmatter for file pattern matching) +``` + +Skills use a three-stage loading: metadata (~100 tokens) -> full instructions (<5k tokens) -> bundled resources only as needed. + +## Suggested Skills to Build + +### /catchup +Reads all changed files in your git branch when resuming work. Shows what changed since last session, reads relevant memory files, and summarises the current state. + +### /validate +Codifies the "validate before deploying" principle. Runs helm template, kustomize build, linting, and type-checking as appropriate for the current project. Catches errors before they hit the cluster. + +### /deploy +Standardised deploy workflow for cluster-bootstrap. Validates first, applies, then runs the appropriate verify script. + +### /security-audit +Checks for secrets in code, insecure configurations, default credentials. Trail of Bits has 12+ open-source security skills that could be adapted. + +### /tdd +Test-driven development workflow. Write tests first, then implement until tests pass. From `obra/superpowers` — 20+ production-proven skills. + +### /handoff +Creates a structured handoff document (goals, progress, blockers, next steps) for session transitions. Useful before `/clear` or when hitting context limits. + +## Community Skills Worth Evaluating + +| Skill/Resource | Description | +|---|---| +| **obra/superpowers** | 20+ skills: TDD, systematic debugging, root cause tracing, brainstorming | +| **Trail of Bits security skills** | 12+ security-focused skills for code auditing and vulnerability detection | +| **cc-devops-skills** | IaC validation, shell script generation, DevOps workflows | +| **Context Engineering Kit** | Advanced context engineering techniques with minimal token footprint | +| **reddit-fetch** | Workaround for Claude's inability to fetch Reddit — uses Gemini CLI as fallback | + +## Best Practices + +- Limit to 20-30 high-quality skills. More than that degrades performance (Claude wastes tokens parsing descriptions). +- Each skill should have one clear purpose and be self-contained. +- Skills should be <200 lines / <5k tokens for the full instruction set. +- Use YAML frontmatter in `.claude/rules/` for path-scoped conditional loading (e.g., rules that only apply to `*.yaml` files).