Set Up Claude Code in 30 Minutes: A Quick Guide to CLAUDE.md

What is CLAUDE.md?

CLAUDE.md is a Markdown file that Claude Code automatically reads when a session starts. It can store project overviews, development rules, and personal preferences, and Claude Code follows these directives throughout subsequent interactions.

Loading hierarchy

CLAUDE.md files are not limited to the project root. Claude Code loads them in three scopes:

User‑level: applies to all projects on the machine.

Project‑level: a CLAUDE.md placed in the repository root affects that repository only.

Subdirectory‑level: a CLAUDE.md inside a specific folder is consulted only when Claude Code accesses that folder.

The loading order follows the nearest‑scope principle : rules that are closer to the current task and have a narrower scope take precedence. Within the same level, more specific statements outrank vague ones.

Conflict resolution

When multiple CLAUDE.md files conflict, the nearest‑scope principle is applied. For example, if a user‑level file enforces four‑space indentation but a project‑level file explicitly requires two‑space indentation, Claude Code will use two spaces for that project.

Quick start: generate a draft

The simplest way to create a CLAUDE.md is to run the following command in the project root:

$ claude
> /init

Claude Code analyses the tech stack, directory layout, and common commands, then produces a basic CLAUDE.md skeleton.

First‑time authoring

When writing the initial file, focus on information that directly influences Claude Code’s behavior:

Common commands such as build, test, lint, and local‑dev scripts.

Project‑specific constraints (e.g., non‑editable directories, soft‑delete tables, middleware‑required APIs).

Basic workflow rules (branch naming, pre‑commit checks, PR requirements).

Architecture context (responsibilities of directories in a monorepo, module boundaries).

If a piece of information does not help Claude Code understand the project faster or reduce common errors, it can be omitted.

When the file grows: splitting

As the number of rules increases, avoid a single massive file. Use @imports to reference more detailed files from the main CLAUDE.md.

Continuous evolution

CLAUDE.md is not a one‑time document; it evolves with the project. Add rules that arise from repeated collaboration issues, such as:

Prefer npm over pnpm for package management.

Correct placement of generated test files.

Explicit dependency rebuild steps after modifying database schema files.

At the end of each session, ask Claude Code to summarise useful points and incorporate them into CLAUDE.md (using the /reflection flow).

Insights‑based optimisation

Beyond manual review, the Insights report provides a longer‑term view of usage patterns, helping identify recurring problems and stable habits that merit formalisation in CLAUDE.md.

Best practices

Keep the file concise; unnecessary content consumes context tokens.

Write rules in an executable form (exact commands, directory restrictions, required checks).

Explain the intent behind rules so Claude Code can apply them flexibly.

Use progressive disclosure: keep the main file clean and move detailed sections to imported files.

Never store API keys, passwords, or tokens in CLAUDE.md because it is version‑controlled.

Comparison with other AI coding tools

Most AI coding assistants have a similar configuration file, but the design differs. Claude Code and Gemini CLI treat the file as persistent memory injected into the model. Codex, OpenCode, and Droid follow the same evolutionary path but keep the file name generic.

The emerging trend is a convergence of these specification systems, yet CLAUDE.md’s hierarchical loading and project‑context management give it a clear advantage.

Conclusion

The guide covered the concept of CLAUDE.md, its loading rules, quick generation, authoring strategy, evolution process, best‑practice recommendations, and its position relative to other tools. The most effective workflow starts from a usable draft and iteratively refines it through real collaboration, turning project experience into stable, actionable rules for the AI assistant.