Claude Code Best Practices Guide

• Install via npm:

    npm install -g @anthropic-ai/claude-code
 

• Run in your project folder:

    claude
 

• Run `/init` first

→ Generates a starter `CLAUDE.md` based on your project structure

  → Detects build systems, test frameworks, and code patterns  

`CLAUDE.md` is a special file that Claude reads at the start of every conversation.

Include:

• Bash commands
• Code style
• Workflow rules

This gives Claude persistent context it cannot infer from code alone.

• Document what Claude gets wrong (not just what to do)
• Avoid referencing full docs inline

→ Use: “For complex usage, see path/to/docs.md”

• Keep rules actionable

→ Instead of:

    "never use --foo-bar flag"  
  → Write:  
    "never use --foo-bar; prefer --baz instead"

Claude's context window includes:

• Messages
• Files read
• Command outputs

If it gets full → Claude may forget earlier instructions.

• Use `/clear` between unrelated tasks
• Pipe data instead of reopening files:

    cat error.log | claude
 

• Provide URLs instead of pasting large docs
• Resume sessions:

    claude --continue
    claude --resume
 

Planning reduces decision complexity.

Without planning → success rate ≈ 33%

• Use Plan Mode (press `Shift + Tab` twice)
• Plans persist across context resets
• For large features:

→ Ask Claude to write a spec first

  → Say: **"don't implement yet"**

Include:

• Test commands
• Linter checks
• Expected outputs

Claude will:

• Run tests
• Detect failures
• Fix issues automatically

Refactor the auth middleware to use JWT.
Run the existing test suite after.
Fix any failures before calling it done.

• `CLAUDE.md` → advisory (~80% compliance)
• Hooks → deterministic (100%)

• Formatting
• Linting
• Security checks

Add `PostToolUse` hooks in:

.claude/settings.json

• Sub-agents run in separate context windows
• Return compressed summaries

• Keeps main session clean
• Improves focus
• Adds safety

• Code review agent → reads files only
• Documentation agent → no shell commands

• Simple control loops > complex systems
• Avoid over-engineering
• Only implement what is requested

• Unnecessary features
• Extra refactoring
• “Nice-to-have” improvements

Successful users:

• Manage context carefully
• Plan before coding
• Keep systems simple
• Use hooks for quality control
• Continuously improve `CLAUDE.md`

Key idea: The difference between frustration and productivity is not the tool — it's how you use it.

https://code.claude.com/docs/en/best-practices