Most Claude Code users are aware of the
.claude/
folder but have never really opened it. AI engineer Akshay recently organized a comprehensive guide, explaining the purpose of each file in this folder and how to set it up so that Claude works exactly the way you want.
Two folders, not one
First, clarify a common misconception:
The .claude/
folder has two parts, not just one.
Project-level (.claude/ in your project): Stores team-shared settings, committed to Git, ensuring everyone follows the same rules and commands.
Global-level (~/.claude/): Personal preferences and cross-project settings that only affect your own machine.
CLAUDE.md: The most important file
Every time you start a Claude Code session, Claude first reads
CLAUDE.md
and loads it into the system prompt, continuously following its instructions throughout the conversation.
What should be included:
Build, test, lint commands (e.g., npm run test)
Important architectural decisions
Obscure notes (e.g., “TypeScript strict mode enabled, unused variables will error out”)
Naming conventions, error handling styles
What should NOT be included: rules suitable for linter configurations, full documentation, lengthy theoretical explanations.
Akshay recommends keeping CLAUDE.md within 200 lines—beyond that, Claude’s adherence rate actually drops because of excessive context consumption.
rules/ folder: Modular commands, suitable for team expansion
As CLAUDE.md becomes more bloated,
.claude/rules/
is the solution. Each Markdown file represents a focus point, such as code-style.md, testing.md, api-conventions.md. Claude will automatically read all files.
Even more powerful is the “path scope rule”: by adding YAML front matter to rule files, you can make rules only load when Claude processes files in specific paths, preventing irrelevant rules from occupying context.
commands/ folder: Custom slash commands
Each Markdown file placed in
.claude/commands/
becomes a slash command. review.md corresponds to /project:review, fix-issue.md to /project:fix-issue.
The most practical feature is using
!
syntax inside command files to execute shell commands and embed their output—for example, automatically fetching git diff and injecting it into prompts, allowing Claude to “see” your code changes. Personal commands in ~/.claude/commands/ are available across all projects.
skills/ and agents/: Proactive triggers vs. designated sub-agents
The core difference between Skills and agents lies in how they are triggered:
Skills: Claude automatically decides whether to call them based on conversation content, no manual commands needed. Each skill has its own directory with SKILL.md and optional support files.
Agents: Define specialized sub-agent personas with independent system prompts, tool permissions, and model settings. For complex tasks, Claude spawns an isolated context window for the agent to execute, preventing the main session from being overwhelmed with tokens.
In agents, the
tools
field limits the scope of the sub-agent’s actions—security audit agents only need read permissions and should not have write access. The model field allows you to choose a lighter model for focused tasks, saving costs.
settings.json: Whitelist and blacklist permissions
.claude/settings.json
controls what actions Claude is allowed or forbidden to perform:
allow list: actions that can be executed directly without confirmation (e.g., npm run *, git *)
deny list: actions that are completely blocked (e.g., rm -rf *, reading .env)
Operations not on either list will prompt Claude for confirmation.
Personal settings can be placed in
.claude/settings.local.json
, which is automatically ignored by git and not committed to the repository.
Where to start?
Akshay’s recommended practical starting steps: run
/init
to generate the initial CLAUDE.md, add basic permissions in settings.json, then create one or two most-used custom commands—gradually adding more as you get familiar.
The key insight is:
The .claude/
folder is your protocol for telling Claude “who you are, what the project is, and what rules to follow.” The clearer the setup, the less time spent correcting Claude.
This article explains in detail: Understanding the .claude/ folder: Claude Code’s control hub, with full analysis of CLAUDE.md, commands, skills, and permissions, originally published on Chain News ABMedia.
