Claude Code Best Practices Skill

Apply these best practices from the official Claude Code documentation.

Core Constraint

Claude's context window fills up fast and performance degrades as it fills. This is the single most important resource to manage. All best practices flow from this constraint.

1. Give Claude a way to verify its work

• Always provide pass/fail checks: test suites, build exit codes, linters, output diffs, screenshot comparisons
• Without verification, "looks done" is the only signal and the user becomes the verification loop
• Choose strictness level: single prompt → /goal condition → Stop hook → verification subagent (independent reviewer)
• Claude should show evidence (test output, commands run, screenshots) rather than claiming success
• Provide verification criteria in the initial prompt, not after implementation

2. Explore first, then plan, then code

Follow four phases for non-trivial tasks:

1. Explore: Enter plan mode, read files, understand architecture, make no changes
2. Plan: Create detailed implementation plan (Ctrl+G lets user edit in text editor)
3. Implement: Exit plan mode, code + write tests + run test suite + fix failures
4. Commit: Descriptive commit message, create PR

Skip planning when: scope is clear, fix is small (typo, log line, variable rename), or diff can be described in one sentence.

Plan when: uncertain about approach, changes span multiple files, or modifying unfamiliar code.

3. Provide specific context in prompts

• Reference specific files, mention constraints, point to example patterns
• Scope the task: specify which file, what scenario, testing preferences
• Point to sources: direct to git history, documentation, API references
• Reference existing patterns: show Claude how similar things are done in the codebase
• Describe the symptom: provide bug symptoms, likely location, and "fixed" definition

Provide rich content via: @ file references, pasted screenshots, URLs, piped data (cat error.log | claude), or telling Claude to fetch context itself.

4. Configure your environment

CLAUDE.md

• Run /init to generate starter, then refine over time
• Include: Bash commands Claude can't guess, non-standard code style rules, testing instructions, repo etiquette, architectural decisions, environment quirks, common gotchas
• Exclude: anything Claude can figure out from code, standard conventions, detailed API docs (link instead), frequently-changing info, long tutorials, self-evident practices
• Rule of thumb: for each line, ask "Would removing this cause Claude to make mistakes?" If not, cut it
• Place at: ~/.claude/CLAUDE.md (global), ./CLAUDE.md (project root, check into git), ./CLAUDE.local.md (personal, gitignore), parent directories (monorepos), child directories (on-demand)
• Use @path/to/import to import additional files
• Add emphasis ("IMPORTANT", "YOU MUST") to improve adherence

Permissions

• Auto mode: separate classifier model reviews commands, blocks only risky ones
• Permission allowlists: permit specific safe commands like npm run lint or git commit
• Sandboxing: OS-level isolation restricting filesystem and network access

CLI tools

• Use gh, aws, gcloud, sentry-cli for external service interaction
• Claude can learn new CLI tools: "Use 'foo-cli-tool --help' to learn about it, then solve A, B, C"

MCP servers

• claude mcp add to connect Notion, Figma, databases, issue trackers, monitoring data

Hooks

• Deterministic scripts that run at specific workflow points (unlike CLAUDE.md which is advisory)
• Configure in .claude/settings.json, browse with /hooks
• Claude can write hooks for you

Skills

• Create SKILL.md in .claude/skills/ for domain knowledge and reusable workflows
• Invoke with /skill-name
• Use disable-model-invocation: true for workflows with manual side effects

Subagents

• Define in .claude/agents/ with independent context and tool permissions
• Useful for tasks reading many files or needing isolation

Plugins

• Bundle MCP servers, skills, and hooks for one-click installation
• Browse installed with /plugins

5. Communicate effectively

Ask codebase questions

• Ask like you'd ask a senior engineer — no special prompting needed
• Great for onboarding: "How does logging work?", "How do I make a new API endpoint?"

Let Claude interview you

• For larger features, have Claude interview first using AskUserQuestion tool
• Cover: technical implementation, UI/UX, edge cases, concerns, tradeoffs
• Write complete spec to SPEC.md after interview
• Start fresh session to execute spec (clean context focused on implementation)
• Best specs: name files/interfaces involved, state what's out of scope, end with end-to-end verification step

