10 Common Claude Code Mistakes (and How to Fix Them)

March 8, 2026

I’ve been running Claude Code across 6+ projects daily for months. These are the mistakes I made early on — and the ones I still see other developers making. Each has a fix. Most fixes take less than five minutes.

1. Vague prompts

The mistake: “Add user authentication to the app.”

What happens: Claude Code builds an entire auth system. Maybe it picks JWT. Maybe sessions. Maybe it adds a database table you didn’t want. Maybe it installs three packages you’ve never heard of. The output is technically impressive and completely wrong for your project.

The fix: Write specs, not prompts. Specify the auth strategy, the packages to use, the file structure, the existing code to integrate with.

Add session-based authentication using the existing Express app.
Use passport.js with the local strategy.
Store sessions in the existing PostgreSQL database using connect-pg-simple.
Add auth routes in src/routes/auth.ts.
Add the session middleware in src/middleware/index.ts after the CORS middleware.
User model already exists in src/models/user.ts — use it.

That’s a spec that an AI agent can execute independently. The vague version is a wish.

2. Watching it work

The mistake: Reading Claude Code’s streaming output as it writes. Following along line by line. Mentally reviewing as it goes.

What happens: You spend 15 minutes watching something you’re going to review again afterward anyway. You’ve doubled your time on this task and you can’t work on anything else in parallel.

The fix: Paste the scope. Switch tabs. Come back when it’s done and review the diff. The code is the artifact. The process of writing it is not your concern.

3. Tasks that are too large

The mistake: “Build the entire onboarding flow for Triumfit.”

What happens: A 400-line diff that’s 70% right. The 30% that’s wrong is tangled into the 70% that’s right. Now you’re spending 30 minutes understanding what it built before you can figure out what to fix. You’d have been faster writing it yourself.

The fix: Break it down. The onboarding flow becomes: (1) create the welcome screen component, (2) add the goal selection step, (3) add the workout preference step, (4) wire up the flow navigation, (5) connect to the user profile API. Five tasks, five clean diffs, five fast reviews.

This is the core of scoping for agents. Smaller tasks are always better. Always.

4. No file path references

The mistake: “Update the header component to include a search bar.”

What happens: Which header component? The app has three. Claude Code picks one. Probably the wrong one.

The fix: Always specify file paths.

Add a search bar to the main app header in src/components/AppHeader.tsx.
Place it between the logo and the nav links.
Use the existing SearchInput component from src/components/ui/SearchInput.tsx.

File paths eliminate ambiguity. The AI doesn’t guess which file you mean. You don’t waste a review cycle discovering it picked the wrong one.

5. Letting it refactor adjacent code

The mistake: You ask for a new feature. Claude Code adds the feature and also “improves” three nearby functions, renames a variable for clarity, and reformats a file it opened for reference.

What happens: Your diff is now 80 lines instead of 20. The extra 60 lines are changes you didn’t ask for, didn’t review carefully because they weren’t the point, and might break something.

The fix: Set boundaries in your scope. “Only modify the files listed above. Do not refactor existing code. Do not rename existing variables or functions.”

I put a version of this in most of my project CLAUDE.md files. It’s that common.

6. No CLAUDE.md

The mistake: Running Claude Code in a project with no CLAUDE.md file. Every session starts with zero context about your project’s architecture, conventions, or patterns.

What happens: The AI makes reasonable-looking decisions that don’t match your codebase. It uses a different state management pattern. It puts files in the wrong directory. It uses a different error handling style than the rest of the project.

The fix: Create a CLAUDE.md in your project root. It doesn’t need to be long. Cover:

# Project

Brief description of what this is and the tech stack.

## Architecture

Where things live. Key directories and their purposes.

## Conventions

Error handling approach, state management, naming conventions,
test patterns.

## Don't

Things the AI should never do. Files it shouldn't touch.
Patterns it shouldn't use.

This is part of setting up Claude Code for real projects. Five minutes of setup saves hours of correcting wrong-pattern output.

7. Not using .claudeignore

The mistake: Claude Code has access to your entire project, including files it should never read or modify — environment files, credentials, generated code, large data files.

What happens: Sometimes nothing. Sometimes the AI reads a .env file and references values from it. Sometimes it modifies a generated file that will be overwritten on the next build. Sometimes it gets confused by a 10,000-line vendor file.

The fix: Create a .claudeignore file. Same syntax as .gitignore.

.env*
*.generated.*
dist/
node_modules/
vendor/
*.lock

Keep the AI focused on the code that matters.

8. Conversational coding for production

The mistake: Using Claude Code like a chat — asking questions, getting answers, iterating back and forth, building features through conversation.

What happens: It works for prototypes and exploration. It doesn’t work for production code across multiple projects. Conversational coding is synchronous. You’re locked into one task, one session, one project. You can’t parallelize it. You can’t walk away from it.

The fix: Use specs for production work. Conversations for exploration. Know which mode you’re in. If you’re going to ship the code, write a spec. If you’re figuring out an approach, have a conversation — then write a spec for the implementation.

9. Accepting output without reviewing

The mistake: The code looks clean. The feature works when you click through it. You commit without reading the diff.

What happens: Bugs. Not always. But often enough. An unhandled edge case. A security oversight. An unnecessary dependency added. A file changed that shouldn’t have been.

I shipped a Lucid bug this way — an export feature that crashed on entries with images because I didn’t notice the image path handling was missing from the diff. The feature worked when I tested it on a text-only entry. Five minutes of diff review would have caught it.

The fix: Read every diff. Three passes — structure, logic, style. No exceptions. The boring discipline of reading diffs is what makes this workflow reliable.

10. Treating it like a junior developer

The mistake: Giving Claude Code high-level direction and expecting it to figure out the details, the same way you’d delegate to a junior team member who knows the codebase.

What happens: A junior developer asks clarifying questions. They walk to your desk and say “did you mean X or Y?” Claude Code doesn’t. It picks one and builds it with confidence. If it picked wrong, you find out at review time.

The fix: Treat it like a contractor who’s never seen your codebase. Contractors are skilled. They can build anything. But they need a clear brief — what to build, where, using what materials, and what the finished product should look like.

That’s what a spec is. A clear brief for a skilled executor who doesn’t know your project and won’t ask follow-up questions.

The pattern

Most of these mistakes have the same root cause: not enough information upfront.

Vague prompt → bad output. No file paths → wrong files. No CLAUDE.md → wrong patterns. Too-big task → unfocused output. No review → shipped bugs.

The fix is always the same: more clarity before the AI starts working, more attention after it finishes. The work in between — the actual code generation — takes care of itself.