/init scans your project and drafts a CLAUDE.md with build commands, how to test, and conventions. Use it to avoid starting from a blank file.
How it works
When you run /init, Claude analyzes the codebase and creates a CLAUDE.md with the build commands, test instructions, and project conventions it finds. If a CLAUDE.md already exists, it does not overwrite it and suggests improvements instead.
The generated file is a starting point. The official docs also say to refine it by adding instructions Claude would not discover on its own. The draft fills in facts that can be read from the code, but context such as team agreements and things not to do has to be written by a person.
How to use it
Run claude in the project root and type /init. When it finishes, open the file and review the contents. You can also open and edit it with /memory.
- Step 1: run claude in the project root
- Step 2: type /init
- Step 3: in the generated CLAUDE.md, delete wrong commands and unneeded explanations
- Step 4: add rules the code cannot tell you (commit rules, folders not to touch)
- Step 5: in a new session, run /context and check that the file appears in the Memory files list
claude /init
Interactive mode and variations
If you set the environment variable CLAUDE_CODE_NEW_INIT=1, /init turns into a multi-step interactive flow. It first asks what to create among CLAUDE.md, skills, and hooks, explores the codebase with subagents, fills in gaps with follow-up questions, and shows a proposal you can review before writing any file. You can set it in your shell or in the env block of a settings file. It only changes how /init runs, so it is fine to leave it on.
If it finds OpenAI Codex or Google Gemini CLI configuration, it may also offer to bring it in with /import. If the repository already uses AGENTS.md, you can import it from CLAUDE.md with @AGENTS.md.
How it relates to nearby features
- CLAUDE.md: the output /init produces, and the file you manage by hand afterward.
- /memory: opens the file for editing after it is created, and turns auto memory on or off. /init is for the first creation and /memory is for managing it afterward.
- Auto memory: notes Claude writes for itself from your corrections during a conversation. It is separate from /init.
Real examples
In a Next.js repository you just received, Claude keeps fumbling for the command to run tests
Run claude in the project root, then /init
Claude analyzes the repository and drafts a CLAUDE.md with the run commands and structure. Run each generated command once to check that it actually works, and fix the wrong parts. From the next session on, you do not have to repeat the same explanation.
A CLAUDE.md already exists, but it is old and no longer matches the current structure
/init
It does not overwrite the existing file and suggests improvements instead. Apply only the suggestions that are right, and delete rules you no longer use yourself.
You want to set up hooks and skills along with CLAUDE.md
Run with CLAUDE_CODE_NEW_INIT=1 claude, then /init
It asks what to set up first, explores the codebase, and shows a proposal for review. It does not write files until you approve.
Common mistakes and when not to use it
- Using the generated draft as is without review. The analysis may write wrong commands or trivial facts. Run them and check.
- Leaving a bloated draft as it is. The official recommendation is under 200 lines per file. Delete entries that are not useful.
- Thinking one /init run is the end. When the project changes, CLAUDE.md needs to change with it.
- Expecting much when the codebase is nearly empty. With nothing to analyze, the draft is thin too. In that case, writing a few lines yourself is better.
FAQ
If I run /init again, will my existing CLAUDE.md be gone?
No. The official docs say that if a CLAUDE.md already exists, it does not overwrite it and suggests improvements instead.
Where does /init create the CLAUDE.md?
Project instructions use ./CLAUDE.md or ./.claude/CLAUDE.md in the project root. After it is generated, you can check the location with /memory or /context.
How do I turn on the interactive mode for /init?
Set the environment variable CLAUDE_CODE_NEW_INIT to 1 and run /init. It asks what to set up among CLAUDE.md, skills, and hooks, and shows a proposal you can review.
Checked against the official docs on 2026-10-30. Sources: Claude Code docs: How Claude remembers your project, Claude Code docs: Commands. How we write