6. Manage your session

Course-correct early and often

• Esc: stop Claude mid-action, context preserved
• Esc+Esc or /rewind: open rewind menu, restore previous state or summarize
• "Undo that": have Claude revert changes
• /clear: reset context between unrelated tasks
• Rule: if corrected more than twice on same issue, /clear and start fresh with better prompt
• Clean session + better prompt > long session + accumulated corrections

Manage context aggressively

• /clear: completely reset context window (use frequently between tasks)
• /compact : compact with specific instructions
• /rewind → Summarize from here: condense from that point forward
• /rewind → Summarize up to here: condense earlier messages, keep recent full
• /btw: quick questions, answer in dismissible overlay, never enters history
• Customize compaction in CLAUDE.md

Use subagents for investigation

• Delegate research to subagents — they explore in separate context, report summaries
• Also use for post-implementation verification: "use a subagent to review this code for edge cases"

Rewind with checkpoints

• Every prompt creates checkpoint, files snapshotted before each change
• Restore: conversation only, code only, both, or summarize from selected message
• Checkpoints persist across sessions — close terminal and still rewind later
• Only tracks Claude's changes, not a git replacement

Resume conversations

• /rename sessions with descriptive names, treat like branches
• claude --continue: resume most recent, claude --resume: choose from list

7. Automate and scale

Non-interactive mode

• claude -p "prompt" for CI, pre-commit hooks, scripts
• Output formats: plain text, --output-format json, --output-format stream-json --verbose

Multiple sessions

• Worktrees: isolated git checkouts, edits don't collide
• Desktop app: visual management of multiple local sessions
• Claude Code on the web: cloud infrastructure, isolated VMs
• Agent teams: automated coordination, shared tasks, team lead

Writer/Reviewer pattern: Session A implements, Session B reviews in fresh context.

Fan out across files

• For large migrations: generate task list → write loop script → test on 2-3 files → run at scale
• Use --allowedTools to scope permissions for unattended batch operations

Auto mode for autonomous runs

• claude --permission-mode auto -p "fix all lint errors"
• Classifier blocks scope escalation, unknown infrastructure, hostile-content actions
• Non-interactive auto mode aborts if classifier repeatedly blocks (no user fallback)

Adversarial review step

• Subagent reviews diff in fresh context, reports gaps
• Prompt reviewer to flag only correctness/requirement gaps, not style preferences
• Warning: reviewers asked to find gaps will usually report some even when work is sound — don't chase every finding, leads to over-engineering

8. Avoid common failure patterns

9. Develop your intuition

• These patterns are starting points, not iron rules
• Sometimes let context accumulate (deep in one complex problem)
• Sometimes skip planning (exploratory tasks)
• Sometimes vague prompt is right (see how Claude interprets before constraining)
• Notice what works: prompt structure, context provided, mode used
• Ask why when Claude struggles: noisy context? vague prompt? too big for one pass?

Inter-chapter Relationships

Context Management (core constraint)
├── Provide specific context → fewer corrections → save context
├── Explore then plan → avoid solving wrong problem → save context
├── Manage context aggressively → /clear, /compact, subagents
└── Avoid failure patterns → kitchen sink, over-correction, infinite exploration

Verification (automation foundation)
├── Give verification means → unattended runs possible
├── Adversarial review → ensure correctness for long autonomous runs
└── Auto mode → batch unattended execution

Environment Configuration (multiplier)
├── CLAUDE.md → persistent knowledge every session
├── Skills → on-demand domain knowledge loading
├── Subagents → isolated investigation/verification
├── Hooks → deterministic auto-execution
├── CLI tools → efficient external service interaction
└── MCP servers → connect external data sources

Scaling
├── Non-interactive mode → CI/script integration
├── Multiple sessions → parallel development + independent review
├── File fan-out → large-scale batch operations
└── Agent teams → multi-task auto-coordination