# Anatomy of the .claude/ Folder

> The .claude/ folder controls Claude Code behavior through instructions, permissions, commands, skills, and subagents. Keep CLAUDE.md under 200 lines.

Published: 2026-03-28
URL: https://daniliants.com/insights/anatomy-of-the-claude-folder/
Tags: claude-code, developer-tools, ai-configuration, dotfiles, prompt-engineering, workflow-automation, cli-tools

---

## Summary

The `.claude/` folder is the control center for Claude Code's behavior in a project, containing instructions (CLAUDE.md), permission rules (settings.json), custom slash commands, auto-invoked skills, and subagent personas. Understanding and configuring each component properly - especially keeping CLAUDE.md under 200 lines - dramatically reduces time spent correcting Claude and improves output quality.

## Key Insight

- **Two-tier config system:** Project-level `.claude/` (committed to git, shared with team) and global `~/.claude/` (personal preferences, session history, auto-memory). Both are read and combined at session start.
- **CLAUDE.md is highest-leverage:** Keep it under 200 lines - instruction adherence drops with longer files. Focus on build/test/lint commands, architectural decisions, non-obvious gotchas, and import/naming conventions. Skip anything that belongs in linter configs.
- **Path-scoped rules:** Files in `.claude/rules/` with YAML frontmatter `paths:` fields only activate when Claude works on matching files. This prevents context pollution - API rules don't load when editing React components.
- **Commands vs skills distinction is now merged:** As of recent updates, commands (`.claude/commands/`) and skills (`.claude/skills/`) are unified. Skills add optional features: supporting file directories, frontmatter for auto-invocation, and Claude can load them automatically when context matches.
- **Agents for isolated complex tasks:** `.claude/agents/` defines subagent personas with restricted tool access and model selection. A code reviewer agent spawns in its own context window with only Read/Grep/Glob, keeping the main session clean. Using cheaper models (e.g., Haiku) for focused read-only tasks saves cost.
- **Permission layering:** `settings.json` has allow (runs without confirmation), deny (blocked entirely), and implicit middle ground (asks before proceeding). Pair with `.local` variants for personal overrides that stay out of version control.
- **Shell command injection in commands:** The `!` backtick syntax in command files runs shell commands and embeds output into the prompt before Claude processes it - useful for injecting git diffs, issue content, or other dynamic context.