Claude Init: What It Writes to CLAUDE.md, What to Replace, and What to Never Put In It

There is no claude init command in the Claude Code CLI. The thing people mean is /init, run inside an interactive Claude Code session, and it scans your repository and writes a root CLAUDE.md covering build, test and style conventions.

That file is worth more care than it usually gets, because Claude Code loads it at the start of every session. Below: what /init actually writes, where Claude Code looks for the file, what to replace before you commit the output, and what should never go in it.

Key Takeaways

• /init is a session command, not a shell subcommand. It scans the repo and generates a concise CLAUDE.md. If one already exists, it suggests improvements rather than overwriting your rules.
• Claude Code reads CLAUDE.md, not AGENTS.md. If your repo has an AGENTS.md, it stays inert unless /init folds it in.
• The root file loads at the start of every session. Files in subdirectories do not: they load on demand, when Claude reads files in that directory. That difference is how you keep a large repo's guidance affordable.
• The generated draft is a starting point, not a finished file. Replace the generic scaffolding with the commands that actually run in this repo, and delete any rule that no longer maps to a real reason it exists.
• Never put secrets in it, never name a client in it, and keep it short. Every line in the root file is context spent on every session.

What /init Writes to CLAUDE.md

The command scans project structure, files and configuration to infer the tech stack, then generates a root CLAUDE.md recording build, test and style guidelines. Typical output covers the framework and language, installation steps, and the common development tasks: running tests, linting, the git hooks and CI scripts.

It stays short by design. If a CLAUDE.md already exists, /init suggests additions rather than replacing what your team wrote.

Set CLAUDE_CODE_NEW_INIT=1 and it becomes interactive, asking which artifacts you want set up — CLAUDE.md, skills, hooks — rather than writing a file and stopping. That flow can also read an existing AGENTS.md and incorporate it. This matters because Claude Code does not read AGENTS.md on its own during normal work. If your repo has one, it is inert until something folds it into CLAUDE.md.

What /init cannot do is know your team's incidents, decisions or conventions. That part is written by hand and kept current by hand.

Where Claude Code Looks for the File

More than one CLAUDE.md can apply at once:

• An organization-managed policy file, if your company sets one.
• Your personal file in your home directory under .claude, which follows you across every repo.
• The project root file, committed and shared with the team. This is the one /init writes.
• A local file for personal settings you want but your teammates did not ask for.
• Parent directories and subdirectories of the project.

The difference that matters: the root file loads at the start of every session, while subdirectory files load only when Claude reads files there. So guidance for one service in a monorepo belongs beside that service, not in the root where every session pays for it. That is the same discipline that keeps a scheduled Claude Code run affordable.

What to Replace Before You Commit It

Treat the generated draft as a scaffold. Three edits earn their keep:

1. Replace generic setup documentation with this repo's specifics: the command that actually runs the tests, the linter that is authoritative, the architecture docs worth reading first, the deploy step people get wrong.
2. Replace "follow best practices" with the team's real conventions. The directory layout, the release process, the thing a new contributor always breaks.
3. Replace an empty testing section with the real expectation, stated plainly enough that a person or a coding agent can act on it. A repo that cannot state its test bar is not ready for agentic coding.

The Test for Whether a Rule Belongs

CLAUDE.md is not a prompt you write once. The rule we use: every line has to map to a failure that actually happened. Our own CLAUDE.md for this workspace runs 3,250 words across 325 lines, and carries 26 dated references to specific incidents. Not one of them is advice. Each is a thing that went wrong once, on a date, with the correction attached.

The reason to write it that way is that it makes the file falsifiable. A rule tied to an incident can be retired when the incident stops being possible. A rule that says "write clean code" can never be retired, so it stays forever, costing context on every session and teaching nothing. Rules with dates are the walls and rails that make an agent's output predictable; rules without them are decoration.

What to Never Put In CLAUDE.md

1. Secrets, API keys, credentials or tokens. The file is committed, and it is read as plain context by every session. There is no built-in protection for it, and a repo file that an agent reads automatically is already an attack surface.
2. Client or customer names. They have no place in a file the whole team and every session reads, and once committed they are in the history.
3. Internal metrics nobody approved for that visibility. The agent repeats them into pull requests and commit messages.
4. Filler. It costs context on every run and changes nothing the agent does.

Conclusion

/init gets you a first draft fast on an unfamiliar codebase. It is a starting point: edit it down to the project's real conventions and the workflow your team actually follows, push directory-specific guidance into the directory it belongs to, keep secrets out, and tie every rule to something that actually happened.

FAQs

1. Is there a claude init command?

No. It is /init, run inside an interactive Claude Code session. There is a claude plugin init command, but that scaffolds a plugin and has nothing to do with CLAUDE.md.

2. Does Claude Code read AGENTS.md?

No. Claude Code reads CLAUDE.md. The one exception is /init with CLAUDE_CODE_NEW_INIT=1, which can read an existing AGENTS.md and fold its contents into the CLAUDE.md it generates.

3. Does /init overwrite a CLAUDE.md that already exists?

No. It suggests improvements rather than replacing what is there, so running it on a repo that already has team conventions is safe.

4. Is CLAUDE.md re-read on every run?

The root file loads at the start of every session. Files in subdirectories are different: they load on demand, when Claude reads files in that subdirectory. So length in the root file costs you every time, and length in a subdirectory file costs you only when it is relevant.