Initializing Claude Code — The /init Command and CLAUDE.md

When you first open Claude Code inside a project, it has no idea what your codebase does, what technologies you use, or how your team prefers to write code. It starts with a blank slate — a fresh context window with no memory of your project. That is where the /init command comes in.

The /init command tells Claude to analyze your codebase and generate a CLAUDE.md file — a Markdown document that acts as persistent instructions for every future session. Think of it as writing a briefing document for a new team member, except in this case the team member is an AI agent that reads the briefing automatically every time it starts.

This article walks through the full lifecycle of initializing a project with Claude Code: running /init, understanding how Claude explores and analyzes the codebase, reviewing the generated CLAUDE.md file, and understanding the permission system that keeps you in control. By the end, you will know how to bootstrap any project for effective agentic coding.

Running the /init Command

Starting Claude Code in Your Project

Before you can initialize, you need Claude Code running inside your project directory. Open your terminal, navigate to the project root, and start Claude Code:

You can also start Claude Code from within VS Code or JetBrains IDEs, or from the Claude desktop app. The important thing is that Claude Code's working directory is set to your project root.

Once Claude Code is running, you will see the interactive prompt. This is where you type commands and have conversations with Claude. To initialize the project, simply type:

What Happens When You Run /init

When you type /init and press Enter, Claude begins a multi-step exploration of your project. It does not just look at one file — it systematically reads your codebase to build an understanding of the entire project. Here is what happens behind the scenes:

1. Directory structure scan — Claude examines the folder layout to understand how the project is organized (source folders, test folders, configuration files, build output directories).
2. Technology detection — Claude reads configuration and manifest files to identify the technologies in use. For a C# project, it reads .csproj files, global.json, Directory.Build.props, and NuGet.config. For other stacks, it reads package.json, Cargo.toml, go.mod, requirements.txt, and similar files.
3. Key file analysis — Claude reads entry points, configuration files, README files, and other important files to understand what the project does and how it is structured.
4. Build and test command discovery — Claude identifies how to build, run, and test the project by examining build scripts, CI/CD configurations, Makefiles, and package manager files.
5. Convention detection — Claude looks at existing code to infer conventions: naming patterns, code style, architectural patterns, and any documented standards.

This exploration phase involves Claude using its built-in tools — reading files, listing directories, and sometimes running shell commands — to gather information. You will see Claude working through these steps in real time, and each action requires your approval depending on your permission mode.

The Permission System During Initialization

Every time Claude wants to read a file, list a directory, or run a shell command during initialization, it goes through the permission system. By default, Claude Code operates in default mode, which means it asks for your approval before performing most actions.

When Claude requests permission to perform an action, you see a prompt describing exactly what it wants to do. You have several options:

1. Allow once — approve this single action
2. Allow for session — approve this type of action for the rest of the current session
3. Deny — reject the action

This is a core safety feature: you are always in control. Claude never silently reads, modifies, or executes anything without your explicit consent (unless you opt into a more permissive mode). For initialization, Claude primarily needs read access to your project files, so you will mostly be approving file reads and directory listings.

Permission Modes — Choosing Your Level of Oversight

Claude Code offers several permission modes that control how often you are prompted. You can cycle between modes by pressing Shift+Tab in the CLI, or select them in the IDE integrations:

For your first initialization, default mode is recommended. You will see exactly what Claude is doing and learn how it explores a project. Once you are comfortable, you can switch to acceptEdits mode to speed up future sessions.

You can set a mode at startup:

Or set a persistent default in your settings:

The Generated CLAUDE.md File

What Is CLAUDE.md?

CLAUDE.md is a Markdown file that Claude Code reads at the start of every session. It is loaded directly into the context window as part of the system prompt. Every instruction, convention, and command listed in this file is available to Claude from the very first message.

Think of CLAUDE.md as your project's "user manual for the AI." Just as you might onboard a new developer by giving them a document describing the project structure, coding standards, build process, and important conventions, CLAUDE.md serves the same purpose for Claude Code.

What /init Generates

After analyzing your project, Claude generates a CLAUDE.md file at the root of your project. The generated content typically includes:

1. Project description — a brief summary of what the project does
2. Technology stack — languages, frameworks, and major dependencies
3. Build commands — how to build, run, and test the project
4. Project structure — key directories and their purposes
5. Coding conventions — naming standards, architectural patterns, file organization rules
6. Important notes — anything unusual or critical about the project

Here is an example of what a generated CLAUDE.md might look like for a C# ASP.NET Core Web API project:

Reviewing and Editing the Output

The /init command does not blindly overwrite your file. If a CLAUDE.md already exists, Claude reads the existing content and suggests improvements rather than replacing it. This is safe to run repeatedly.

After Claude generates the file, you should review it carefully. Claude does an excellent job of detecting project structure and conventions, but it may miss things or include details that are not quite right. Open the generated CLAUDE.md in your editor and:

1. Verify that the build and test commands are correct
2. Add any team-specific conventions that Claude could not infer from the code
3. Remove anything that is incorrect or irrelevant
4. Add important notes about deployment, environment variables, or external dependencies

Anthropic recommends keeping your CLAUDE.md under 200 lines. Since this file is loaded into the context window at every session start, a very long CLAUDE.md wastes valuable context space. Be concise and prioritize the most important instructions.

CLAUDE.md Scopes and Organization

Where CLAUDE.md Files Can Live

CLAUDE.md is not limited to a single file at the project root. Claude Code supports a hierarchy of instruction files at different scopes:

