1. What is CLAUDE.md?

1. Core Positioning

We usually write README.md for people to read project descriptions, while CLAUDE.md is a project rulebook specifically written for the Claude Code AI. As long as the file is placed in the project root directory, every time a Claude Code session is opened, the AI will automatically read and fully comply with all constraints inside, perfectly solving two pain points:

1. No need to repeatedly explain the project's tech stack, coding standards, and directory rules in every conversation;
2. Prevents the AI from writing messy code, modifying files arbitrarily, or outputting logic that doesn't match the project style.

A simple analogy:

• README.md = New developer handbook (for humans)
• CLAUDE.md = AI onboarding constraint document (automatically loaded by Claude)

2. Multi-level Loading Mechanism (Key Knowledge Point)

CLAUDE.md supports four scopes, with higher priority for closer directories, and rules stack cumulatively:

File Location	Scope	Purpose
~/.claude/CLAUDE.md	All projects globally	Personal universal coding preferences (indentation, comment style)
Project root ./CLAUDE.md	Current entire repository	Team-shared, committed to Git, unifies project standards
Subdirectory xxx/CLAUDE.md	Only that folder	Module-specific rules (e.g., frontend/backend distinction standards)
.claude/CLAUDE.md	Project private config	Not committed to Git, stores local private instructions

Practical tip: The root directory's CLAUDE.md can be committed to the code repository, automatically unifying coding standards for everyone on the team using Claude Code.

3. What Should a Standard File Contain?

A high-quality CLAUDE.md contains 5 major modules, rejecting empty rhetoric (like "write good code"), and writing only actionable, verifiable rules code.claude.com:

1. Project Basic Info: Project purpose, tech stack, business goals
2. Directory Structure Conventions: Content stored in each folder, files prohibited from modification
3. Mandatory Coding Standards: Indentation, naming, comments, syntax, code length limits
4. Engineering Commands: Run, test, build, debug commands (automatically used by AI when executing tools)
5. AI Behavior Constraints: File read/write restrictions, output format, prohibited operations, communication rules

2. Pre-operation: One-click Generation of Basic CLAUDE.md

As demonstrated in the screenshot, enter the command in the VS Code Claude Code panel:

/init

The AI will automatically scan the current project structure and generate a basic version of CLAUDE.md. We then manually refine the project-specific rules, no need to write from scratch.

3. Practical Demo: Complete add-demo Addition Tool Project (Corresponding to Screenshot Case)

Scenario Description

In the screenshot, we created the add-demo simple Node.js project. Requirement: Write an addition utility function with accompanying test calls, constraining AI behavior throughout via CLAUDE.md, eliminating the need to repeat rules.

Step 1: Execute /init to Generate Initial CLAUDE.md

Open the VS Code Claude Code sidebar, enter /init, the AI automatically identifies the project and generates a basic configuration file. At this point, the original file lacks precise constraints, so we rewrite it to the standard specification version.

Step 2: Complete CLAUDE.md Template (Can be directly copied for use)

# CLAUDE.md - add-demo Project AI Constraint Document
## 1. Project Basic Info
- Project Name: add-demo
- Tech Stack: Native Node.js, no framework, no TS, pure JavaScript
- Project Goal: Encapsulate a universal addition utility function, supporting integer and floating-point operations, with console test cases
- Entry File: index.js (the only code file, all logic written uniformly here)

## 2. Directory Structure Constraints
The project has only 2 core files, prohibiting the creation of other js files:
- index.js: Business code, utility functions, test examples
- CLAUDE.md: AI rule configuration file
Prohibit automatic creation of folders like src, test, dist, maintaining a minimalist structure.

## 3. JavaScript Mandatory Coding Standards
1. Indentation: 2 spaces, prohibit Tab
2. Functions: Use function declarations, do not use arrow function shorthand
3. Comments: Single-line comment above function explaining its purpose, add comments to distinguish call examples
4. Output: Test code uniformly uses console.log, print format `functionName(parameter) = calculation result`
5. Variable Naming: lowerCamelCase, simple and understandable, no complex abbreviations
6. Prohibit: Adding redundant dependencies, introducing third-party libraries, using ES Module import/export

## 4. Run & Debug Commands
Fixed command to run the project, execute this command to verify after modifying code:
```bash
node index.js

5. AI Operation Behavior Constraints

1. Confirm the index.js file before writing code, append all new logic to the end of the file, do not overwrite existing valid code.
2. Inform the number of lines and content before modifying a file, prohibit silently overwriting all code.
3. Accompany code output with a brief explanation, do not output irrelevant redundant explanations.
4. Prohibit modifying the CLAUDE.md file itself, only allow humans to edit this rule document.
5. Automatically output the run command after task completion, prompting the user to verify the result.

### Step 3: Initiate Request, AI Automatically Follows Rules to Generate Code
Enter natural language request:
> Write an addition utility function that supports adding two numbers, with two sets of test calls: integer addition, positive and negative floating-point addition

At this point, Claude Code reads the `CLAUDE.md` constraints and automatically generates `index.js` that conforms to the specification, identical to the code in the screenshot:
```javascript
// Addition utility: returns the sum of two numbers
function add(a, b) {
  return a + b;
}

// Call examples
console.log('add(1, 2) =', add(1, 2));
console.log('add(-5, 3.7) =', add(-5, 3.7));

Step 4: Run Verification

AI automatically outputs the run command, execute in terminal:

node index.js

Output result:

add(1, 2) = 3
add(-5, 3.7) = -1.3

Practical Advantage Comparison (Difference with and without CLAUDE.md)

Without CLAUDE.md	With CLAUDE.md Configured
Must explain in every conversation: use native JS, don't create new folders, use function declarations	AI automatically reads rules, no need to repeat descriptions
AI might generate arrow functions, create test folders, introduce modules	Strictly adheres to indentation, naming, file structure constraints
Generated code has no fixed output format, messy test prints	Unified standard log output, conforms to project conventions
Often silently overwrites all code, losing original logic	Prompts change scope before modification, appends code instead of overwriting

4. Pitfall Avoidance Tips for Writing CLAUDE.md

1. Rules must be concrete, reject vague descriptions Wrong: Write code more standardized, clear comments; Correct: JS uses 2-space indentation, add a single-line functional comment at the top of each function.
2. Control length, only write what the AI must know Don't stuff the entire business document in, only keep coding, file, command, and behavior constraints, too long dilutes the model's attention.
3. Distinguish project rules from personal preferences Project root directory file writes team common standards (can be committed to Git); global ~/.claude/CLAUDE.md stores personal habits.
4. Iterate and update promptly When the project adds new tech stacks or directory changes, synchronously modify CLAUDE.md to prevent the AI from generating wrong code based on old rules.
5. Use the /init command for quick initialization For new projects, directly execute /init to generate a basic template, then supplement custom constraints; writing from scratch is extremely inefficient.

5. Summary

CLAUDE.md is the most cost-effective efficiency tool for Claude Code, essentially providing the AI with persistent, session-shared project context. Previously, you had to repeatedly explain project rules every time you communicated with the AI. After configuring a standardized CLAUDE.md, the AI will automatically adapt to your project architecture, code style, and file constraints, greatly reducing the cost of manually correcting code.

The Node.js minimalist addition project accompanying this article can be directly replicated. You just need to copy the CLAUDE.md template from the article to your project root directory to immediately experience the smooth AI coding workflow brought by standardized constraints.