Claude Code `~/.claude/CLAUDE.md` Complete Guide
- AI
- AIAgent
- AI Utilization
- ClaudeCode
- Claude
Introduction
This document is a guide that summarizes how beginners can understand the role of ~/.claude/CLAUDE.md and safely operate it with general and extensible settings.
The ~/.claude/CLAUDE.md discussed here is apersonal common instruction file applicable to all projects using Claude Code, not just specific ones.
The most important concept is as follows.
~/.claude/CLAUDE.md contains only personal common settings that Claude Code cannot determine from code or repositories.
Official Documentation:
1. What is CLAUDE.md
CLAUDE.md is a Markdown file used to provide continuous instructions to Claude Code.
You don't need to input the same instructions every time in regular chat; instead, Claude Code will load the file and use the written guidelines as a reference during work.
For example, you can describe personal preferences such as:
- I would like you to answer in Japanese by default.
- Please keep commands and identifiers in English.
- Please answer simple questions briefly and elaborate on complex investigations.
- I would like you to check existing code or documents before answering questions.
- Please do not report tests that have not been executed as successful.
Meaning of ~/.claude/CLAUDE.md
The tilde at the beginning of the path represents the current user's home directory.
The common save location on Windows is as follows.
Example:
On macOS or Linux, it is typically located in the following path.
2. Difference between global files and project files
Claude Code instructions are organized based on their purpose.
| Configuration Location | Main Purpose |
|---|---|
| ~/.claude/CLAUDE.md | Personal settings applicable to all projects |
| <project>/CLAUDE.md | Commands, conventions, and notes for a specific project |
| <project>/CLAUDE.local.md | Personal settings used only within a specific project |
| <project>/.claude/rules/*.md | Rules limited to specific paths or files |
| skills/<name>/SKILL.md | Reusable multi-step work procedures |
| agents/<name>.md | Role of specialized sub-agents |
| settings.json | Settings such as model, permissions, sandbox, and hooks |
Examples of judgment
Content suitable for global files
Content suitable for project-specific files
Specifications such as pytest or pnpm are not necessarily common to all projects. Therefore, they are typically written in the project's CLAUDE.md.
3. Why it is necessary to keep it concise
~/.claude/CLAUDE.md is loaded in many sessions.
If the file is too long, the following problems are more likely to occur.
- The instructions unrelated to the current task may be read.
- Important instructions may be buried in a large amount of text.
- Instructions may overlap or conflict with each other.
- Old rules may continue to remain.
- Claude Code may become overly cautious and stop even for simple tasks.
- Project-specific conventions may be incorrectly applied to other projects.
Therefore, it is important not to increase the number of lines, but to retain only the necessary information.
It is also not good to make the instructions too short. If you remove necessary personal settings, you will have to re-enter the instructions every time.
The goal is not the shortest, but sufficient and necessary.
4. Final Recommended Template
It is recommended to save the following in ~/.claude/CLAUDE.md.
The reason for writing the template in English is that it makes it easier for Claude Code to consistently interpret technical instructions, and it also maintains alignment with English commands, setting names, and API names.
It is not mandatory. The template can also function in Japanese. However, using concise and unambiguous English in the configuration file and specifying Japanese as the response language from Claude Code makes it easier to handle.
5. Template Details
5.1 Personal Defaults
This header indicates that the file contains personal defaults rather than organizational or project rules.
This paragraph has two purposes.
- Indicates that this file is applicable to all projects
- Prevents adding project-specific information to global files
It functions as a boundary for extending the template in the future.
5.2 Communication
Respond in Japanese by default
Usually respond in Japanese, but use English if the user specifies it.
Preserve technical elements in their original language
Explanation text in Japanese will not be translated.
Translating commands or setting names would make them unusable as-is.
Adjust explanation length to match the task.
This prevents providing lengthy explanations for simple questions or summarizing complex troubleshooting in a single sentence.
Example:
- Command meaning: Answer concisely.
- Small setting change: Briefly report the change and verification result.
- Architecture design: Explain reasons and trade-offs in detail.
- Troubleshooting: Detail the basis, hypothesis, and verification method.
Prioritize specific and actionable information.
It will not end with abstract advice like "test appropriately," but instead provide specific commands, target files, and verification methods within the scope of understanding.
Explicitly state uncertain content.
This is an instruction to distinguish and report the following states.
- Facts confirmed directly from code.
- Reasonable speculation.
- Results confirmed through execution.
- Unverified assumptions.
- Content that could not be verified due to insufficient environment.
5.3 Collaboration
Check existing information before asking questions.
If the answer exists in conversation, code, settings, tests, documentation, or error logs, do not ask the user immediately; first check the existing information.
Proceed with low-risk tasks autonomously.
Work is performed without multiple confirmations if the following conditions are met.
- The request content is clear.
- The user is requesting execution.
- The impact is minimal.
- It can be easily reverted.
Examples:
- Modification of the specified document.
- Small-scale changes to local code.
- Adding unit tests.
- Execution of lint or format.
- Creation of a new output file.
Ask only when unresolved ambiguity could materially change the outcome.
Do not stop work for trivial ambiguities; ask only when the ambiguity could significantly affect the result.
Examples where questions are more likely needed:
- Implementation varies depending on the target platform.
- Unclear whether backward compatibility is required.
- Unclear whether destructive changes are allowed.
- The outcome could change significantly based on multiple interpretations of the specification.
- Involves public, billing, or permission changes.
Preserve the user's existing changes and avoid work outside the requested scope.
Prevents the following issues:
- Overwriting unrelated uncommitted changes.
- Unrequested refactoring.
- Unrelated format changes.
- Unnecessary dependency updates.
- Accidental fixes for unrelated features.