All of these files are loaded into the context at session start. Project-level files are shared with your team via version control. User-level files apply only to you, across all projects. The .local.md variant lets you have personal project settings without affecting your teammates.

Organizing with @imports and Rules

As your instructions grow, you can split them into multiple files and import them. CLAUDE.md supports an @import syntax:

Each @path line tells Claude to read and include the contents of that file as if they were written inline. This keeps your root CLAUDE.md clean and lets you organize detailed instructions into separate documents.

For even more granular organization, you can use the .claude/rules/ directory. Each file in this directory is a separate rule that gets loaded into the context:

Rule files can include an optional paths frontmatter to scope them to specific file patterns:

When Claude is working on a file that matches the pattern, the rule is automatically included in the context. This prevents unrelated instructions from consuming context space.

Writing Effective CLAUDE.md Instructions

Be Specific and Actionable

The most common mistake is writing vague instructions. Claude performs better when instructions are concrete and testable. Compare these two approaches:

Use Clear Formatting

CLAUDE.md is Markdown, so use its formatting features to make instructions scannable. Anthropic recommends:

1. Use Markdown headers (#, ##, ###) to organize sections
2. Use bullet points for lists of rules or conventions
3. Use backtick code blocks for commands, paths, and code references
4. Keep the total length under 200 lines

Practical Example: A Complete CLAUDE.md for an ASP.NET Core Project

Here is a realistic, complete CLAUDE.md for an ASP.NET Core project that demonstrates all the key sections:

Auto Memory — The Complementary System

What Is Auto Memory?

In addition to the manually maintained CLAUDE.md file, Claude Code has an auto memory system. While you write CLAUDE.md, Claude writes auto memory notes on its own over the course of a session.

When Claude discovers something important — like a user preference, a correction, or a project-specific finding — it can save a note to its memory. These notes are stored at:

The first 200 lines of the MEMORY.md file in this directory are automatically loaded at the start of each session, just like CLAUDE.md. You can browse and manage memory entries using the /memory command.

CLAUDE.md vs. Auto Memory

Both systems serve the purpose of giving Claude persistent context, but they work differently:

The best approach is to use both together. Use CLAUDE.md for the team-level instructions that everyone should follow, and let auto memory capture the personal discoveries and preferences that are unique to your workflow.

Safe Agentic Coding — The Human in the Loop

Why Permissions Matter

Claude Code is an agentic system — it does not just generate text, it takes actions. It can read files, write files, run shell commands, and interact with external services. This power is what makes it useful, but it is also why the permission system exists.

Every action Claude takes during initialization (and during regular coding sessions) goes through the permission layer. This ensures that:

1. You see exactly what Claude is doing at each step
2. No file is modified without your approval
3. No shell command is executed without your knowledge
4. You can deny any action that looks suspicious or incorrect

Protected Paths

Regardless of which permission mode you use, Claude Code has a set of protected paths that are never auto-approved. These include:

1. .git/ — repository state
2. .vscode/, .idea/ — IDE configuration
3. .claude/ — Claude Code configuration (except .claude/commands, .claude/agents, and .claude/skills)
4. Shell configuration files — .bashrc, .zshrc, .profile
5. .gitconfig, .gitmodules

This safeguard prevents accidental corruption of your repository state and Claude's own configuration, even in the most permissive modes.

Best Practices for Safe Initialization

Here are concrete recommendations for safely initializing a project with Claude Code:

1. Start in default mode — watch what Claude does during your first /init to understand the exploration process
2. Review the generated CLAUDE.md — do not blindly trust the output; verify commands and conventions
3. Commit the CLAUDE.md to version control — this shares the instructions with your entire team
4. Keep it under 200 lines — use @imports for detailed guidelines
5. Run /init again periodically — as your project evolves, re-running /init can surface new conventions or updated commands

Hands-On: Initializing an ASP.NET Core Project

Step 1: Navigate to Your Project and Start Claude Code

Open your terminal and navigate to an existing ASP.NET Core project:

Step 2: Run the /init Command

At the Claude Code prompt, type:

Watch as Claude explores the project. It will read .csproj files, examine the directory structure, check Program.cs, look at existing tests, and analyze the project configuration. Approve each action as prompted.

Step 3: Review the Output

Once Claude finishes, open the generated CLAUDE.md file in your editor. Check the following:

1. Are the build and test commands correct?
2. Did Claude detect your project architecture accurately?
3. Are the coding conventions it inferred actually what your team uses?

Step 4: Customize and Commit

Edit the CLAUDE.md to add anything Claude missed, fix any inaccuracies, and remove unnecessary content. Then commit it:

From now on, every Claude Code session in this project will start with these instructions loaded into the context. Your team members will benefit from the same instructions when they use Claude Code.

Step 5: Verify It Works

Close Claude Code and start a new session. Ask Claude to perform a task that relies on the instructions in your CLAUDE.md:

Claude should follow the conventions you defined — using minimal APIs, async/await, the repository pattern, and the correct project structure — because those instructions are now part of its context from the very start.

Summary

The /init command is the starting point for effective agentic coding with Claude Code. It bootstraps your project by generating a CLAUDE.md file that captures your project's structure, commands, and conventions. Combined with the permission system that keeps you in control, and the auto memory system that learns from your sessions, Claude Code provides a structured, safe, and productive environment for AI-assisted development.

Remember: the CLAUDE.md file is not a one-time setup. It is a living document that evolves with your project. Review it regularly, keep it concise, and commit it to version control so your entire team benefits from consistent AI-assisted coding.