Introduction to CLAUDE.md - Get Started with Project Configuration in 5 Minutes¶
Target Audience
- First-time Claude Code users
- Those wanting to introduce an AI assistant to their project
- Those who want to understand the basics of CLAUDE.md
Key Points¶
- What CLAUDE.md is
- How to create it with minimal configuration
- The full picture of memory hierarchy and file structure
- How to differentiate between Skills, Subagents, and CLAUDE.md
- Real examples where you can feel the effect
- Path to the next steps
Prerequisites¶
- Basic command-line operations
- Text editor usage experience
What is CLAUDE.md¶
CLAUDE.md is a configuration file that helps Claude Code understand your project. With this file, the AI can understand project-specific rules and workflows, providing more appropriate assistance.
Important: The file name must be
CLAUDE.md(all uppercase).
Auto-Generation with /init Command¶
Instead of creating CLAUDE.md manually, you can use Claude Code's /init command to automatically analyze your project and generate a CLAUDE.md file.
# Run within a Claude Code session
/init
/init analyzes your project's directory structure, programming languages, build systems, and more, then generates a CLAUDE.md with appropriate initial settings. Since it's faster than writing one manually, we recommend starting with /init and then customizing from there.
Comparing CLAUDE.md, Skills, and Subagents¶
Claude Code provides multiple mechanisms for customizing AI behavior. Understanding the role and differences of each is important.
| Feature | CLAUDE.md | Skills (.claude/skills/) | Subagents (.claude/agents/) |
|---|---|---|---|
| Purpose | Project rules & conventions | On-demand specialized knowledge | Task execution with independent context |
| Loading | Automatic at session start | Triggered by keywords | Explicitly invoked via Task tool |
| Scope | Entire session | Only when triggered | Only during task execution |
| Content | Build commands, conventions, constraints | Workflow procedures, domain expertise | Agent behavior definitions |
| Sharing | Shared via Git | Shared via Git | Shared via Git |
- CLAUDE.md: Rules and conventions that apply constantly across the entire project. Automatically loaded at session start
- Skills: Specialized knowledge needed for specific tasks. Loaded on-demand via trigger keywords (e.g., "create article", "build")
- Subagents: Agents that execute specific tasks in an independent context. Allows task delegation without consuming the main conversation context
Memory Hierarchy¶
Claude Code loads multiple configuration files hierarchically. Higher priority items take precedence and apply to broader scopes.
| Priority | File | Scope | Description |
|---|---|---|---|
| 1 (Highest) | Managed policy (system directories) | All org users | Organization policies set by administrators |
| 2 | ./CLAUDE.md or ./.claude/CLAUDE.md | Entire team | Project rules shared via Git |
| 3 | ./.claude/rules/*.md | Entire team | Path-specific rules (see below) |
| 4 | ~/.claude/CLAUDE.md | Just you (all projects) | Personal settings across all projects |
| 5 | ./CLAUDE.local.md | Just you (current project) | Local-only settings (not committed to Git) |
| 6 | ~/.claude/projects/<project>/memory/ | Just you (per project) | Auto-saved memory by Claude Code |
Tips for Choosing the Right Level¶
- Settings to share with the team -> Write in
CLAUDE.mdand manage with Git - Personal preferences or environment-specific settings -> Write in
CLAUDE.local.md(add to.gitignore) - Personal settings common to all projects -> Write in
~/.claude/CLAUDE.md
Auto Memory¶
Claude Code has an auto memory feature that automatically saves project patterns and debugging insights learned during sessions to ~/.claude/projects/<project>/memory/MEMORY.md. The first 200 lines of this file are automatically loaded at session start.
Auto memory accumulates information such as:
- Project-specific debugging patterns
- Frequently used commands and workflows
- Notes discovered in previous sessions
Splitting Files with @import¶
When your CLAUDE.md grows large, you can use the @import syntax to load other files.
# Project Configuration
@docs/coding-standards.md
@docs/api-guidelines.md
@.claude/rules/testing-rules.md
@import Specifications¶
- Both relative and absolute paths are supported
- Recursive imports supported up to a maximum depth of 5 hops (prevents circular references)
- An approval dialog is displayed on first import (security protection)
@pathinside code spans or code blocks is not evaluated (treated as plain text)
# The following will be imported
@configs/rules.md
# The following will NOT be imported (inside code block)
`@configs/rules.md`
Path-Specific Rules (.claude/rules/)¶
By placing Markdown files in the .claude/rules/ directory, you can define rules that apply only to specific file paths. Use the paths field in the YAML frontmatter to specify target paths in glob format.
---
paths:
- "src/api/**/*.ts"
---
# API Development Rules
- All endpoints must include input validation
- Responses must use a unified format
- Error handling must always be implemented
---
paths:
- "tests/**/*.test.ts"
---
# Testing Rules
- Tests must follow the Arrange-Act-Assert pattern
- Keep mocks to a minimum
Rule files without a paths field apply to all files.
Minimal Configuration in 5 Minutes¶
Step 1: Create the File (30 seconds)¶
Run the following in your project's root directory:
touch CLAUDE.md
Alternatively, run /init within a Claude Code session to auto-generate it.
Step 2: Add Minimal Content (2 minutes)¶
Write the following content in CLAUDE.md:
# Project Configuration
## Overview
This project is an application for [purpose].
## Tech Stack
- Language: [Python/JavaScript/etc.]
- Framework: [framework in use]
## Key Commands
- Start dev server: `npm run dev`
- Run tests: `npm test`
## Notes
- [Important project-specific notes]
Step 3: Real Example (2 minutes)¶
Concrete example for a React project:
# Project Configuration
## Overview
Frontend application for customer management system
## Tech Stack
- Language: TypeScript
- Framework: React 18
- Styling: Tailwind CSS
## Key Commands
- Start dev server: `npm run dev`
- Run tests: `npm test`
- Build: `npm run build`
## Notes
- API endpoints are managed via environment variables
- Components are placed under src/components
Step 4: Add to Git (30 seconds)¶
git add CLAUDE.md
git commit -m "Add CLAUDE.md configuration"
What to Include and What Not to Include in CLAUDE.md¶
What to Include¶
Write information in CLAUDE.md that cannot be inferred from code alone.
- Build/test commands: Project-specific commands like
npm run build,pytest - Code style rules: Naming conventions and formatting rules specific to this project
- Repo etiquette: PR conventions, branch naming rules, commit message formats
- Architectural decisions: Reasons for adopting specific patterns and design policies
- Common gotchas: Mistakes and pitfalls that newcomers often encounter
What Not to Include¶
The following information should not be included in CLAUDE.md.
- Standard conventions: General conventions Claude Code already knows, such as PEP 8 or ESLint default rules
- Detailed API documentation: Link to lengthy API references instead (to prevent CLAUDE.md from becoming bloated)
- Frequently changing information: Version numbers, release dates, and other information that quickly becomes outdated
Feel the Effect¶
After adding CLAUDE.md, try asking Claude Code questions like these:
Before (without CLAUDE.md)¶
Q: "Add a new component"
A: What kind of component should I add, and where?
After (with CLAUDE.md)¶
Q: "Add a new component"
A: I'll create a component using TypeScript and Tailwind CSS under src/components.
FAQ¶
Q: Does it work with lowercase file names?¶
A: Technically it works, but CLAUDE.md (uppercase) is recommended.
Q: Where should I place it?¶
A: Place it in your project's root directory. You can also place it at .claude/CLAUDE.md.
Q: Can I write it in Japanese?¶
A: Yes, you can write it in Japanese. Use your team's language.
Q: What's the difference between CLAUDE.md and CLAUDE.local.md?¶
A: CLAUDE.md is managed with Git and shared with the entire team. CLAUDE.local.md is for personal local settings and should not be committed to Git.
Q: Can I use the content generated by /init as-is?¶
A: The content generated by /init is a good starting point, but we recommend manually adding and adjusting project-specific conventions and workflows.
Next Steps¶
Once you've created a basic CLAUDE.md, learn more usage methods with these articles:
- CLAUDE.md Practical Guide - Detailed configuration by project type
- Troubleshooting - Common issues and solutions
- Best Practices - Advanced optimization techniques
Summary¶
CLAUDE.md is a simple and effective way to improve communication with your AI assistant. Start with the /init command or minimal configuration, and gradually add details as your project grows. By leveraging the memory hierarchy along with Skills and Subagents, you can achieve more advanced AI assistance.
This article is a beginner-friendly introduction. For more detailed configuration methods, please refer to the related articles above.