Claude Code for working engineers: what the tutorials skip
Most Claude Code tutorials are the same video: install it, type "build me a todo app," watch files appear, marvel. That is not how you will use it. You have a codebase with ten years of decisions in it, a CI pipeline that fails for reasons nobody remembers, and a review process. The question a working engineer has is not "can it write code" but "how do I run it on a real repo without it making a mess, and how do I know when to trust it."
This guide is that. It assumes you are a developer who ships, you have tried a coding agent for an afternoon, and you want the mental model that the install tutorials skip.
What one turn actually does
The single most useful thing to understand about Claude Code is that it is a loop, not a chat. You type a message. The model reads your message plus everything it can see (the conversation so far, your CLAUDE.md, the files it has opened), decides on an action, and takes it: read a file, run a command, edit a file, search. It looks at the result and decides on the next action. It keeps going until it thinks the task is done, then it talks to you.
Everything else follows from that. The agent is only as good as what it can see, so context is the whole game. It runs real commands, so permissions matter. It decides when it is done, so the way you describe "done" decides what you get.
Two habits fall out immediately:
- Give it a way to check its own work. "Make the tests pass" is a task with a verifiable end. "Improve the error handling" is not. An agent with a test command runs it, reads the failure, fixes it, and runs it again. An agent without one guesses and stops.
- Say what done looks like before it starts. Typecheck clean, lint clean, this test green, no new dependencies. The loop terminates on the condition you gave it.
Plan mode first, on anything you cannot undo in a minute
Claude Code has a plan mode: the agent reads and thinks but does not edit or run anything that changes state, then shows you a plan you approve before it executes. Tutorials mention it as a feature. Working engineers use it as a default for anything bigger than a one-file change.
The reason is not that the model is bad at planning. It is that a plan is the cheapest place to catch a misunderstanding. If it read the request as "migrate the auth module" and you meant "add one field to the session," you find out from a five-line plan instead of from a forty-file diff. Plan, correct, approve, execute. The extra minute is paid back on the first task where the plan was wrong.
The related tool is checkpoints. Every edit the agent makes is recoverable; you can rewind a session to before a change the same way you would reset a git branch. That is what makes "let it try" a safe instruction. Try, look, rewind if wrong.
CLAUDE.md is the interview you never have to repeat
Every new engineer on your team gets the same half-day briefing: here is how we run tests, here is the directory layout, never touch that generated file, we do not use that library, commit messages look like this. Claude Code reads a file called CLAUDE.md at the root of your repo at the start of every session. That file is the briefing.
What goes in it is exactly what you would tell a strong contractor on day one, and nothing else:
- The commands: build, test, lint, typecheck, dev server. With the exact flags.
- The layout: where the app code is, where the server-only code is, what is generated and must not be edited by hand.
- The conventions that are not derivable from the code: naming, what "done" means, what never to run (deploys, migrations against production).
- The one-line reasons behind rules that look arbitrary, so the agent does not "fix" them.
What does not go in it: a tour of the whole codebase, aspirations, anything the agent can read from the code itself. A long CLAUDE.md is worse than a short one, because it is read on every turn and every line of it competes for attention with your actual request.
A good test: if a new senior hire would need to be told it on day one, it belongs in the file. If they would figure it out by reading the code in ten minutes, leave it out.
Permissions: the setting most people get wrong in both directions
By default Claude Code asks before running commands or editing files. New users click "allow" fifty times an hour and then, exhausted, switch to allow-everything mode, and that is where the "it deleted my branch" stories come from.
The right setup is neither. Allow the boring, safe, reversible things permanently (reading files, running the test suite, git status, the formatter). Keep the ask on anything that touches the world outside the repo (pushing, deploying, deleting, installing packages, anything with credentials). Deny outright the things that should never happen from a session (force push to main, touching production config). That is a five-minute settings file and it turns a nagging tool into one you can leave running.
If you work on anything sensitive, run it in a container. A sandbox with only the repo mounted means the worst case of a bad command is a rebuilt container, not a rebuilt laptop. The course spends a full lesson on this because it is the difference between "I tried it once" and "I use it every day."
Context is a budget, and you are spending it
A session has a context window. Every file it reads, every command output, every message you send takes up space in it. When it fills, the session compacts: older material is summarized and the detail is gone. Long sessions get worse not because the model tires but because it is working from a summary of what it saw an hour ago.
Working habits that keep the budget in hand:
- One task per session for anything substantial. Finish, commit, start fresh. The new session reads
CLAUDE.mdand the diff and is sharper than the old one at hour two. - Point it at files instead of letting it search when you already know where the code is. A search that reads twenty files costs twenty files of context.
- Fan out big read-only jobs to subagents. "Find every caller of this function across the repo" in a subagent returns a short answer to your session instead of filling it with grep output.
- Watch what it re-reads. If it opens the same 2,000-line file three times, tell it to keep notes or split the task.
Where it is genuinely worse than you, and where it is better
Be honest about the shape of the tool, because the tutorials are not.
It is better than you at: reading a large unfamiliar codebase quickly, writing the boring 80% of a change, generating tests for code that has none, and doing mechanical migrations that would bore you into mistakes. It does not get tired at file forty.
It is worse than you at: knowing what you did not say, noticing that the ticket is wrong, and stopping. Given an impossible task it will try increasingly creative things instead of asking. Given a vague one it will pick an interpretation and commit to it. Both are your job to catch, and the earlier you catch them (plan mode, small tasks, a test to fail) the cheaper they are.
The engineers getting the most out of it are not the ones who prompt best. They are the ones who already had good engineering hygiene (tests, a fast build, clear conventions, small commits) because every one of those makes the loop converge faster. If your repo is hard for a new human to work in, it is hard for the agent too, and fixing that pays twice.
Where this goes
Everything above is the first module of the claude code course, which takes a working developer from a first session to shipping a real API end to end: the agent loop, plan mode and permission modes, context engineering with CLAUDE.md, the daily workflow on a real codebase, git and pull requests, test-driven work with the agent, running it safely in a container, and prompt injection (the attack your own repo can run on you). A second course, claude code pro, covers extending it: skills, hooks, MCP, subagents, and using it as a Unix command in CI.
The course is in early access as lessons are recorded, so the curriculum on the course page is a sketch that will shift. If you want to be told when lesson one lands, that page has the button.
