Most people's first hour with Claude Code goes the same way. They ask it something small, it does something surprisingly large, and they either close it or start trusting it too much. Both reactions come from the same missing idea about what the thing is.
This is written for that first hour. Not a feature tour, which the documentation does better and which goes stale every few weeks anyway, but the mental model and the four mistakes that cost people the most time.
What Claude Code actually is
It is an agent that works inside your project. It runs in your terminal, and also in a desktop app, in a web app, and inside editors like VS Code and JetBrains, but the surface is not the important part.
The important part is that it reads your real files, edits them, runs your real commands, and reads the output to decide what to do next. You give it a goal rather than a line to complete, and it goes and does several steps toward that goal on its own.
That is a different category of tool from the two things people usually mistake it for. Autocomplete predicts the next few tokens where your cursor is. A chat window can talk about code you paste into it. Neither of them can open a file you did not mention, run your test suite, read the failure and change its approach.
Everything below follows from that one difference.
Mistake one: giving it a task instead of a goal, or a goal instead of a task
There are two opposite errors here and beginners usually make both in the first day.
The first is treating it like autocomplete: asking for one small edit at a time and reviewing each. That works, and it wastes most of what the tool is for. If you can describe the finished state, describe the finished state.
The second is the opposite and more expensive. Asking for something enormous and vague, like making the app faster or cleaning up the codebase, produces a large diff touching many files, built on assumptions you never saw it make. It usually looks plausible and is very hard to review.
The size that works is a task you could explain to a competent new colleague in a couple of sentences, where you would recognise a correct result when you saw it. Bounded enough to check, big enough to be worth delegating.
Mistake two: not reading the diff
This is the one that actually hurts, and it is tempting precisely because the output usually looks good.
Generated code fails differently from code somebody wrote. It tends to be locally correct and globally wrong: clean naming, sensible structure, and a subtly different problem solved from the one you had. Nothing about the surface of the change signals it.
So read the diff before you accept it, and read it as a reviewer rather than as an author. The question is not whether the code looks reasonable, because it will. It is whether it does the thing you actually wanted, in the way your codebase already does things.
This is not a temporary limitation to wait out. Reviewing is the part of the job that moved toward you when producing got cheap.
Mistake three: explaining your project conventions over and over
The single highest-leverage thing a beginner can do is write the project's rules down where the agent reads them, rather than repeating them in every conversation.
Claude Code looks for a CLAUDE.md file in your project and treats it as standing instructions. Put in it the things you would tell a new engineer on their first day and would be annoyed to repeat: which package manager this repo uses, how to run the tests, the conventions that are not obvious from the code, and the specific mistakes people make here.
The trick is that it should be corrections rather than aspirations. A rule earns its place after somebody, or something, gets it wrong once. A file full of general good intentions is noise; a file that says do not use this command because it silently corrupted the database last month is worth a great deal.
Every hour spent on that file pays back across every future session, which is not true of anything you type into a single conversation.
Mistake four: assuming it knows what it cannot know
It knows your code, because it can read it. It does not know what is in your head, what was decided in a meeting, which of two similar functions is the one that matters, or that the ticket is wrong.
It also cannot tell you when it is out of its depth. There is no equivalent of a colleague saying they are not sure. It produces a confident answer either way, and confidence carries no information about correctness.
The practical version: supply the context that is not in the repository, and be specific about what would count as done. Most disappointing results are a missing constraint rather than a missing capability.
What to do on day one
A short version, in order, that will get you further than reading about it will.
- Pick a real task you already know how to do, so you can judge the result. Not a toy, and not something critical.
- Ask for the finished state rather than the first step, then read the whole diff before accepting anything.
- Write a CLAUDE.md the first time you find yourself repeating an instruction. Add to it every time you correct the same thing twice.
- Ask it to explain a part of the codebase you do not know. Reading is where it is most reliably useful and least risky.
- When something comes back wrong, look at what context was missing before you conclude the tool cannot do it.
The part that does not get easier
Getting good at Claude Code is mostly not about learning the tool. The commands are quick to pick up and they change.
What takes longer is the judgement to tell a good result from a plausible one in your own domain, and that is the thing the tool cannot supply for you. It makes producing cheap, and leaves deciding whether the output was worth producing exactly where it was.
Which is the useful frame for beginners: you are not learning to type instructions. You are becoming the reviewer of a fast, confident, tireless colleague who is occasionally wrong in ways that look right.