Claude Code Best Practices and Common Pitfalls

Best Practices

1. Always Work in a Clean Git State

Before every Claude Code session, ensure you're in a git repository with a clean working tree:

git status      # Should show: nothing to commit, working tree clean

If there's uncommitted work, stash it:

git stash

A clean starting point means git diff after a session shows you exactly what Claude Code changed — nothing more.

2. Invest in CLAUDE.md Before Your First Real Task

The single highest-leverage action you can take before using Claude Code on a real project is writing a thorough CLAUDE.md. Include your stack, conventions, structure, commands, workflow, and constraints.

Time investment: 20–30 minutes. Time saved across all future sessions: substantial.

3. Review Changes with Git Before Accepting

Never end a Claude Code session without reviewing what changed:

git diff                    # See all unstaged changes
git diff --staged           # See staged changes
git add -p                  # Stage changes interactively, file by file

Interactive staging (git add -p) is the habit that catches subtle unwanted changes. Claude Code may modify files you didn't intend — the interactive staging review surfaces this.

4. Ask for Plans Before Execution on Risky Tasks

For any refactor that touches more than 5 files or modifies architectural patterns, ask for the plan first:

Describe what you would change to [accomplish task].
List every file you'd modify and what you'd change in each.
Do not make any changes yet.

Review the plan. Confirm it makes sense. Then authorize execution.

5. Use One-Shot Mode for Repetitive Tasks

If you're doing the same kind of task repeatedly, turn it into a one-shot command:

alias add-component='claude -p "Create a new React component with TypeScript, Tailwind, and a colocated .test.tsx file. Component name: $1. Follow CLAUDE.md conventions."'

Scripted tasks with known-good prompts are more reliable than re-prompting from memory each time.

6. Scope Tasks Clearly

Vague tasks produce broad, unpredictable changes. Scoped tasks produce targeted, reviewable changes.

Too broad:

Improve the codebase

Scoped:

In src/components/forms/, add proper TypeScript types to all form component
props. Do not change any logic or structure — only add/improve types.
Run typecheck when done.

---

Common Pitfalls

Pitfall 1: Not Reading CLAUDE.md-Generated Output

Running /init generates a CLAUDE.md but it reflects what's observable in code — not the constraints that live in your team's shared knowledge. The generated file will be missing conventions that aren't encoded in the codebase (e.g., "we never use default exports from utility files").

Prevention: Treat the generated CLAUDE.md as a draft. Edit it to add the knowledge that lives in your team's heads, not just in the files.

---

Pitfall 2: Auto-Approving All Commands

Responding "always" to every permission prompt removes your visibility into what Claude Code is doing. You end up in a situation where you don't know what commands ran or what they changed.

Prevention: Be selective. Auto-approve test runners and type checkers. Require approval for git operations, package installs, and anything that modifies infrastructure.

---

Pitfall 3: Large Vague Tasks Without Verification

Asking Claude Code to "refactor the entire services layer" without verification criteria produces large changesets you have to review entirely manually — which often takes longer than doing the refactor yourself.

Prevention: Add verification instructions to every substantial task: "run typecheck after each file change," "run the test suite when done," "report any tests that fail."

---

Pitfall 4: Working Without Git

Without git, Claude Code's file modifications are permanent. A misunderstood instruction can overwrite important code with no recovery path.

Prevention: Non-negotiable. Always use Claude Code inside a git repository. There is no substitute.

---

Pitfall 5: Using Claude Code for Architecture Decisions

Claude Code will give you an answer to "should we use REST or GraphQL?" But it's biased toward answering decisively (because decisiveness gets you to implementation faster) and it doesn't know your team's expertise, operational context, or long-term constraints.

Prevention: Use Claude.ai or a human expert for architectural decisions. Use Claude Code for implementing decisions already made.

---

Pitfall 6: Long Sessions Without /compact

After an hour in a single session, context has accumulated significantly. Claude Code's attention to early instructions degrades. Subtle drift — slightly inconsistent naming, small deviations from conventions — accumulates.

Prevention: Use /compact at natural task boundaries to compress context while preserving the essential thread.

---

Pitfall 7: Not Reading Security-Sensitive Generated Code

Claude Code generates plausible-looking security code — auth flows, permission checks, data validation. Plausible-looking is not the same as correct.

Prevention: Read every line of security-sensitive code before it ships: authentication logic, authorization checks, input validation, RLS policies, anything that handles user data.

The Right Mental Model

Claude Code is a senior engineer who executes reliably and quickly, never gets tired, and needs clear task definitions. It is not a system architect, not a security auditor, and not a product owner.

Your job in a Claude Code session: define clear tasks with verification criteria, review outputs critically, make architectural decisions, and maintain ownership of what ships.

Claude Code's job: implement those tasks correctly, run the verifications, and report results accurately.

Key Takeaways

• Git + CLAUDE.md + scoped tasks is the foundation of effective Claude Code use
• Review changes with git diff and git add -p before every commit
• Auto-approve only safe read-only and test operations
• Use Claude Code for implementation; use Claude.ai for design and architectural decisions
• Read security-sensitive generated code — it may be plausible but wrong

---

Try It Yourself: Run a Claude Code session and at the end, before committing, go through git add -p file by file. For each change, ask: (1) Did I ask for this? (2) Does it match my project's conventions? (3) If it's security-sensitive, is it correct? Note how many changes you would have missed without this review.