diff --git a/SHORTHAND-GUIDE.md b/SHORTHAND-GUIDE.md new file mode 100644 index 0000000..6781259 --- /dev/null +++ b/SHORTHAND-GUIDE.md @@ -0,0 +1,273 @@ +# The Shorthand Guide to Everything Claude Code + +> A complete setup guide after 10 months of daily use: skills, hooks, subagents, MCPs, plugins, and what actually works. + +## Overview + +I've been an avid Claude Code user since the experimental rollout in February 2025, and won the Anthropic x Forum Ventures hackathon with [Zenith](https://zenith.chat/) alongside [@DRodriguezFX](https://x.com/DRodriguezFX) completely using Claude Code. + +This guide covers the foundational setup: skills and commands, hooks, subagents, MCPs, plugins, and the configuration patterns that form the backbone of an effective Claude Code workflow. + +## Skills and Commands + +Skills operate like rules, constrained to certain scopes and workflows. They're shorthand to prompts when you need to execute a particular workflow. + +After a long session of coding with Opus 4.5, you want to clean out dead code and loose .md files? +Run `/refactor-clean`. Need testing? `/tdd`, `/e2e`, `/test-coverage`. Skills and commands can be chained together in a single prompt. + +You can make a skill that updates codemaps at checkpoints - a way for Claude to quickly navigate your codebase without burning context on exploration. + +### Structure + +**Skills:** +- Location: `~/.claude/skills` +- Purpose: Broader workflow definitions +- Usage: Referenced via `/` commands or skill names + +**Commands:** +- Location: `~/.claude/commands` +- Purpose: Quick executable prompts +- Usage: Quick executable prompts via slash commands + +```bash +# Example skill structure +~/.claude/skills/ + pmx-guidelines.md # Project-specific patterns + coding-standards.md # Language best practices + tdd-workflow/ # Multi-file skill with README.md + security-review/ # Checklist-based skill +``` + +## Hooks + +Hooks are trigger-based automations that fire on specific events. Unlike skills, they're constrained to tool calls and lifecycle events. + +### Hook Types + +1. **PreToolUse** - Before a tool executes (validation, reminders) +2. **PostToolUse** - After a tool finishes (formatting, feedback loops) +3. **UserPromptSubmit** - When you send a message +4. **Stop** - When Claude finishes responding +5. **PreCompact** - Before context compaction +6. **Notification** - Permission requests + +### Example: tmux reminder before long-running commands + +```json +{ + "PreToolUse": [ + { + "matcher": "tool == \"Bash\" && tool_input.command matches \"(npm|pnpm|yarn|cargo|pytest)\"", + "hooks": [ + { + "type": "command", + "command": "if [ -z \"$TMUX\" ]; then echo '[Hook] Consider tmux for session persistence' >&2; fi" + } + ] + } + ] +} +``` + +**Pro tip:** Use the `hookify` plugin to create hooks conversationally instead of writing JSON manually. Run `/hookify` and describe what you want. + +## Subagents + +Subagents are processes your orchestrator (main Claude) can delegate tasks to with limited scopes. They can run in background or foreground, freeing up context for the main agent. + +Subagents work nicely with skills - a subagent capable of executing a subset of your skills can be delegated tasks and use those skills autonomously. They can also be sandboxed with specific tool permissions. + +```bash +# Example subagent structure +~/.claude/agents/ + planner.md # Feature implementation planning + architect.md # System design decisions + tdd-guide.md # Test-driven development + code-reviewer.md # Quality/security review + security-reviewer.md # Vulnerability analysis + build-error-resolver.md + e2e-runner.md + refactor-cleaner.md +``` + +Configure allowed tools, MCPs, and permissions per subagent for proper scoping. + +## Rules and Memory + +Your `.rules` folder holds `.md` files with best practices Claude should ALWAYS follow. Two approaches: + +1. **Single CLAUDE.md** - Everything in one file (user or project level) +2. **Rules folder** - Modular `.md` files grouped by concern + +```bash +~/.claude/rules/ + security.md # No hardcoded secrets, validate inputs + coding-style.md # Immutability, file organization + testing.md # TDD workflow, 80% coverage + git-workflow.md # Commit format, PR process + agents.md # When to delegate to subagents + performance.md # Model selection, context management +``` + +### Example rules + +- No emojis in codebase +- Refrain from purple hues in frontend +- Always test code before deployment +- Prioritize modular code over mega-files +- Never commit console.logs + +## MCPs (Model Context Protocol) + +MCPs connect Claude to external services directly. Not a replacement for APIs - it's a prompt-driven wrapper around them, allowing more flexibility in navigating information. + +**Example:** Supabase MCP lets Claude pull specific data, run SQL directly upstream without copy-paste. Same for databases, deployment platforms, etc. + +### Chrome in Claude + +A built-in plugin MCP that lets Claude autonomously control your browser - clicking around to see how things work. + +### Context Window Management (CRITICAL) + +Be picky with MCPs. Keep all MCPs in user config but disable everything unused. Navigate to `/plugins` and scroll down or run `/mcp`. + +Your 200k context window before compacting might only be 70k with too many tools enabled. Performance degrades significantly. + +**Rule of thumb:** +- Have 20-30 MCPs in config +- Keep under 10 enabled / under 80 tools active + +## Plugins + +Plugins package tools for easy installation instead of tedious manual setup. A plugin can be a skill + MCP combined, or hooks/tools bundled together. + +### Installing plugins + +```bash +# Add a marketplace +claude plugin marketplace add https://github.com/mixedbread-ai/mgrep + +# Open Claude, run /plugins, find new marketplace, install from there +``` + +### LSP Plugins + +Language Server Protocol gives Claude real-time type checking, go-to-definition, and intelligent completions without needing an IDE open. + +```bash +# Enabled plugins example +typescript-lsp@claude-plugins-official # TypeScript intelligence +pyright-lsp@claude-plugins-official # Python type checking +hookify@claude-plugins-official # Create hooks conversationally +mgrep@Mixedbread-Grep # Better search than ripgrep +``` + +**Warning:** Watch your context window. + +## Tips and Tricks + +### Keyboard Shortcuts + +- `Ctrl+U` - Delete entire line (faster than backspace spam) +- `!` - Quick bash command prefix +- `@` - Search for files +- `/` - Initiate slash commands +- `Shift+Enter` - Multi-line input +- `Tab` - Toggle thinking display +- `Esc Esc` - Interrupt Claude / restore code + +### Parallel Workflows + +`/fork` - Fork conversations to do non-overlapping tasks in parallel instead of spamming queued messages + +### Git Worktrees + +For overlapping parallel Claudes without conflicts. Each worktree is an independent checkout. + +```bash +git worktree add ../feature-branch feature-branch +# Now run separate Claude instances in each worktree +``` + +### tmux for Long-Running Commands + +Stream and watch logs/bash processes Claude runs. + +```bash +tmux new -s dev # Claude runs commands here +tmux attach -t dev # You can detach and reattach +``` + +### mgrep > grep + +`mgrep` is a significant improvement from ripgrep/grep. Install via plugin marketplace, then use the `/mgrep` skill. Works with both local search and web search. + +```bash +mgrep "function handleSubmit" # Local search +mgrep --web "Next.js 15 app router changes" # Web search +``` + +### Other Useful Commands + +- `/rewind` - Go back to a previous state +- `/statusline` - Customize with branch, context %, todos +- `/checkpoints` - File-level undo points +- `/compact` - Manually trigger context compaction + +### GitHub Actions CI/CD + +Set up code review on your PRs with GitHub Actions. Claude can review PRs automatically when configured. + +### Sandboxing + +Use sandbox mode for risky operations - Claude runs in restricted environment without affecting your actual system. (Use `--dangerously-skip-permissions` to do the opposite and let claude roam free, this can be destructive if not careful.) + +## On Editors + +While an editor isn't needed it can positively or negatively impact your Claude Code workflow. While Claude Code works from any terminal, pairing it with a capable editor unlocks real-time file tracking, quick navigation, and integrated command execution. + +### Zed (My Preference) + +I use [Zed](https://zed.dev/) - a Rust-based editor that's lightweight, fast, and highly customizable. + +**Why Zed works well with Claude Code:** + +- **Agent Panel Integration** - Zed's Claude integration lets you track file changes in real-time as Claude edits. Jump between files Claude references without leaving the editor +- **Performance** - Written in Rust, opens instantly and handles large codebases without lag +- **CMD+Shift+R Command Palette** - Quick access to all your custom slash commands, debuggers, and tools in a searchable UI +- **Minimal Resource Usage** - Won't compete with Claude for system resources during heavy operations +- **Vim Mode** - Full vim keybindings if that's your thing + +**Setup:** + +1. Split your screen - Terminal with Claude Code on one side, editor on the other +2. `Ctrl + G` - Quickly open the file Claude is currently working on in Zed +3. Enable autosave so Claude's file reads are always current +4. Use editor's git features to review Claude's changes before committing +5. Enable file watchers - Most editors auto-reload changed files + +### VSCode / Cursor + +Also viable. Works well with Claude Code. Use in either terminal format with automatic sync using `\ide` enabling LSP functionality, or use the extension which is more integrated. + +## Key Takeaways + +1. Don't overcomplicate - treat configuration like fine-tuning, not architecture +2. Context window is precious - disable unused MCPs and plugins +3. Parallel execution - fork conversations, use git worktrees +4. Automate the repetitive - hooks for formatting, linting, reminders +5. Scope your subagents - limited tools = focused execution + +## References + +- [Plugins Reference](https://code.claude.com/docs/en/plugins-reference) +- [Hooks Documentation](https://code.claude.com/docs/en/hooks) +- [Checkpointing](https://code.claude.com/docs/en/checkpointing) +- [Interactive Mode](https://code.claude.com/docs/en/interactive-mode) +- [Memory System](https://code.claude.com/docs/en/memory) +- [Subagents](https://code.claude.com/docs/en/sub-agents) +- [MCP Overview](https://code.claude.com/docs/en/mcp-overview) + +--- + +*Note: This is a subset of detail. More posts on specifics may follow if there's interest.*