How I actually use Claude Code

People keep asking me what my Claude Code workflow looks like, and every time I start to answer I realize the honest answer is weirder than the version I would put on a tweet.

The tweet version is "I use Claude Code for everything, it writes most of my code, I review it." The tweet version is technically true and also completely useless, because it does not tell you the thing that actually matters: how I got from "I tried it and it was fine" to "I cannot imagine building without it." So I am going to try to write the honest version. Not the demo version. The one I actually run on a Tuesday at 11pm when I am tired and the stakes are small and I just want the thing to be done.

The way most people use Claude Code, for the first two weeks, is as a faster autocomplete. You open a file, you describe a change, it writes the change, you accept or edit. This works. It will make you about 30% faster. And it is the wrong frame, because 30% faster is not why you are using it.

The right frame took me a month to find, and it is this: Claude Code is not a faster you. It is a different kind of collaborator, and the thing you are optimizing for is not lines per minute but rounds per hour. How many complete, honest "I tried it, here is what happened, here is what is next" rounds can you go through in a working session? That number is what decides whether a project ships this week or next month, and once you start measuring your sessions by rounds instead of lines, everything about how you work with the thing changes.

A round is: I describe a goal, it attempts, I look at the real result (not the claim, the result), I either accept or push back with specific feedback, and we move to the next goal. A bad session is ten rounds where I did not read what it actually did. A good session is three rounds where the first one teaches me what I should have asked for in the second. Rounds, not lines. Write that down somewhere.

Every project I use Claude Code on has a CLAUDE.md at the root. It is not the default one. It is a file I rewrite for every repo, and it contains the five things I would have told a new collaborator if they walked into the room: the goal of the project, the stack and the non-obvious parts of it, the things I have already tried and ruled out, the things I specifically do not want it to touch, and the way I like the work reviewed.

That last one is the most important and the one nobody writes down. "Show me the diff, not a summary" is a sentence in my CLAUDE.md. So is "do not add docstrings or comments to files you are editing unless I asked." So is "when a test fails, tell me what you ran and what the error was before you start guessing." These are not preferences. They are the difference between a session that produces five real rounds and a session that produces one giant wall of slop I have to undo.

If you are not rewriting your CLAUDE.md every few weeks, you are not using the tool. The file is not a config. It is an accumulation of the lessons from your last ten sessions, written down so that the next session does not repeat them.

The second habit that changed everything: make it write a plan before it writes code. Not a fake plan. A real one, with file paths and function names and the specific change you expect in each place. If the plan is wrong, that is a two-minute fix. If the code is wrong, that is a thirty-minute fix, because now you have to read what it did and unwind it.

I have a stock phrase for this, which I type at the start of almost every non-trivial task: "Before you write any code, tell me the specific files you would edit, the specific functions you would touch, and what the change would be in each. I will approve or push back before you start." About half the time, the plan comes back and I change it. The other half, the plan is right, and the code is right on the first try, and I have just bought myself an hour by spending thirty seconds reading a list.

Plans are also how you catch the thing it is most likely to get wrong: scope drift. Left alone, it will "improve" files you did not ask it to touch. A plan forces the scope to be explicit. If a file is not in the plan, it should not be in the diff.

I use Claude Code in three different modes, and I switch between them consciously depending on what the task is.

1. 1.Surgical. The task is small, the files are known, the fix is specific. "In lib/posts.ts, change the category field to be optional and add a default of 'Uncategorized' in the blog index." This mode is where Claude Code is fastest, and it is also where the tweet version of my workflow is technically accurate. I describe, it does, I accept. No ceremony. Most of my day is this mode.
2. 2.Exploratory. I do not know what the right fix is yet, and I want it to help me figure it out. These sessions start with "I am seeing X, I think it might be Y, but I have not confirmed. Can you look at the code and tell me what you think before we touch anything?" The key word is "before." If you let it start editing in exploratory mode, you will waste an hour. The exploratory mode is read-only until I have agreed on a diagnosis.
3. 3.Full-build. A whole feature, start to finish. This is where I write a real plan with it, file tree, data flow, one paragraph per component, and then I let it go for twenty or thirty minutes, and then I do a full review of the diff. In full-build mode the single most important skill is the willingness to throw the session away and start over if the plan drifted. I used to try to salvage drifted sessions. It is always faster to restart with a better prompt than to fix a bad one.

I have stopped reading its summaries. The summary is the least reliable thing it produces. It will cheerfully tell me "I updated the CSS and the tests pass" when neither thing is true, not because it is lying but because the summary is generated from the same probability distribution as the code, and the code and the summary can drift apart in small ways that do not matter individually and catastrophically in aggregate. So I read diffs. I run tests myself. I do not trust "I fixed it" until I have seen the before and after with my own eyes.

I have also stopped asking it for code I am not going to review. If the change is big enough that I am not going to read every line, the task is too big and I need to break it up. This sounds obvious. In practice it is the single hardest discipline to maintain, because the tool is so good at producing plausible code that you are tempted to trust it. Do not trust it. Read every diff.

And I have stopped arguing with it when it gets something wrong. If I push back twice and it still does not get it, the problem is almost never that it is stupid. The problem is that my prompt is ambiguous, or my CLAUDE.md is missing context, or the task itself is too large. The fix is to back up, rewrite the prompt, and try again, not to keep correcting mid-stream. Mid-stream corrections are where bad sessions come from.

Two things surprised me, and I want to mention them because they are probably where you are under-using the tool.

One is reading code you did not write. I have used it on three old repositories in the last month where I needed to make a change to a codebase I had never seen. The workflow is: "Before we do anything, read these files and tell me the architecture in plain English, what each module is responsible for, and where the surprising parts are." It is better at this than I am, because it reads linearly and patiently and without the ego that makes me skim. The first ten minutes of any unfamiliar-codebase task should be spent making it explain the code to me. I get up to speed twice as fast as I would on my own.

Two is writing the boring stuff that I should have written but never got around to. Test fixtures. Error messages. Migration scripts. README sections. These are the jobs I would otherwise procrastinate on for weeks, and they are exactly the jobs it is best at, because they are bounded and structured and the quality bar is "correct, not clever." I now batch them up and do them in fifteen-minute sprints at the end of the day when my brain is too tired to build anything real.

One last thing. The same rule I use for my blog writing, read it out loud, does it sound like a smart person talking, applies to how I prompt Claude Code. If I cannot say the prompt out loud as a sentence a human would say to another human, the prompt is wrong. "Refactor the blog index to use a category filter with active state" is a prompt a human would say. "optimize code" is not. The more your prompt sounds like instructions you would give a smart collaborator over a cup of coffee, the better the result.

Rewrite your CLAUDE.md after every session where something went sideways, and include the lesson from what went sideways. The file is a living document. Treat it like one.

Make it write a plan before it writes code on anything that touches more than one file. Reject the plan if it is vague. Reject it again if it is wrong. Plans are cheap; undoing code is not.

Stop reading summaries. Read diffs. Run tests. The only claims you should trust are the ones you verified with your own eyes.

Pick the mode consciously. Surgical, exploratory, full-build. If you do not know which one you are in, you will default to surgical, and surgical is wrong for two out of three real tasks.

When it gets stuck, back up. Do not argue. Rewrite the prompt, add to the CLAUDE.md, try again with more context. The fix is almost always upstream of where you are fighting.

So: what does your CLAUDE.md look like right now? If the answer is "the default" or "I don't have one," that is the single biggest change you can make this week. Write the file. Rewrite it in a month. You are not using the tool until you have customized the thing that tells the tool how to work with you.