Claude Code in a folder you already have

Writing CLAUDE.md from scratch – the way the lesson on your first one goes about it – makes sense when you’re starting from an empty directory. When the folder already holds a year of your work, the situation is different: a good deal of context can be read off those files, and retyping it by hand is fairly dull work.

That’s where /init comes in. The command goes through the project’s contents and builds a first version of CLAUDE.md from them. This lesson walks through running it on a folder of your own and, more importantly, through what to do with the result.

Because the result isn’t finished. Claude Code infers from what it sees, and some of those inferences will be off – catching them is today’s job.

Pick a folder that genuinely holds something

This exercise needs a folder you can look at and say whether what Claude Code writes about it is true. Without that there’s no way to judge the result, and judging the result is what the whole lesson is about.

So pick something you know inside out: a project you’ve been sitting with for months, a documentation directory, a website repository.

If the folder is a git repository, so much the better: you’ll have git diff as a second pair of eyes on everything that gets written.

See what Claude Code can make of it

Open a terminal and go into that folder with cd and the path, for example cd ~/projects/company-site. Run claude and, before you call /init, ask a scouting question:

Look around this directory and tell me what this project is and how it's organised.

The answer is interesting in itself, because it shows how much context can be read off the file structure alone. Usually quite a lot – directory names, config files, a README – and usually with one or two places where Claude Code drew a conclusion further than the evidence supports.

Remember those places. You’ll meet them again shortly, this time written into a file, and by then they’ll look like facts.

Run /init

Type:

/init

Claude Code works through the folder’s contents and builds CLAUDE.md out of what it finds: build and test commands, conventions, the directory layout, anything inferable from the files. Depending on what’s in the folder and how big it is, this takes anywhere from tens of seconds to a few minutes.

One thing worth knowing if you also work with other tools: /init reads Cursor rules (.cursor/rules/ or .cursorrules) and Copilot rules (.github/copilot-instructions.md) along the way and folds in the relevant parts. So if your project conventions are already written down somewhere, you don’t have to retype them.

When it finishes, the file is on disk. Don’t close the session yet.

Have Claude Code mark its own guesses

Hand the first pass to whoever wrote the file:

Go through the CLAUDE.md you just created. List which sentences you read straight out of the files and which are your own guesses – and which ones you are least sure about.

You get a short list instead of sixty lines, and that list is the real material to work with. The guesses are exactly the places only you can settle: Claude Code won’t know that the component it saw was the exception nobody got round to fixing.

Four things turn up in such a list most often:

1. Conclusions drawn from a single example. Claude Code saw one component written a certain way and described it as a project convention. Sometimes that was the exception nobody got round to fixing.
2. A description of state instead of an instruction. “The project uses library X” is a fact Claude Code will read off the files every session anyway. The space in this file is better spent on what the files don’t show – why X, and what not to do with it.
3. Out-of-date pieces of the structure. A directory left over from an earlier version of the project can end up described as a living part of the layout.
4. Commands copied from the README that nobody uses any more. Worth checking whether the build command given actually runs – it’s one of the things that look most trustworthy in a generated file and are most often stale.

It isn’t that /init writes badly. It’s that it writes from what it can see, and you see more.

Fix it in the chat, not in an editor

Go back to the session the file came out of and dictate the corrections. Whatever you caught while reading is enough said in a plain sentence:

In CLAUDE.md, drop the point about the component naming convention – that was a one-off exception, not a project convention. Cut the description of the legacy directory too, it has been dead for six months.

Deleting from this file is safe: a removed line stops reaching the conversation and nothing breaks because of it.

It’s worth being ruthless, because a longer file works less well. The documentation suggests staying under two hundred lines – not for tidiness, but because a bloated file takes room in the conversation’s memory and Claude Code sticks to it less closely.

Then dictate what Claude Code had no way of knowing. That’s usually the most valuable part of the whole file, because it covers things that aren’t in the files at all:

• agreements with a client that nobody wrote down anywhere,
• history along the lines of “we don’t touch this directory, it’s deployed separately”,
• your own boundaries – what gets done without asking, and what always needs approval,
• conventions that apply even though the code doesn’t reflect them yet.

Phrase it concretely. “Indent with tabs” is a clear instruction; “write nice code” much less so.

The editor was useful for reading the file and for nothing else. You leave the changes to Claude Code – because it laid the file out in the shape that suits it, and because dictating corrections is the same skill you practise on every other task.

Check it in a new session

The file is read at startup, so the current session doesn’t know about your corrections. Close it and run claude again.

Ask something that forces the specific instruction you just added into play. Don’t ask generally whether it knows the project’s rules, because you’ll get a summary of the file, which proves nothing beyond the file having loaded.

One misconception circulates around /init and is worth putting straight: this command creates no hidden memory. It creates a file you can open and read, and that’s the whole of its magic. Claude Code has a separate automatic memory mechanism, where it notes conclusions from your corrections itself – a different thing, unconnected to this command. We’ll come back to it in a post of its own.

Run /init a second time

Let’s do a small experiment.

Call /init again, in the folder where CLAUDE.md now exists – after your corrections. Claude Code won’t overwrite it. Instead it goes through the project and suggests improvements to what’s already there.

That changes how to think about the command. /init isn’t a one-time wizard you run when setting a project up, it’s a tool you can come back to once the project has grown and the file stopped describing it. Incidentally: when the file gets too long, /doctor can propose trims for it.

Judge the suggestions from the second run exactly as you judged the first version – reading, not accepting. This lesson is really, from end to end, about that one habit.

Tasks

Tick these off as you go. The state is remembered in your browser, so you can come back to this list tomorrow.

• A folder with real work of my own picked
• Scouting question asked before /init
• /init run, CLAUDE.md created
• List of guesses pulled out of Claude Code and reviewed
• Wrong parts removed in the chat
• Dictated what Claude Code had no way of knowing
• A new session confirms the instruction I added is working
• Second /init run, suggestions looked at rather than accepted blind