mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-01-31 11:46:11 +08:00
feat: add images and rename guides to the-shortform-guide.md and the-longform-guide.md
- Renamed SHORTHAND-GUIDE.md to the-shortform-guide.md - Renamed LONGFORM-GUIDE.md to the-longform-guide.md - Added assets/images/shortform/ with 11 images for shorthand guide - Added assets/images/longform/ with 10 images for longform guide - Updated both guides with embedded images from original X articles - Images include: hackathon tweet, command chaining, hooks, MCPs, plugins, tmux demo, GitHub PR review, Zed editor, VS Code extension, custom statusline, session storage, model selection table, pricing table, mgrep benchmark, Boris parallel terminals, two-terminal setup, and 25k stars celebration
This commit is contained in:
Affaan Mustafa
@@ -1,295 +0,0 @@
|
||||
# The Longform Guide to Everything Claude Code
|
||||
|
||||
> Advanced techniques that separate productive sessions from wasteful ones. Token economics, memory persistence, verification patterns, parallelization strategies, and compound effects of building reusable workflows.
|
||||
|
||||
## Preface
|
||||
|
||||
In "The Shorthand Guide to Everything Claude Code", I covered the foundational setup: skills and commands, hooks, subagents, MCPs, plugins, and the configuration patterns that form the backbone of an effective Claude Code workflow.
|
||||
|
||||
This longform guide goes deeper into techniques that make the difference between being plagued by context rot within the first hour, versus maintaining productive sessions for hours. These patterns have been refined over 10+ months of daily use.
|
||||
|
||||
**Themes:** Token economics, memory persistence, verification patterns, parallelization strategies, and the compound effects of building reusable workflows.
|
||||
|
||||
## Context & Memory Management
|
||||
|
||||
For sharing memory across sessions, create a skill or command that summarizes progress and saves to a `.tmp` file in your `.claude` folder. The next day it can use that as context and pick up where you left off.
|
||||
|
||||
### Session Storage Pattern
|
||||
|
||||
Create one file per session: `~/.claude/sessions/YYYY-MM-DD-topic.tmp`
|
||||
|
||||
Each session file should contain:
|
||||
- What approaches worked (with evidence)
|
||||
- Which approaches failed
|
||||
- Which approaches haven't been attempted
|
||||
- What's left to do
|
||||
|
||||
### Clearing Context Strategically
|
||||
|
||||
Once you have your plan set and context cleared, you can work from the plan. This is useful when you've accumulated a lot of exploration context that's no longer relevant to execution.
|
||||
|
||||
**Disable auto-compact** for more control. Manually compact at logical intervals:
|
||||
- Compact after exploration, before execution
|
||||
- Compact after completing a milestone, before starting next
|
||||
|
||||
### Advanced: Dynamic System Prompt Injection
|
||||
|
||||
Instead of solely putting everything in `.claude/rules/` which loads every session, use CLI flags to inject context dynamically:
|
||||
|
||||
```bash
|
||||
claude --system-prompt "$(cat memory.md)"
|
||||
```
|
||||
|
||||
This ensures content gets weighted appropriately in the instruction hierarchy.
|
||||
|
||||
### Memory Persistence Hooks
|
||||
|
||||
Chain these together for continuous memory across sessions:
|
||||
|
||||
- **PreCompact Hook**: Before context compaction happens, save important state to a file
|
||||
- **SessionStart Hook**: On new session, load previous context automatically
|
||||
- **SessionEnd Hook**: On session end, persist learnings to a file
|
||||
|
||||
## Continuous Learning / Memory
|
||||
|
||||
### The Problem
|
||||
|
||||
Wasted tokens, wasted context, wasted time. You repeat prompts because Claude ran into the same problem or gave the same response you've heard before.
|
||||
|
||||
### The Solution
|
||||
|
||||
When Claude Code discovers something non-trivial - a debugging technique, a workaround, a project-specific pattern - it saves that knowledge as a new skill. Next time a similar problem comes up, the skill gets loaded automatically.
|
||||
|
||||
Use a **Stop hook** (runs once at session end) instead of **UserPromptSubmit** (runs on every message and adds latency). The script analyzes the session for patterns worth extracting and saves them as reusable skills in `~/.claude/skills/learned/`.
|
||||
|
||||
### Manual Extraction
|
||||
|
||||
Run `/learn` mid-session when you've just solved something non-trivial. It prompts you to extract the pattern, drafts a skill file, and asks for confirmation before saving.
|
||||
|
||||
## Token Optimization
|
||||
|
||||
### Primary Strategy: Subagent Architecture
|
||||
|
||||
Optimize tools and subagent architecture to delegate the cheapest model sufficient for the task:
|
||||
|
||||
- **Haiku**: Repetitive tasks, clear instructions, "worker" in multi-agent setup
|
||||
- **Sonnet**: 90% of coding tasks (default)
|
||||
- **Opus**: First attempt failed, 5+ files, architectural decisions, security-critical code
|
||||
|
||||
### Model Selection Quick Reference
|
||||
|
||||
```
|
||||
Default: Sonnet for most coding
|
||||
Upgrade to Opus if: First attempt failed, task spans 5+ files, architectural decisions
|
||||
Downgrade to Haiku if: Repetitive, instructions very clear, worker agent
|
||||
```
|
||||
|
||||
### Tool-Specific Optimizations
|
||||
|
||||
- Replace `grep` with `mgrep` - ~50% token reduction on average
|
||||
- Run background processes outside Claude if you don't need Claude to process entire output
|
||||
- Use `tmux` for long-running commands
|
||||
|
||||
### Modular Codebase Benefits
|
||||
|
||||
A modular codebase with reusable utilities, functions, and hooks:
|
||||
- Reduces token costs (main files hundreds of lines instead of thousands)
|
||||
- Gets tasks done right on first try (fewer re-prompts)
|
||||
- Helps Claude avoid large file reads that cause token overflow
|
||||
|
||||
### System Prompt Slimming
|
||||
|
||||
Claude Code's system prompt takes ~18k tokens (~9% of 200k context). Can be reduced to ~10k tokens with patches, saving ~7,300 tokens (41% of static overhead).
|
||||
|
||||
## Verification Loops and Evals
|
||||
|
||||
### Observability Methods
|
||||
|
||||
1. **Hook-based logging**: PostToolUse hook logs what Claude enacted and exact changes
|
||||
2. **Diff-based comparison**: Compare same task with and without skill across worktrees
|
||||
3. **Tmux tracing**: Monitor thinking stream and output when skills trigger
|
||||
|
||||
### Eval Pattern Types
|
||||
|
||||
**Checkpoint-Based Evals:**
|
||||
- Set explicit checkpoints in workflow
|
||||
- Verify against defined criteria
|
||||
- If verification fails, Claude must fix before proceeding
|
||||
- Good for linear workflows with clear milestones
|
||||
|
||||
**Continuous Evals:**
|
||||
- Run every N minutes or after major changes
|
||||
- Full test suite, build status, lint
|
||||
- Report regressions immediately
|
||||
- Good for long-running sessions
|
||||
|
||||
### Key Metrics
|
||||
|
||||
- **pass@k**: At least ONE of k attempts succeeds (use when you just need it to work)
|
||||
- **pass^k**: ALL k attempts must succeed (use when consistency is essential)
|
||||
|
||||
### Building an Eval Roadmap
|
||||
|
||||
1. Start early - 20-50 simple tasks from real failures
|
||||
2. Convert user-reported failures into test cases
|
||||
3. Write unambiguous tasks
|
||||
4. Build balanced problem sets
|
||||
5. Build robust harness
|
||||
6. Grade what agent produced, not the path it took
|
||||
7. Read transcripts from many trials
|
||||
8. Monitor for saturation
|
||||
|
||||
## Parallelization
|
||||
|
||||
### Defining Scopes
|
||||
|
||||
When forking conversations in a multi-Claude terminal setup:
|
||||
- Define scope for actions in fork and original conversation
|
||||
- Aim for minimal overlap
|
||||
- Choose orthogonal tasks to prevent interference
|
||||
|
||||
### Preferred Pattern
|
||||
|
||||
- Main chat: Code changes
|
||||
- Forks: Questions about codebase state, research on external services, doc pulls
|
||||
|
||||
### On Arbitrary Terminal Counts
|
||||
|
||||
Don't set arbitrary amounts like 5 local + 5 upstream. Add terminal/instance out of true necessity:
|
||||
- Use scripts if you can
|
||||
- Let Claude spawn instance in tmux if possible
|
||||
- Minimum viable parallelization is key
|
||||
|
||||
### Git Worktrees
|
||||
|
||||
For overlapping parallel instances without conflicts:
|
||||
|
||||
```bash
|
||||
git worktree add ../project-feature-a feature-a
|
||||
git worktree add ../project-feature-b feature-b
|
||||
git worktree add ../project-refactor refactor-branch
|
||||
|
||||
# Each worktree gets its own Claude instance
|
||||
cd ../project-feature-a && claude
|
||||
```
|
||||
|
||||
Benefits:
|
||||
- No git conflicts
|
||||
- Clean working directory per instance
|
||||
- Easy to compare outputs
|
||||
- Can benchmark same task across approaches
|
||||
|
||||
### The Cascade Method
|
||||
|
||||
Organize with "cascade" pattern:
|
||||
- Open new tasks in new tabs to the right
|
||||
- Sweep left to right, oldest to newest
|
||||
- Maintain consistent direction flow
|
||||
- Focus on at most 3-4 tasks (more = mental overhead grows faster than productivity)
|
||||
|
||||
## Groundwork
|
||||
|
||||
### Two-Instance Kickoff Pattern
|
||||
|
||||
For new projects, start with 2 Claude instances:
|
||||
|
||||
**Instance 1: Scaffolding Agent**
|
||||
- Lays down scaffold and groundwork
|
||||
- Creates project structure
|
||||
- Sets up configs (CLAUDE.md, rules, agents)
|
||||
- Establishes conventions
|
||||
- Gets skeleton in place
|
||||
|
||||
**Instance 2: Deep Research Agent**
|
||||
- Connects to services, web search
|
||||
- Creates detailed PRD
|
||||
- Creates architecture diagrams
|
||||
- Compiles references with actual documentation clips
|
||||
|
||||
### Minimal Starting Requirements
|
||||
|
||||
What you need minimally to start is fine - quicker than feeding in links for Claude to scrape or using Firecrawl MCP. Use those when deep in work and Claude is getting syntax wrong or using dated functions.
|
||||
|
||||
### llms.txt Pattern
|
||||
|
||||
Many documentation sites offer `/llms.txt` - a clean, LLM-optimized version of documentation. Request with `/llms.txt` on their docs page and feed directly to Claude.
|
||||
|
||||
## Philosophy: Build Reusable Patterns
|
||||
|
||||
From [@omarsar0](https://x.com/@omarsar0): "Early on, I spent time building reusable workflows/patterns. Tedious to build, but this had a wild compounding effect as models and agent harnesses improved."
|
||||
|
||||
### What to Invest In
|
||||
|
||||
- Subagents
|
||||
- Skills
|
||||
- Commands
|
||||
- Planning patterns
|
||||
- MCP tools
|
||||
- Context engineering patterns
|
||||
|
||||
### Why It Compounds
|
||||
|
||||
"The best part is that all these workflows are transferable to other agents." Once built, they work across model upgrades. **Investment in patterns > investment in specific model tricks.**
|
||||
|
||||
## Best Practices for Agents & Sub-Agents
|
||||
|
||||
### The Sub-Agent Context Problem
|
||||
|
||||
Sub-agents exist to save context by returning summaries instead of dumping everything. But the orchestrator has semantic context the sub-agent lacks. The sub-agent only knows the literal query, not the PURPOSE behind it. Summaries often miss key details.
|
||||
|
||||
### Iterative Retrieval Pattern
|
||||
|
||||
1. Orchestrator evaluates every sub-agent return
|
||||
2. Ask follow-up questions before accepting
|
||||
3. Sub-agent goes back to source and gets answers
|
||||
4. Loop until sufficient (max 3 cycles)
|
||||
|
||||
**Key:** Pass objective context, not just the query.
|
||||
|
||||
### Sequential Phase Pattern
|
||||
|
||||
```
|
||||
Phase 1: RESEARCH → research-summary.md
|
||||
Phase 2: PLAN → plan.md
|
||||
Phase 3: IMPLEMENT → code changes
|
||||
Phase 4: REVIEW → review-comments.md
|
||||
Phase 5: VERIFY → done or loop back
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
1. Each agent gets ONE clear input, produces ONE clear output
|
||||
2. Outputs become inputs for next phase
|
||||
3. Never skip phases
|
||||
4. Use `/clear` between agents
|
||||
5. Store intermediate outputs in files
|
||||
|
||||
## Tips and Tricks
|
||||
|
||||
### MCPs Are Replaceable
|
||||
|
||||
Most MCPs (GitHub, Supabase, Vercel, etc.) are just wrappers around robust CLIs. Instead of having the MCP loaded full-time (context cost), create skills and commands that use the CLI directly.
|
||||
|
||||
Example: Instead of GitHub MCP, create `/gh-pr` command wrapping `gh pr create` with your preferred options.
|
||||
|
||||
**Note:** With lazy loading, the context window issue is mostly solved, but token usage and cost are not. CLI + skills approach still effective.
|
||||
|
||||
## Video
|
||||
|
||||
Full end-to-end project walkthrough covering both guides in action is planned, demonstrating:
|
||||
- Full project setup with configs from shorthand guide
|
||||
- Advanced techniques from longform guide
|
||||
- Real-time token optimization
|
||||
- Verification loops in practice
|
||||
- Memory management across sessions
|
||||
- Two-instance kickoff pattern
|
||||
- Parallel workflows with git worktrees
|
||||
|
||||
## References
|
||||
|
||||
- [Anthropic: Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)
|
||||
- [YK: 32 Claude Code Tips](https://agenticcoding.substack.com/p/32-claude-code-tips-from-basics-to)
|
||||
- [RLanceMartin: Session Reflection Pattern](https://rlancemartin.github.io/2025/12/01/claude_diary/)
|
||||
|
||||
---
|
||||
|
||||
*Everything covered in both guides is available on GitHub at [everything-claude-code](https://github.com/affaan-m/everything-claude-code)*
|
||||
@@ -1,273 +0,0 @@
|
||||
# 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.*
|
||||
BIN
assets/images/longform/01-header.png
Normal file
BIN
assets/images/longform/01-header.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 5.4 MiB |
BIN
assets/images/longform/02-shortform-reference.png
Normal file
BIN
assets/images/longform/02-shortform-reference.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 452 KiB |
BIN
assets/images/longform/03-session-storage.png
Normal file
BIN
assets/images/longform/03-session-storage.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 65 KiB |
BIN
assets/images/longform/03b-session-storage-alt.png
Normal file
BIN
assets/images/longform/03b-session-storage-alt.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 180 KiB |
BIN
assets/images/longform/04-model-selection.png
Normal file
BIN
assets/images/longform/04-model-selection.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 320 KiB |
BIN
assets/images/longform/05-pricing-table.png
Normal file
BIN
assets/images/longform/05-pricing-table.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 183 KiB |
BIN
assets/images/longform/06-mgrep-benchmark.png
Normal file
BIN
assets/images/longform/06-mgrep-benchmark.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 573 KiB |
BIN
assets/images/longform/07-boris-parallel.png
Normal file
BIN
assets/images/longform/07-boris-parallel.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 436 KiB |
BIN
assets/images/longform/08-two-terminals.png
Normal file
BIN
assets/images/longform/08-two-terminals.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 766 KiB |
BIN
assets/images/longform/09-25k-stars.png
Normal file
BIN
assets/images/longform/09-25k-stars.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 522 KiB |
BIN
assets/images/shortform/01-hackathon-tweet.png
Normal file
BIN
assets/images/shortform/01-hackathon-tweet.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.1 MiB |
BIN
assets/images/shortform/02-chaining-commands.jpeg
Normal file
BIN
assets/images/shortform/02-chaining-commands.jpeg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 37 KiB |
BIN
assets/images/shortform/03-posttooluse-hook.png
Normal file
BIN
assets/images/shortform/03-posttooluse-hook.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 30 KiB |
BIN
assets/images/shortform/04-supabase-mcp.jpeg
Normal file
BIN
assets/images/shortform/04-supabase-mcp.jpeg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 20 KiB |
BIN
assets/images/shortform/05-plugins-interface.jpeg
Normal file
BIN
assets/images/shortform/05-plugins-interface.jpeg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 59 KiB |
BIN
assets/images/shortform/06-marketplaces-mgrep.jpeg
Normal file
BIN
assets/images/shortform/06-marketplaces-mgrep.jpeg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 58 KiB |
BIN
assets/images/shortform/07-tmux-video.mp4
Normal file
BIN
assets/images/shortform/07-tmux-video.mp4
Normal file
Binary file not shown.
BIN
assets/images/shortform/08-github-pr-review.jpeg
Normal file
BIN
assets/images/shortform/08-github-pr-review.jpeg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 63 KiB |
BIN
assets/images/shortform/09-zed-editor.jpeg
Normal file
BIN
assets/images/shortform/09-zed-editor.jpeg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 136 KiB |
BIN
assets/images/shortform/10-vscode-extension.jpeg
Normal file
BIN
assets/images/shortform/10-vscode-extension.jpeg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 213 KiB |
BIN
assets/images/shortform/11-statusline.jpeg
Normal file
BIN
assets/images/shortform/11-statusline.jpeg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
354
the-longform-guide.md
Normal file
354
the-longform-guide.md
Normal file
@@ -0,0 +1,354 @@
|
||||
# The Longform Guide to Everything Claude Code
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
> **Prerequisite**: This guide builds on [The Shorthand Guide to Everything Claude Code](./the-shortform-guide.md). Read that first if you haven't set up skills, hooks, subagents, MCPs, and plugins.
|
||||
|
||||
|
||||
*The Shorthand Guide - read it first*
|
||||
|
||||
In the shorthand guide, I covered the foundational setup: skills and commands, hooks, subagents, MCPs, plugins, and the configuration patterns that form the backbone of an effective Claude Code workflow. That was the setup guide and the base infrastructure.
|
||||
|
||||
This longform guide goes into the techniques that separate productive sessions from wasteful ones. If you haven't read the shorthand guide, go back and set up your configs first. What follows assumes you have skills, agents, hooks, and MCPs already configured and working.
|
||||
|
||||
The themes here: token economics, memory persistence, verification patterns, parallelization strategies, and the compound effects of building reusable workflows. These are the patterns I've refined over 10+ months of daily use that make the difference between being plagued by context rot within the first hour, versus maintaining productive sessions for hours.
|
||||
|
||||
Everything covered in the shorthand and longform guides is available on GitHub: `github.com/affaan-m/everything-claude-code`
|
||||
|
||||
---
|
||||
|
||||
## Tips and Tricks
|
||||
|
||||
### Some MCPs are Replaceable and Will Free Up Your Context Window
|
||||
|
||||
For MCPs such as version control (GitHub), databases (Supabase), deployment (Vercel, Railway) etc. - most of these platforms already have robust CLIs that the MCP is essentially just wrapping. The MCP is a nice wrapper but it comes at a cost.
|
||||
|
||||
To have the CLI function more like an MCP without actually using the MCP (and the decreased context window that comes with it), consider bundling the functionality into skills and commands. Strip out the tools the MCP exposes that make things easy and turn those into commands.
|
||||
|
||||
Example: instead of having the GitHub MCP loaded at all times, create a `/gh-pr` command that wraps `gh pr create` with your preferred options. Instead of the Supabase MCP eating context, create skills that use the Supabase CLI directly.
|
||||
|
||||
With lazy loading, the context window issue is mostly solved. But token usage and cost is not solved in the same way. The CLI + skills approach is still a token optimization method.
|
||||
|
||||
---
|
||||
|
||||
## IMPORTANT STUFF
|
||||
|
||||
### Context and Memory Management
|
||||
|
||||
For sharing memory across sessions, a skill or command that summarizes and checks in on progress then saves to a `.tmp` file in your `.claude` folder and appends to it until the end of your session is the best bet. The next day it can use that as context and pick up where you left off, create a new file for each session so you don't pollute old context into new work.
|
||||
|
||||
|
||||
*Example of session storage -> https://github.com/affaan-m/everything-claude-code/tree/main/examples/sessions*
|
||||
|
||||
Claude creates a file summarizing current state. Review it, ask for edits if needed, then start fresh. For the new conversation, just provide the file path. Particularly useful when you're hitting context limits and need to continue complex work. These files should contain:
|
||||
- What approaches worked (verifiably with evidence)
|
||||
- Which approaches were attempted but did not work
|
||||
- Which approaches have not been attempted and what's left to do
|
||||
|
||||
**Clearing Context Strategically:**
|
||||
|
||||
Once you have your plan set and context cleared (default option in plan mode in Claude Code now), you can work from the plan. This is useful when you've accumulated a lot of exploration context that's no longer relevant to execution. For strategic compacting, disable auto compact. Manually compact at logical intervals or create a skill that does so for you.
|
||||
|
||||
**Advanced: Dynamic System Prompt Injection**
|
||||
|
||||
One pattern I picked up: instead of solely putting everything in CLAUDE.md (user scope) or `.claude/rules/` (project scope) which loads every session, use CLI flags to inject context dynamically.
|
||||
|
||||
```bash
|
||||
claude --system-prompt "$(cat memory.md)"
|
||||
```
|
||||
|
||||
This lets you be more surgical about what context loads when. System prompt content has higher authority than user messages, which have higher authority than tool results.
|
||||
|
||||
**Practical setup:**
|
||||
|
||||
```bash
|
||||
# Daily development
|
||||
alias claude-dev='claude --system-prompt "$(cat ~/.claude/contexts/dev.md)"'
|
||||
|
||||
# PR review mode
|
||||
alias claude-review='claude --system-prompt "$(cat ~/.claude/contexts/review.md)"'
|
||||
|
||||
# Research/exploration mode
|
||||
alias claude-research='claude --system-prompt "$(cat ~/.claude/contexts/research.md)"'
|
||||
```
|
||||
|
||||
**Advanced: Memory Persistence Hooks**
|
||||
|
||||
There are hooks most people don't know about that help with memory:
|
||||
|
||||
- **PreCompact Hook**: Before context compaction happens, save important state to a file
|
||||
- **Stop Hook (Session End)**: On session end, persist learnings to a file
|
||||
- **SessionStart Hook**: On new session, load previous context automatically
|
||||
|
||||
I've built these hooks and they're in the repo at `github.com/affaan-m/everything-claude-code/tree/main/hooks/memory-persistence`
|
||||
|
||||
---
|
||||
|
||||
### Continuous Learning / Memory
|
||||
|
||||
If you've had to repeat a prompt multiple times and Claude ran into the same problem or gave you a response you've heard before - those patterns must be appended to skills.
|
||||
|
||||
**The Problem:** Wasted tokens, wasted context, wasted time.
|
||||
|
||||
**The Solution:** When Claude Code discovers something that isn't trivial - a debugging technique, a workaround, some project-specific pattern - it saves that knowledge as a new skill. Next time a similar problem comes up, the skill gets loaded automatically.
|
||||
|
||||
I've built a continuous learning skill that does this: `github.com/affaan-m/everything-claude-code/tree/main/skills/continuous-learning`
|
||||
|
||||
**Why Stop Hook (Not UserPromptSubmit):**
|
||||
|
||||
The key design decision is using a **Stop hook** instead of UserPromptSubmit. UserPromptSubmit runs on every single message - adds latency to every prompt. Stop runs once at session end - lightweight, doesn't slow you down during the session.
|
||||
|
||||
---
|
||||
|
||||
### Token Optimization
|
||||
|
||||
**Primary Strategy: Subagent Architecture**
|
||||
|
||||
Optimize the tools you use and subagent architecture designed to delegate the cheapest possible model that is sufficient for the task.
|
||||
|
||||
**Model Selection Quick Reference:**
|
||||
|
||||
|
||||
*Hypothetical setup of subagents on various common tasks and reasoning behind the choices*
|
||||
|
||||
| Task Type | Model | Why |
|
||||
| ------------------------- | ------ | ------------------------------------------ |
|
||||
| Exploration/search | Haiku | Fast, cheap, good enough for finding files |
|
||||
| Simple edits | Haiku | Single-file changes, clear instructions |
|
||||
| Multi-file implementation | Sonnet | Best balance for coding |
|
||||
| Complex architecture | Opus | Deep reasoning needed |
|
||||
| PR reviews | Sonnet | Understands context, catches nuance |
|
||||
| Security analysis | Opus | Can't afford to miss vulnerabilities |
|
||||
| Writing docs | Haiku | Structure is simple |
|
||||
| Debugging complex bugs | Opus | Needs to hold entire system in mind |
|
||||
|
||||
Default to Sonnet for 90% of coding tasks. Upgrade to Opus when first attempt failed, task spans 5+ files, architectural decisions, or security-critical code.
|
||||
|
||||
**Pricing Reference:**
|
||||
|
||||
|
||||
*Source: https://platform.claude.com/docs/en/about-claude/pricing*
|
||||
|
||||
**Tool-Specific Optimizations:**
|
||||
|
||||
Replace grep with mgrep - ~50% token reduction on average compared to traditional grep or ripgrep:
|
||||
|
||||
|
||||
*In our 50-task benchmark, mgrep + Claude Code used ~2x fewer tokens than grep-based workflows at similar or better judged quality. Source: https://github.com/mixedbread-ai/mgrep*
|
||||
|
||||
**Modular Codebase Benefits:**
|
||||
|
||||
Having a more modular codebase with main files being in the hundreds of lines instead of thousands of lines helps both in token optimization costs and getting a task done right on the first try.
|
||||
|
||||
---
|
||||
|
||||
### Verification Loops and Evals
|
||||
|
||||
**Benchmarking Workflow:**
|
||||
|
||||
Compare asking for the same thing with and without a skill and checking the output difference:
|
||||
|
||||
Fork the conversation, initiate a new worktree in one of them without the skill, pull up a diff at the end, see what was logged.
|
||||
|
||||
**Eval Pattern Types:**
|
||||
|
||||
- **Checkpoint-Based Evals**: Set explicit checkpoints, verify against defined criteria, fix before proceeding
|
||||
- **Continuous Evals**: Run every N minutes or after major changes, full test suite + lint
|
||||
|
||||
**Key Metrics:**
|
||||
|
||||
```
|
||||
pass@k: At least ONE of k attempts succeeds
|
||||
k=1: 70% k=3: 91% k=5: 97%
|
||||
|
||||
pass^k: ALL k attempts must succeed
|
||||
k=1: 70% k=3: 34% k=5: 17%
|
||||
```
|
||||
|
||||
Use **pass@k** when you just need it to work. Use **pass^k** when consistency is essential.
|
||||
|
||||
---
|
||||
|
||||
## PARALLELIZATION
|
||||
|
||||
When forking conversations in a multi-Claude terminal setup, make sure the scope is well-defined for the actions in the fork and the original conversation. Aim for minimal overlap when it comes to code changes.
|
||||
|
||||
**My Preferred Pattern:**
|
||||
|
||||
Main chat for code changes, forks for questions about the codebase and its current state, or research on external services.
|
||||
|
||||
**On Arbitrary Terminal Counts:**
|
||||
|
||||
|
||||
*Boris (Anthropic) on running multiple Claude instances*
|
||||
|
||||
Boris has tips on parallelization. He's suggested things like running 5 Claude instances locally and 5 upstream. I advise against setting arbitrary terminal amounts. The addition of a terminal should be out of true necessity.
|
||||
|
||||
Your goal should be: **how much can you get done with the minimum viable amount of parallelization.**
|
||||
|
||||
**Git Worktrees for Parallel Instances:**
|
||||
|
||||
```bash
|
||||
# Create worktrees for parallel work
|
||||
git worktree add ../project-feature-a feature-a
|
||||
git worktree add ../project-feature-b feature-b
|
||||
git worktree add ../project-refactor refactor-branch
|
||||
|
||||
# Each worktree gets its own Claude instance
|
||||
cd ../project-feature-a && claude
|
||||
```
|
||||
|
||||
IF you are to begin scaling your instances AND you have multiple instances of Claude working on code that overlaps with one another, it's imperative you use git worktrees and have a very well-defined plan for each. Use `/rename <name here>` to name all your chats.
|
||||
|
||||
|
||||
*Starting Setup: Left Terminal for Coding, Right Terminal for Questions - use /rename and /fork*
|
||||
|
||||
**The Cascade Method:**
|
||||
|
||||
When running multiple Claude Code instances, organize with a "cascade" pattern:
|
||||
|
||||
- Open new tasks in new tabs to the right
|
||||
- Sweep left to right, oldest to newest
|
||||
- Focus on at most 3-4 tasks at a time
|
||||
|
||||
---
|
||||
|
||||
## GROUNDWORK
|
||||
|
||||
**The Two-Instance Kickoff Pattern:**
|
||||
|
||||
For my own workflow management, I like to start an empty repo with 2 open Claude instances.
|
||||
|
||||
**Instance 1: Scaffolding Agent**
|
||||
- Lays down the scaffold and groundwork
|
||||
- Creates project structure
|
||||
- Sets up configs (CLAUDE.md, rules, agents)
|
||||
|
||||
**Instance 2: Deep Research Agent**
|
||||
- Connects to all your services, web search
|
||||
- Creates the detailed PRD
|
||||
- Creates architecture mermaid diagrams
|
||||
- Compiles the references with actual documentation clips
|
||||
|
||||
**llms.txt Pattern:**
|
||||
|
||||
If available, you can find an `llms.txt` on many documentation references by doing `/llms.txt` on them once you reach their docs page. This gives you a clean, LLM-optimized version of the documentation.
|
||||
|
||||
**Philosophy: Build Reusable Patterns**
|
||||
|
||||
From @omarsar0: "Early on, I spent time building reusable workflows/patterns. Tedious to build, but this had a wild compounding effect as models and agent harnesses improved."
|
||||
|
||||
**What to invest in:**
|
||||
|
||||
- Subagents
|
||||
- Skills
|
||||
- Commands
|
||||
- Planning patterns
|
||||
- MCP tools
|
||||
- Context engineering patterns
|
||||
|
||||
---
|
||||
|
||||
## Best Practices for Agents & Sub-Agents
|
||||
|
||||
**The Sub-Agent Context Problem:**
|
||||
|
||||
Sub-agents exist to save context by returning summaries instead of dumping everything. But the orchestrator has semantic context the sub-agent lacks. The sub-agent only knows the literal query, not the PURPOSE behind the request.
|
||||
|
||||
**Iterative Retrieval Pattern:**
|
||||
|
||||
1. Orchestrator evaluates every sub-agent return
|
||||
2. Ask follow-up questions before accepting it
|
||||
3. Sub-agent goes back to source, gets answers, returns
|
||||
4. Loop until sufficient (max 3 cycles)
|
||||
|
||||
**Key:** Pass objective context, not just the query.
|
||||
|
||||
**Orchestrator with Sequential Phases:**
|
||||
|
||||
```markdown
|
||||
Phase 1: RESEARCH (use Explore agent) → research-summary.md
|
||||
Phase 2: PLAN (use planner agent) → plan.md
|
||||
Phase 3: IMPLEMENT (use tdd-guide agent) → code changes
|
||||
Phase 4: REVIEW (use code-reviewer agent) → review-comments.md
|
||||
Phase 5: VERIFY (use build-error-resolver if needed) → done or loop back
|
||||
```
|
||||
|
||||
**Key rules:**
|
||||
|
||||
1. Each agent gets ONE clear input and produces ONE clear output
|
||||
2. Outputs become inputs for next phase
|
||||
3. Never skip phases
|
||||
4. Use `/clear` between agents
|
||||
5. Store intermediate outputs in files
|
||||
|
||||
---
|
||||
|
||||
## FUN STUFF / NOT CRITICAL JUST FUN TIPS
|
||||
|
||||
### Custom Status Line
|
||||
|
||||
You can set it using `/statusline` - then Claude will say you don't have one but can set it up for you and ask what you want in it.
|
||||
|
||||
See also: https://github.com/sirmalloc/ccstatusline
|
||||
|
||||
### Voice Transcription
|
||||
|
||||
Talk to Claude Code with your voice. Faster than typing for many people.
|
||||
|
||||
- superwhisper, MacWhisper on Mac
|
||||
- Even with transcription mistakes, Claude understands intent
|
||||
|
||||
### Terminal Aliases
|
||||
|
||||
```bash
|
||||
alias c='claude'
|
||||
alias gb='github'
|
||||
alias co='code'
|
||||
alias q='cd ~/Desktop/projects'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Milestone
|
||||
|
||||
|
||||
*25,000+ GitHub stars in under a week*
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
**Agent Orchestration:**
|
||||
|
||||
- https://github.com/ruvnet/claude-flow - Enterprise orchestration platform with 54+ specialized agents
|
||||
|
||||
**Self-Improving Memory:**
|
||||
|
||||
- https://github.com/affaan-m/everything-claude-code/tree/main/skills/continuous-learning
|
||||
- rlancemartin.github.io/2025/12/01/claude_diary/ - Session reflection pattern
|
||||
|
||||
**System Prompts Reference:**
|
||||
|
||||
- https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools - Collection of system prompts (110k stars)
|
||||
|
||||
**Official:**
|
||||
|
||||
- Anthropic Academy: anthropic.skilljar.com
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- [Anthropic: Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)
|
||||
- [YK: 32 Claude Code Tips](https://agenticcoding.substack.com/p/32-claude-code-tips-from-basics-to)
|
||||
- [RLanceMartin: Session Reflection Pattern](https://rlancemartin.github.io/2025/12/01/claude_diary/)
|
||||
- @PerceptualPeak: Sub-Agent Context Negotiation
|
||||
- @menhguin: Agent Abstractions Tierlist
|
||||
- @omarsar0: Compound Effects Philosophy
|
||||
|
||||
---
|
||||
|
||||
*Everything covered in both guides is available on GitHub at [everything-claude-code](https://github.com/affaan-m/everything-claude-code)*
|
||||
431
the-shortform-guide.md
Normal file
431
the-shortform-guide.md
Normal file
@@ -0,0 +1,431 @@
|
||||
# The Shorthand Guide to Everything Claude Code
|
||||
|
||||
|
||||
*Won the Anthropic x Forum Ventures hackathon with [zenith.chat](https://zenith.chat) alongside [@DRodriguezFX](https://x.com/DRodriguezFX)*
|
||||
|
||||
---
|
||||
|
||||
**Been an avid Claude Code user since the experimental rollout in Feb, and won the Anthropic x Forum Ventures hackathon with [zenith.chat](https://zenith.chat) alongside [@DRodriguezFX](https://x.com/DRodriguezFX) - completely using Claude Code.**
|
||||
|
||||
Here's my complete setup after 10 months of daily use: skills, hooks, subagents, MCPs, plugins, and what actually works.
|
||||
|
||||
---
|
||||
|
||||
## Skills and Commands
|
||||
|
||||
Skills operate like rules, constricted 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 can also include codemaps - a way for Claude to quickly navigate your codebase without burning context on exploration.
|
||||
|
||||
|
||||
*Chaining commands together*
|
||||
|
||||
Commands are skills executed via slash commands. They overlap but are stored differently:
|
||||
|
||||
- **Skills**: `~/.claude/skills/` - broader workflow definitions
|
||||
- **Commands**: `~/.claude/commands/` - quick executable prompts
|
||||
|
||||
```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 constricted 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"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
*Example of what feedback you get in Claude Code, while running a PostToolUse hook*
|
||||
|
||||
**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.
|
||||
|
||||
|
||||
*Example of the Supabase MCP listing the tables within the public schema*
|
||||
|
||||
**Chrome in Claude:** is a built-in plugin MCP that lets Claude autonomously control your browser - clicking around to see how things work.
|
||||
|
||||
**CRITICAL: Context Window Management**
|
||||
|
||||
Be picky with MCPs. I keep all MCPs in user config but **disable everything unused**. Navigate to `/plugins` and scroll down or run `/mcp`.
|
||||
|
||||
|
||||
*Using /plugins to navigate to MCPs to see which ones are currently installed and their status*
|
||||
|
||||
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, but keep under 10 enabled / under 80 tools active.
|
||||
|
||||
```bash
|
||||
# Check enabled MCPs
|
||||
/mcp
|
||||
|
||||
# Disable unused ones in ~/.claude.json under projects.disabledMcpServers
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
|
||||
*Displaying the newly installed Mixedbread-Grep marketplace*
|
||||
|
||||
**LSP Plugins** are particularly useful if you run Claude Code outside editors frequently. 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
|
||||
```
|
||||
|
||||
Same warning as MCPs - 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`) - 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:
|
||||
|
||||
https://github.com/user-attachments/assets/shortform/07-tmux-video.mp4
|
||||
|
||||
```bash
|
||||
tmux new -s dev
|
||||
# Claude runs commands here, you can detach and reattach
|
||||
tmux attach -t dev
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
*Claude approving a bug fix PR*
|
||||
|
||||
### Sandboxing
|
||||
|
||||
Use sandbox mode for risky operations - Claude runs in restricted environment without affecting your actual system.
|
||||
|
||||
---
|
||||
|
||||
## On Editors
|
||||
|
||||
Your editor choice significantly impacts 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) - written in Rust, so it's genuinely fast. Opens instantly, handles massive codebases without breaking a sweat, and barely touches system resources.
|
||||
|
||||
**Why Zed + Claude Code is a great combo:**
|
||||
|
||||
- **Speed** - Rust-based performance means no lag when Claude is rapidly editing files. Your editor keeps up
|
||||
- **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
|
||||
- **CMD+Shift+R Command Palette** - Quick access to all your custom slash commands, debuggers, build scripts in a searchable UI
|
||||
- **Minimal Resource Usage** - Won't compete with Claude for RAM/CPU during heavy operations. Important when running Opus
|
||||
- **Vim Mode** - Full vim keybindings if that's your thing
|
||||
|
||||
|
||||
*Zed Editor with custom commands dropdown using CMD+Shift+R. Following mode shown as the bullseye in the bottom right.*
|
||||
|
||||
**Editor-Agnostic Tips:**
|
||||
|
||||
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. **Auto-save** - Enable autosave so Claude's file reads are always current
|
||||
4. **Git integration** - Use editor's git features to review Claude's changes before committing
|
||||
5. **File watchers** - Most editors auto-reload changed files, verify this is enabled
|
||||
|
||||
### VSCode / Cursor
|
||||
|
||||
This is also a viable choice and works well with Claude Code. You can use it in either terminal format, with automatic sync with your editor using `\ide` enabling LSP functionality (somewhat redundant with plugins now). Or you can opt for the extension which is more integrated with the Editor and has a matching UI.
|
||||
|
||||
|
||||
*The VS Code extension provides a native graphical interface for Claude Code, integrated directly into your IDE.*
|
||||
|
||||
---
|
||||
|
||||
## My Setup
|
||||
|
||||
### Plugins
|
||||
|
||||
**Installed:** (I usually only have 4-5 of these enabled at a time)
|
||||
|
||||
```markdown
|
||||
ralph-wiggum@claude-code-plugins # Loop automation
|
||||
frontend-design@claude-code-plugins # UI/UX patterns
|
||||
commit-commands@claude-code-plugins # Git workflow
|
||||
security-guidance@claude-code-plugins # Security checks
|
||||
pr-review-toolkit@claude-code-plugins # PR automation
|
||||
typescript-lsp@claude-plugins-official # TS intelligence
|
||||
hookify@claude-plugins-official # Hook creation
|
||||
code-simplifier@claude-plugins-official
|
||||
feature-dev@claude-code-plugins
|
||||
explanatory-output-style@claude-code-plugins
|
||||
code-review@claude-code-plugins
|
||||
context7@claude-plugins-official # Live documentation
|
||||
pyright-lsp@claude-plugins-official # Python types
|
||||
mgrep@Mixedbread-Grep # Better search
|
||||
```
|
||||
|
||||
### MCP Servers
|
||||
|
||||
**Configured (User Level):**
|
||||
|
||||
```json
|
||||
{
|
||||
"github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
|
||||
"firecrawl": { "command": "npx", "args": ["-y", "firecrawl-mcp"] },
|
||||
"supabase": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@supabase/mcp-server-supabase@latest", "--project-ref=YOUR_REF"]
|
||||
},
|
||||
"memory": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory"] },
|
||||
"sequential-thinking": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
|
||||
},
|
||||
"vercel": { "type": "http", "url": "https://mcp.vercel.com" },
|
||||
"railway": { "command": "npx", "args": ["-y", "@railway/mcp-server"] },
|
||||
"cloudflare-docs": { "type": "http", "url": "https://docs.mcp.cloudflare.com/mcp" },
|
||||
"cloudflare-workers-bindings": {
|
||||
"type": "http",
|
||||
"url": "https://bindings.mcp.cloudflare.com/mcp"
|
||||
},
|
||||
"clickhouse": { "type": "http", "url": "https://mcp.clickhouse.cloud/mcp" },
|
||||
"AbletonMCP": { "command": "uvx", "args": ["ableton-mcp"] },
|
||||
"magic": { "command": "npx", "args": ["-y", "@magicuidesign/mcp@latest"] }
|
||||
}
|
||||
```
|
||||
|
||||
This is the key - I have 14 MCPs configured but only ~5-6 enabled per project. Keeps context window healthy.
|
||||
|
||||
### Key Hooks
|
||||
|
||||
```json
|
||||
{
|
||||
"PreToolUse": [
|
||||
{ "matcher": "npm|pnpm|yarn|cargo|pytest", "hooks": ["tmux reminder"] },
|
||||
{ "matcher": "Write && .md file", "hooks": ["block unless README/CLAUDE"] },
|
||||
{ "matcher": "git push", "hooks": ["open editor for review"] }
|
||||
],
|
||||
"PostToolUse": [
|
||||
{ "matcher": "Edit && .ts/.tsx/.js/.jsx", "hooks": ["prettier --write"] },
|
||||
{ "matcher": "Edit && .ts/.tsx", "hooks": ["tsc --noEmit"] },
|
||||
{ "matcher": "Edit", "hooks": ["grep console.log warning"] }
|
||||
],
|
||||
"Stop": [
|
||||
{ "matcher": "*", "hooks": ["check modified files for console.log"] }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Status Line
|
||||
|
||||
Shows user, directory, git branch with dirty indicator, context remaining %, model, time, and todo count:
|
||||
|
||||
|
||||
*Example statusline in my Mac root directory*
|
||||
|
||||
```
|
||||
affoon:~ ctx:65% Opus 4.5 19:52
|
||||
▌▌ plan mode on (shift+tab to cycle)
|
||||
```
|
||||
|
||||
### Rules Structure
|
||||
|
||||
```
|
||||
~/.claude/rules/
|
||||
security.md # Mandatory security checks
|
||||
coding-style.md # Immutability, file size limits
|
||||
testing.md # TDD, 80% coverage
|
||||
git-workflow.md # Conventional commits
|
||||
agents.md # Subagent delegation rules
|
||||
patterns.md # API response formats
|
||||
performance.md # Model selection (Haiku vs Sonnet vs Opus)
|
||||
hooks.md # Hook documentation
|
||||
```
|
||||
|
||||
### Subagents
|
||||
|
||||
```
|
||||
~/.claude/agents/
|
||||
planner.md # Break down features
|
||||
architect.md # System design
|
||||
tdd-guide.md # Write tests first
|
||||
code-reviewer.md # Quality review
|
||||
security-reviewer.md # Vulnerability scan
|
||||
build-error-resolver.md
|
||||
e2e-runner.md # Playwright tests
|
||||
refactor-cleaner.md # Dead code removal
|
||||
doc-updater.md # Keep docs synced
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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. See the [Longform Guide](./the-longform-guide.md) for advanced patterns.
|
||||
|
||||
---
|
||||
|
||||
*Won the Anthropic x Forum Ventures hackathon in NYC building [zenith.chat](https://zenith.chat) with [@DRodriguezFX](https://x.com/DRodriguezFX)*
|
||||
Reference in New Issue
Block a user