What Claude Code's /init puts in CLAUDE.md, and what to change afterwards

The first command most people run in a new repository is /init. Claude inspects the codebase and writes a CLAUDE.md for you, but if you leave the output untouched it tends to be long, and long files make Claude follow your instructions less reliably.

In short: treat the output of /init as a draft. Cut what Claude can learn by reading the code, add what it cannot guess, then confirm the file loads with /context.

What /init does

The official command reference describes /init as "Initialize project with a CLAUDE.md guide". Claude analyzes your codebase and creates a file with the build commands, test instructions, and project conventions it discovers.

Item	Behavior
Output	CLAUDE.md at the project root
Contents	Build commands, test instructions, conventions found in the code
Existing CLAUDE.md	Not overwritten. /init suggests improvements instead
Other tools' rules	Reads .cursor/rules/, .cursorrules, and .github/copilot-instructions.md and incorporates the relevant parts
Codex / Gemini CLI config	If found, offers to carry it over with /import

The interactive /init

Set CLAUDE_CODE_NEW_INIT=1 to switch /init to an interactive, multi-phase flow. It asks which artifacts to set up (CLAUDE.md files, skills, and hooks), explores the codebase with a subagent, fills gaps with follow-up questions, and shows a reviewable proposal before writing anything. In this mode it also reads AGENTS.md, .devin/rules/, .windsurf/rules/, and .clinerules.

CLAUDE_CODE_NEW_INIT=1 claude

Then run /init in the session. Choosing the personal option also creates CLAUDE.local.md and adds it to .gitignore.

What to cut from the generated file

The official best practices suggest asking, for every line, "Would removing this cause Claude to make mistakes?" and cutting it if not. The target is under 200 lines per file. Because /init writes from what it read in the code, it tends to include content Claude can derive on its own:

• Directory listings and file-by-file descriptions
• Dependency lists
• Standard language conventions and self-evident practices such as "write clean code"
• Long architecture explanations or tutorials

Claude can read the code whenever it needs this, so keeping it in CLAUDE.md only spends context every session.

What to add

Add the things /init cannot discover: what Claude cannot guess. The official "include" column summarizes as follows.

Include	Example
Commands Claude can't guess	A package-specific test command such as pnpm --filter api test
Style rules that differ from defaults	"Use ES modules, not CommonJS"
Repository etiquette	Branch naming, PR conventions
Project-specific architectural decisions	"API handlers live in src/api/handlers/"
Environment quirks	Required env vars, a local database that must be running
Common gotchas	"Never edit existing migrations"

Write instructions concrete enough to verify: "Use 2-space indentation" rather than "Format code properly", and "Run npm test before committing" rather than "Test your changes".

# Commands
- Tests: `pnpm -r test` (single package: `pnpm --filter <pkg> test`)
- Typecheck: `pnpm typecheck`. Always run it after a series of changes

# Conventions
- Use ES modules (import/export), not require
- API handlers live in `src/api/handlers/`

# Etiquette
- Branch names start with `feat/` or `fix/`
- Never edit existing files under `prisma/migrations/`

Procedures you only need sometimes, such as a release checklist, belong in a skill rather than CLAUDE.md, so they load on demand. Rules that only matter for one directory belong in a subdirectory CLAUDE.md or a path-scoped rule under .claude/rules/.

Confirm the file loads

After editing, run /context in a session and check that CLAUDE.md appears under Memory files. /memory is the command for listing and editing CLAUDE.md files and toggling auto memory; the official way to confirm what actually loaded is /context.

You can pull other files in with @path imports, but imported files also load at launch, so this organizes content without saving context.

Summary

• /init analyzes the codebase and writes a CLAUDE.md with build commands, test instructions, and conventions. An existing file is not overwritten; /init suggests improvements instead
• CLAUDE_CODE_NEW_INIT=1 turns it into an interactive flow that also sets up skills and hooks
• After generation, cut content Claude can derive from the code, such as directory layouts and dependency lists. Aim for under 200 lines
• Add commands Claude can't guess, non-default conventions, environment quirks, and gotchas, phrased concretely
• Verify with /context under Memory files, and use /doctor to trim a file that has grown