Working with Claude Code is a powerful experience — but like any powerful tool, the results depend enormously on how you use it. The difference between a frustrating session full of corrections and a smooth session where the code simply works almost always comes down to what you did before writing the first prompt.
This article is for everyone: if you’re senior, you’ve probably already intuited some of these things, but here we’re going to systematize them. If you’re junior, this is going to save you hours of headaches.
The Most Common Mistake: Jumping In Without Context
Most developers open Claude Code, write “build an authentication system with JWT” and expect magic. Sometimes it works. But when the project grows, when there are architectural decisions to respect, when there are team conventions… Claude starts making decisions that don’t align with your reality.
The problem isn’t Claude — it’s that it doesn’t have context. And without context, it improvises.
Step 1: The CLAUDE.md File — Your Contract with the Agent
The CLAUDE.md file in the root of your project is the most important tool you have. Claude reads it automatically at the start of each session. Think of it as the “onboarding” you’d give a new developer joining your team.
A good CLAUDE.md includes:
Exact stack and versions — Not “we use React”, but “React 18.3 with TypeScript 5.4, Vite as bundler, Tailwind 3.4”. The more specific, the fewer surprises.
Project conventions — Do you use camelCase or snake_case? Functional components only? How do you name test files? Where do global types go? These decisions that you already have automated in your head, Claude doesn’t know them.
Architecture and folder structure — A paragraph explaining how the project is organized is worth more than a thousand questions. “Business logic lives in /services, components in /components organized by feature, global types in /types.”
What it should NOT do — This is underestimated. If you don’t want Claude to install dependencies without asking, say so. If there are parts of the code that are legacy and shouldn’t be touched, mark them. If you have a linter configured and don’t want it overwritten, specify it.
Key commands — The commands to run tests, the build command, how to set up the local environment. Claude can execute them to validate its own work.
Step 2: Use /init on Existing Projects
If you’re incorporating Claude Code into a project that already exists, the /init command is your starting point. Claude will explore the project structure, read key files, and generate an initial CLAUDE.md based on what it finds.
It’s not perfect — you’ll always want to edit it — but it’s an excellent starting point that saves you 20 minutes of documenting the obvious.
Step 3: Break Down the Work Before Asking for It
Claude Code works best with well-defined tasks. Before starting a session, take 5 minutes to think about the boundaries of what you’re going to ask.
Instead of: “Implement the complete user module”
Better: “Create the User model with these fields, the registration endpoint with validation, and the JWT authentication middleware. Tests go in /tests/auth. Don’t touch the profiles module yet.”
The difference seems small, but you’re giving Claude a clear scope, a place to put things, and an explicit boundary of where to stop. That reduces errors and reduces the risk of it modifying code it shouldn’t.
Step 4: Exploration Mode vs. Execution Mode
Claude Code has two modes of operation and knowing when to use each one changes everything.
Exploration mode — Ask it to understand, analyze, or propose before acting. “Read the payments module and tell me how you’d implement support for multiple currencies without breaking what exists.” This is invaluable before big changes. You see the plan, you question it, you adjust it — and only then do you execute.
Execution mode — Ask it to implement directly with clear instructions. Ideal when you already know what you want and the scope is well-defined.
The classic mistake is using execution mode when you needed exploration first. You end up with a technically functional implementation that doesn’t fit your architecture, and now you have to undo work.
Step 5: Set Checkpoints, Not Long Sessions
Very long sessions with Claude Code accumulate context that eventually becomes noise. It’s better to work in blocks — implement one part, review, commit, and start a new session with clean context for the next part.
A workflow that works well:
- Exploration session → understand the problem
- Implementation session → concrete code with delimited scope
- Human review → read the diff, understand what changed and why
- Commit with descriptive message
- New session for the next block
This workflow keeps you in control of the project. You don’t delegate — you collaborate.
The Benefits in Execution
When you prepare the context well, the benefits are immediate and cumulative:
Fewer corrections — Claude makes decisions aligned with your stack and conventions from the first attempt. You don’t have to repeat “use strict TypeScript” in every session.
More consistent code — The style, folder structure, error patterns — everything follows your conventions because you documented them.
Fewer architectural hallucinations — Without context, Claude can propose valid solutions that don’t fit your project. With context, proposals are more grounded.
Shorter and more productive sessions — Paradoxically, investing time in preparation reduces the total project time. Corrections are expensive.
A history of decisions — Your CLAUDE.md becomes living documentation of the project. Anyone (or any future instance of Claude) can understand the project by reading it.
Quick Checklist Before You Start
Before your next Claude Code session, check this:
- Do you have an updated
CLAUDE.mdwith the stack, conventions, and constraints? - Is the scope of what you’re going to ask clear and delimited?
- Do you know if you need exploration or execution first?
- Do you have tests and linter running so Claude can validate its work?
- Are you on a clean branch so you can roll back if something goes wrong?
If you answered yes to everything, you’re ready. If not, five minutes of preparation now will save you an hour later.
Claude Code is not a replacement for developer judgment — it’s a multiplier of it. And like any multiplier, it amplifies both the good and the bad. Give it good context, give it clear scope, keep yourself in the review loop, and you’ll see results that completely justify the change in workflow.