iamneilroberts Claude Code best practices reference
Routes to a local mirror of the official docs at ~/.claude/anthropic-docs/ (refreshed weekly
from https://code.claude.com/docs/llms.txt) — canonical Markdown; cite the source path when you
reference a fact. Read the file for the topic at hand instead of guessing.
How to look something up
- Know the topic? Read
~/.claude/anthropic-docs/en__<slug>.md(route table below). - Don't know it?
cat ~/.claude/anthropic-docs/_llms.txt | grep -i <keyword> - API/SDK topic (not the CLI)? Check
en__agent-sdk__*.md.
Route table — topic → local file
| Topic | Local file |
|---|---|
| Best practices overview (workflow patterns, common failures) | en__best-practices.md |
| CLAUDE.md (format, placement, what to include/exclude) | en__memory.md |
| Context window (how it fills, what loads at startup) | en__context-window.md |
| Cost / reduce token usage | en__costs.md |
| Prompt caching (also see platform.claude.com docs) | en__costs.md (CC-specific) |
| Checkpointing / /rewind | en__checkpointing.md |
| Sessions (continue, resume, fork, naming) | en__sessions.md |
| Interactive mode (/clear, /compact, /btw, key bindings) | en__interactive-mode.md |
| Slash commands / built-in commands | en__commands.md |
| Hooks (events, JSON shape, examples) | en__hooks-guide.md + en__hooks.md |
| Skills (SKILL.md format, when to use) | en__skills.md |
| Subagents (.claude/agents/*) | en__sub-agents.md |
| Permission modes (auto, plan, sandbox) | en__permission-modes.md |
| Permissions (allowlists, /permissions) | en__permissions.md |
| Sandboxing | en__sandboxing.md |
| MCP (configuration, claude mcp add) | en__mcp.md |
| Worktrees / parallel sessions | en__worktrees.md |
| Agent teams | en__agent-teams.md |
| Headless / CI (claude -p, --output-format) | en__headless.md |
| Chrome extension (UI verification) | en__chrome.md |
| Claude Code on the web | en__claude-code-on-the-web.md |
| Plugins | en__plugins.md + en__discover-plugins.md |
| Settings.json reference | en__settings.md |
| CLI reference | en__cli-reference.md |
| Status line | en__statusline.md |
| Channels (push events into a session) | en__channels.md + en__channels-reference.md |
| Auto mode config (classifier rules) | en__auto-mode-config.md |
| How Claude Code works (agentic loop internals) | en__how-claude-code-works.md |
| Agent SDK (build agents programmatically) | en__agent-sdk__overview.md and siblings |
For anything not listed, grep _llms.txt.
Load-bearing principles (nuance in en__best-practices.md)
Workflow
- Verify before claiming done: include tests, screenshots, or expected outputs so Claude can self-check — the highest-leverage single habit.
- Explore → plan → implement → commit; skip planning only when the diff fits in one sentence (Ctrl+G opens plan mode in a text editor).
- Specific prompts beat vague ones: name files, point to existing patterns, describe symptoms + likely location + what "fixed" looks like.
Context hygiene
- One concern per session — don't mix research/write/review in one context.
/clearliberally: after two failed correction attempts (a fresh session with a sharper prompt beats a corrected long one), between unrelated tasks, or before an unscoped "investigate X" (scope narrowly or delegate to a subagent instead).- Subagents for investigation — their reads don't pollute your context.
/btwfor side-questions — answers land in an overlay, never in history.
Cache hygiene (invalidation order: tools → system → messages; a change at level N
invalidates N and everything after)
- Don't, mid-session: edit CLAUDE.md (system block — edit between sessions or
/clearright after), switch models, toggle Shift+Tab fast mode, or enable/disable MCP servers. /compactrewrites the prefix — use at deliberate breakpoints, not reflexively.- Safe mid-session: pasted images, skill invocations, tool calls.
CLAUDE.md content discipline
- Loaded every session — per line, ask "would removing this cause mistakes?"; if no, cut. Bloat makes Claude ignore rules.
- Include bash commands Claude can't guess, non-default code style, test preferences, repo etiquette, env quirks. Exclude anything readable from code, standard conventions, tutorials, and frequently-changing info.
Parallel work
- Writer/reviewer: one session implements, a fresh one reviews (less bias toward just-written code).
- Worktrees for parallel edits that mustn't collide;
claude -pfor fan-out over files, scoped with--allowedTools.
Refreshing the mirror
Auto-refreshes weekly via cron; manual: ~/.claude/scripts/refresh-anthropic-docs.sh.
Source: https://code.claude.com/docs/llms.txt. Manifest with per-page SHA-256 + timestamps:
~/.claude/anthropic-docs/_manifest.json.