Home / Fundamentals and the agent loop
CLAUDE.md, the project's memory
CLAUDE.md is read automatically at the start of every session on the repository where it sits, and its rules are read as context, with no guarantee of strict enforcement.
CLAUDE.md is a text file placed at the root of a repository. Claude Code reads it automatically at the start of every session opened on that repository, without anyone needing to mention it. The file is delivered as a user message after the system prompt, not as part of the system prompt itself: Claude reads these rules and tries to follow them, with no strict guarantee of compliance. To block an action regardless of what Claude decides, a PreToolUse hook is needed rather than a line in CLAUDE.md.
What /init produces
The /init command runs a real analysis of the current repository, not the copying of a generic template. It scans the folder structure, the scripts declared in the configuration files and the conventions already in place, then proposes a first draft of CLAUDE.md from what it finds. This first draft still needs reviewing and trimming: a short file with absolute rules serves better than a long description of what the repository already contains anyway.
# Commands
npm test runs the test suite
npm run build produces the dist folder
# Conventions
React components live in src/components, one file per component
# Absolute rules
Never commit the dist folder
Always run npm run lint before a commitA wider variant behind an environment variable
As of 2026-09-02, activating the environment variable CLAUDE_CODE_NEW_INIT=1 before running /init triggers an interactive walkthrough wider than just CLAUDE.md: it also covers skills, hooks and personal memory files, and offers to import the configuration of another agent detected in the repository, for example an AGENTS.md file already present. Without this variable, /init keeps its usual behaviour and produces only a CLAUDE.md.
Why a short file wins
A CLAUDE.md loaded in full at every session weighs on the context available for the rest of the task. The rules that really matter are the ones that, if absent, would waste time or produce an error: the exact command to run the tests, where the components live, what must never be committed. Everything else, the project's history or the full list of dependencies, is better placed in a file read on demand than in a memory loaded on every turn of the agent loop, and a dedicated command also makes it possible to check what is actually loaded in the current session, see the essential slash commands.
Two behaviours of /init
| Scope covered by /init | What gets analysed | What gets proposed |
|---|---|---|
| Without CLAUDE_CODE_NEW_INIT=1 | The source code and the repository structure | A CLAUDE.md file |
| With CLAUDE_CODE_NEW_INIT=1 | The repository, plus the skills, hooks and personal memory already present | An interactive walkthrough that can import the configuration of another detected agent |
A developer runs /init in a repository where the environment variable CLAUDE_CODE_NEW_INIT=1 is active. Claude Code analyses the contents of the repository, engages an interactive walkthrough that asks questions about the skills and hooks present, then proposes a CLAUDE.md file to approve.
Write in one sentence what this situation establishes, and in one sentence what it does not establish.
What this establishes: This session establishes that the walkthrough triggered by /init with this variable active covered more than just the CLAUDE.md file, also asking about the repository's skills and hooks.
What this does not establish: It does not establish the final content of the CLAUDE.md file, since the developer has not yet approved the displayed proposal.
The three most common miscalibrations
- Too broad This session proves that /init now covers skills and hooks in every installation of Claude Code, even without the variable activated.
- Too narrow This session shows nothing more than the existence of the /init command, without learning anything about its real behaviour.
- Off target This session shows that the repository already contained several skills and hooks before /init was even run.
- CLAUDE.md is read automatically at the start of every session on the repository where it sits, with no need to flag it.
- The rules written in CLAUDE.md are read as context at the start of the session, with no guarantee of strict enforcement: what must be guaranteed goes through a hook instead.
- The /init command genuinely analyses the current repository to produce a first draft, it is not a generic template being copied.
- Activating CLAUDE_CODE_NEW_INIT=1 before /init triggers an interactive walkthrough that also covers skills, hooks and personal memory.
Run /init in an existing repository, review the proposed CLAUDE.md file, and delete any line that describes what you could find by reading the code rather than an absolute rule or an exact command.
These points depend on an interface or a rule that may have changed since this was written. Check them on your own screen before relying on them.
- The exact date the CLAUDE_CODE_NEW_INIT=1 variant was introduced could not be found, only its presence as of 2026-09-02 is confirmed.
Every datable claim in this lesson links here to the public text behind it. A source that does not open proves nothing.
- Claude Code, commands, the CLAUDE_CODE_NEW_INIT variable and the interactive walkthrough of /init consultée le 2026-09-02
- Claude Code, memory, CLAUDE.md read as context with no strict enforcement consultée le 2026-09-02