Blog
4 min read

Claude Code /init: What It Does and How to Get a Good CLAUDE.md From It

/init scans your project and writes a starter CLAUDE.md with build commands, test instructions and conventions. What it picks up, what it misses, the interactive CLAUDE_CODE_NEW_INIT flow, importing rules from Cursor or Copilot, and how to edit the result.

/init is usually the first command people run in a new Claude Code project, and it's worth understanding what it does — and doesn't — before you trust the file it writes.

What /init does

Run it inside a Claude Code session, from your project folder:

/init

Claude reads through your codebase — package.json, config files, the folder structure, your README, existing scripts — and writes a CLAUDE.md file at the project root. That file then loads at the start of every future session. (Claude Code memory explained)

A typical result includes:

  • How to install dependencies, run the dev server, build and test
  • The main folders and what's in them
  • Conventions it noticed (TypeScript strictness, test framework, lint setup)
  • Anything unusual about the project layout

If a CLAUDE.md already exists, /init doesn't overwrite it. It suggests improvements instead.

Bringing rules from other tools

If you've used another AI coding tool in this repo, /init picks up its instruction files and folds the relevant parts into the new CLAUDE.md:

  • Cursor rules in .cursor/rules/ or .cursorrules
  • GitHub Copilot's .github/copilot-instructions.md

If it finds OpenAI Codex or Gemini CLI configuration, it offers to carry that over with /import. (Cursor rules explained, AGENTS.md vs CLAUDE.md)

The interactive version

There's a longer, guided flow. Set an environment variable before running /init:

export CLAUDE_CODE_NEW_INIT=1
claude

Then /init asks which things you want set up — CLAUDE.md files, skills and hooks — explores the code with a subagent, asks you follow-up questions to fill gaps, and shows you a proposal to review before writing anything. It also reads a wider set of other tools' files (AGENTS.md, Windsurf, Cline and Devin rules), and can set up a personal CLAUDE.local.md that's added to .gitignore for you.

For a real project you'll keep working on, the interactive flow is worth the extra minute.

What /init gets wrong (or can't know)

/init can only write down what's visible in the code. It can't know:

  • Why things are the way they are ("we pin this library because v3 broke uploads")
  • What you don't want touched ("never edit the migrations folder by hand")
  • How the team actually works ("open a PR, don't push to main")
  • The traps ("the tests need a local Postgres on port 5433, not 5432")

These are exactly the things that make a CLAUDE.md valuable. The generated file is a starting point, not the finished article.

It also tends to over-describe. A long list of every folder and dependency is information Claude could find itself by reading the code — and it costs context on every single message. Anthropic's guidance is to keep CLAUDE.md under about 200 lines.

How to edit the result

After running /init, open the file (/memory lists it) and:

  1. Keep the commands — build, test, lint, dev server. These are gold.
  2. Cut long folder trees and dependency lists Claude could rediscover.
  3. Add the rules and traps only you know.
  4. Make rules checkable. "Run pnpm test before committing" beats "test your changes".
  5. Commit it so everyone on the project — and every future session — gets the same instructions.

A trimmed example:

# Commands
- pnpm install / pnpm dev / pnpm test / pnpm lint

# Rules
- Never edit src/db/migrations/ by hand — use pnpm db:generate
- All API input is validated with Zod in src/api/schemas/
- Ask before adding a new dependency

# Gotchas
- Tests need Postgres on port 5433 (docker compose up db)

Keeping it fresh

A CLAUDE.md goes stale as the project changes. Two habits help:

  • When Claude makes the same mistake twice, add a line.
  • Every so often run /doctor, which can suggest trims and flag instructions that reference files or commands that no longer exist.

The summary

  • /init writes a starter CLAUDE.md from what it can see in your code.
  • It won't overwrite an existing one — it suggests edits.
  • Set CLAUDE_CODE_NEW_INIT=1 for a guided version that also sets up skills and hooks.
  • Edit the result: keep commands, cut noise, add the things only you know.

EasySpawn gives each project a persistent server where Claude Code, your CLAUDE.md and your running app all live together — run /init once and it's there every time you come back. See how it works or join the waitlist.

Related: How to Write a CLAUDE.md That Actually Helps · Claude Code Tutorial for Beginners · Claude Code Slash Commands · Claude Code Memory Explained

Keep reading