====== Claude Code Best Practices Guide ======

===== 🚀 Getting Started =====

==== Installation & Setup ====
  * Install via npm:
    <code bash>
    npm install -g @anthropic-ai/claude-code
    </code>
  * Run in your project folder:
    <code bash>
    claude
    </code>
  * Run `/init` first  
    → Generates a starter `CLAUDE.md` based on your project structure  
    → Detects build systems, test frameworks, and code patterns  

-----

===== 📄 CLAUDE.md — Your Most Important File =====

`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.

==== Tips for a good CLAUDE.md ====
  * 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"

-----

===== 🧠 Context Window Management — #1 Priority =====

Claude's context window includes:
  * Messages
  * Files read
  * Command outputs

If it gets full → Claude may forget earlier instructions.

==== Practical tips ====
  * Use `/clear` between unrelated tasks
  * Pipe data instead of reopening files:
    <code bash>
    cat error.log | claude
    </code>
  * Provide URLs instead of pasting large docs
  * Resume sessions:
    <code bash>
    claude --continue
    claude --resume
    </code>

-----

===== 📋 Always Plan Before You Code =====

Planning reduces decision complexity.

Without planning → success rate ≈ 33%

==== Best practices ====
  * 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"**

-----

===== 🔁 Give Claude a Feedback Loop =====

Include:
  * Test commands
  * Linter checks
  * Expected outputs

Claude will:
  * Run tests
  * Detect failures
  * Fix issues automatically

==== Example prompt ====
<code>
Refactor the auth middleware to use JWT.
Run the existing test suite after.
Fix any failures before calling it done.
</code>

-----

===== 🪝 Use Hooks for Non-Negotiable Rules =====

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

==== Use hooks for ====
  * Formatting
  * Linting
  * Security checks

==== Example ====
Add `PostToolUse` hooks in:
<code>
.claude/settings.json
</code>

-----

===== 🤖 Sub-Agents & Parallel Work =====

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

==== Benefits ====
  * Keeps main session clean
  * Improves focus
  * Adds safety

==== Example roles ====
  * Code review agent → reads files only
  * Documentation agent → no shell commands

-----

===== ⚙️ Keep Things Simple =====

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

==== Avoid ====
  * Unnecessary features
  * Extra refactoring
  * "Nice-to-have" improvements

-----

===== 🛠️ Useful Commands & Shortcuts =====

^ Command ^ Description ^
| `/init` | Generate starter CLAUDE.md |
| `/clear` | Reset context window |
| `/config` | Set output style |
| `!git status` | Run shell command |
| `Shift + Tab (x2)` | Enter Plan Mode |
| `claude --continue` | Resume last session |

-----

===== 🔑 Key Mindset =====

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.

-----

===== 📚 Official Documentation =====

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