Anatomy of the .claude/ Folder

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.