The Complete Guide to Claude Code Directory Structure

By Tyler Cyert

Understanding the Claude Code directory structure is essential if you're using Claude Code as your development assistant. The .claude/ directory is the configuration backbone of every Claude Code project — it tells the agent who it is, what it can do, and what guardrails to follow.

What Is the .claude/ Directory?

The .claude/ folder lives at the root of your project. It is Claude Code's equivalent of .vscode/ or .github/ — a dedicated configuration directory that defines how the AI agent operates within your codebase.

The Full Directory Structure

your-project/
├── .claude/
│   ├── agents/
│   │   ├── code-reviewer.md
│   │   └── test-writer.md
│   ├── skills/
│   │   └── deploy/
│   │       └── SKILL.md
│   ├── rules/
│   │   ├── code-style.md
│   │   └── security.md
│   ├── hooks/
│   │   └── format-on-save.sh
│   ├── settings.json
│   └── settings.local.json
├── CLAUDE.md
├── CLAUDE.local.md
└── .gitignore

Root Configuration Files

CLAUDE.md — The Project Instructions

CLAUDE.md sits at the project root and acts as the system prompt for your agent. Everything here gets loaded into context every session. Include your stack, build commands, architecture, and coding conventions.

For a deeper dive, see our complete guide to CLAUDE.md.

CLAUDE.local.md — Personal Overrides

Your personal preferences — verbosity, local paths, environment quirks. Gitignored, not shared with the team.

Inside .claude/

agents/ — Specialized Sub-Agents

Markdown files defining focused agent personas. Each file describes a role, its tools, and its scope. These work as both delegated subagents and agent team teammates.

skills/ — On-Demand Knowledge

Each skill lives in its own subdirectory with a SKILL.md file. Loaded via /slash commands — not every session. Use for procedures, templates, or reference material.

rules/ — Scoped Instructions

Markdown files with path-glob frontmatter. Only loaded when matching files are touched. Use to split a large CLAUDE.md into focused, file-type-specific pieces.

hooks/ — Lifecycle Automation

Scripts triggered by events: PreToolUse, PostToolUse, Stop, SessionStart, TeammateIdle, TaskCreated, TaskCompleted. Exit 0 to proceed, exit 2 to block.

settings.json — Project Settings

Tool permissions, model preferences, hooks configuration, and environment variables. Committed to git for the whole team.

settings.local.json — Personal Settings

Your local overrides. Gitignored.

File Reference

Project vs Global Configuration

Project-level (.claude/ in your repo) — shared with your team, committed to git. Defines how Claude Code behaves for this specific project.

Global (~/.claude/ in your home directory) — personal defaults that apply to every project. Can contain agents, skills, and rules that are available everywhere.

Project-level takes precedence over global.

Agent Teams

Agent teams let Claude Code coordinate multiple sub-agents working in parallel. Enable with the experimental flag in settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Your agent definitions in .claude/agents/ become the roles that teams reference when spawning teammates.

Scaffolding with DotBox

Setting up this structure by hand means creating folders, writing markdown in the right format, and configuring JSON schemas correctly. DotBox scaffolds the complete directory structure visually — define agents, skills, rules, and hooks through a guided interface, then export as a zip or install with a single command.

Getting Started

1. Create CLAUDE.md at your project root
2. Create .claude/ with at least settings.json
3. Add rules for hard constraints
4. Define agents for specialized roles
5. Add hooks for automation

Start with CLAUDE.md and settings.json, then layer in the rest as your workflow matures.