DEV Community

Cover image for 7 Mistakes I Made With Claude Code (And How I Fixed Them)
Muhammad Usman
Muhammad Usman

Posted on

7 Mistakes I Made With Claude Code (And How I Fixed Them)

#claudecode #ai #productivity #tooling

I've been using Claude Code daily for months. It lives in my terminal, it knows my codebases, and on a good day it feels like pairing with a senior engineer who never gets tired.

On a bad day, it wastes my time, hallucinates conventions, and racks up token costs for nothing.

The difference between those two experiences? Almost entirely configuration and habits — not the tool itself. After enough frustration, I started documenting what actually works. That turned into a GitHub repo of Claude Code best practices — guides, real CLAUDE.md templates, hook scripts, MCP configs, and a contributing workflow for teams.

Here's what I wish I'd known from day one.

Mistake 1: Not having a CLAUDE.md file

This was the biggest one. Without a CLAUDE.md, Claude has no idea what your project does, where things live, or what conventions your team follows. It guesses — wrong test commands, wrong file locations, wrong code style.

CLAUDE.md is a Markdown file you commit to your repo root. Claude reads it automatically at the start of every session. Here's a minimal one that actually works:

# MyApp

Node.js/Express backend with PostgreSQL.

## Commands
- `npm test` — run tests
- `npm run lint` — ESLint check
- `npm run dev` — start dev server

Run `npm run lint && npm test` before committing.

## Structure
- `src/routes/` — API route handlers
- `src/models/` — Sequelize models
- `src/middleware/` — Express middleware

## Rules
- TypeScript strict mode — no `any`
- All API responses: `{ data, error, status }`
- Use `src/utils/logger.ts`, not console.log
Enter fullscreen mode Exit fullscreen mode

Twenty lines. Claude now knows your commands, your structure, and your rules — every session, without you repeating yourself.

The repo has ready-to-use CLAUDE.md templates for React/TypeScript, Python/FastAPI, monorepos, and a minimal starter.

Mistake 2: Writing vague prompts

I used to say things like "fix the bug" or "clean up this file." Claude would explore broadly, make assumptions, and often miss the point entirely.

The fix is embarrassingly simple: be specific.

# Bad
"fix the bug"

# Good
"fix the null reference error in src/auth/login.ts:42
 where user.email is accessed before the null check"
Enter fullscreen mode Exit fullscreen mode

Point Claude at the file. Give it the line number if you have it. Tell it the symptom and the expected behavior. The more specific you are, the fewer tokens Claude wastes exploring, and the better the result.

Mistake 3: Never running /compact

Every message you send gets more expensive as the conversation grows — all that history is re-sent with each new message. I used to let sessions run for 80–100 exchanges without thinking about it.

/compact summarizes the conversation history, dramatically cutting context size. I now run it after every completed subtask:

/compact focus on the auth refactor
Enter fullscreen mode Exit fullscreen mode

The optional focus hint tells the compressor what to preserve. Everything else gets aggressively summarized.

Rule of thumb: /compact every 20–30 exchanges, or whenever you finish one piece of work and move to the next.

Mistake 4: Using --dangerously-skip-permissions in the wrong places

This flag disables all permission prompts. Claude can read, write, execute, and commit without asking. It's necessary for CI pipelines — but I made the mistake of using it locally on repos containing production credentials.

The rule I follow now:

  • CI/CD pipelines and containers → --dangerously-skip-permissions is fine and necessary
  • Local development on anything sensitive → never

In CI, pair it with --allowedTools to limit the blast radius:

claude -p "review src/ for bugs" \
  --dangerously-skip-permissions \
  --allowedTools "Read,Grep,Glob"  # read-only, no writes
Enter fullscreen mode Exit fullscreen mode

Full CI/CD patterns are in the CI and Automation guide.

Mistake 5: No .claudeignore file

Claude can read any file in your project. Without a .claudeignore, that includes your .env files, private keys, and credential configs.

.claudeignore uses the same syntax as .gitignore and lives at your project root:

.env
.env.*
credentials/
*.pem
*.key
secrets.yaml
Enter fullscreen mode Exit fullscreen mode

Files matching these patterns are completely invisible to Claude. Use it liberally — there's no cost to ignoring files Claude doesn't need. More security patterns are in the Security Practices guide.

Mistake 6: Trying to do too much in one session

I used to start a session and just keep going — bug fix, new feature, refactor, PR description — all in one 120-message conversation. By the end, Claude was confused about which decisions we'd made and why.

Claude works best with focused sessions. One goal per session. When you're done, commit and start fresh.

For large tasks touching more than a handful of files, use plan mode first:

plan how to refactor the authentication system to use JWT
Enter fullscreen mode Exit fullscreen mode

Review the plan. Ask questions. Only then:

looks good, go ahead and implement it
Enter fullscreen mode Exit fullscreen mode

Mistake 7: Not setting up hooks

Hooks let you run shell commands automatically when Claude performs an action. I went months without setting any up, which meant Claude's edits didn't always match my formatting standards and I had no audit trail.

Two hooks I now use on every project:

Auto-format after every file edit:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
    }]
  }
}
Enter fullscreen mode Exit fullscreen mode

Desktop notification when Claude finishes:

{
  "hooks": {
    "Notification": [{
      "matcher": "",
      "command": "osascript -e 'display notification \"$CLAUDE_NOTIFICATION\" with title \"Claude Code\"'"
    }]
  }
}
Enter fullscreen mode Exit fullscreen mode

The notification sounds minor but is genuinely useful — Claude often finishes while you've switched windows and you don't notice for five minutes. More ready-to-use hook scripts are in the examples folder.

The repo

All of this — and more — is in claude-code-best-practices. It includes:

  • Guides on CLAUDE.md setup, context management, cost management, MCP servers, multi-agent workflows, CI/CD automation, security practices, and team setup
  • CLAUDE.md templates for React, Python/FastAPI, monorepos, and minimal projects
  • Ready-to-use hook scripts and MCP server configurations
  • A CONTRIBUTING.md so the community can help keep it current

If you've found patterns that work (or patterns that don't), PRs are open.

What mistakes did I miss? Drop them in the comments — if enough people have hit the same wall, I'll add a guide.

Top comments (0)