Anatomy of the .claude/ folder: The Control Center for AI-Enhanced Projects

When working with AI coding assistants, organization is everything. A clean, structured approach to managing instructions, rules, and specialized agents can be the difference between a helpful partner and a confusing mess.

That's where the .claude/ folder comes in: it's the control center for your AI-enhanced project.

Here's a breakdown of how this folder is structured and what each part does.

The Root Level: High-Level Instructions

At the root of your project, you have two primary files:

• CLAUDE.md: These are the team-wide instructions. They should be committed to git so that every developer on the team has the same baseline for how to interact with the AI.
• CLAUDE.local.md: This file is for your personal overrides. It should be gitignored, allowing you to customize the AI's behavior without affecting the rest of the team.

The .claude/ Folder: The Control Center

Inside the .claude/ directory, the logic is divided into modular components.

1. Settings and Permissions

• settings.json: Contains shared permissions and configurations for the team (committed).
• settings.local.json: Personal permissions and localized configurations (gitignored).

This separation ensures that sensitive or personal permissions don't accidentally leak into the shared repository while still providing a robust baseline for everyone.

2. Custom Slash Commands

The commands/ directory allows you to define custom slash commands using markdown files. For example:

• review.md -> /project:review
• fix-issue.md -> /project:fix-issue
• deploy.md -> /project:deploy

These serve as shortcuts for complex tasks that you perform frequently, ensuring consistency in how the AI handles them.

3. Modular Instruction Files

The rules/ folder is where you store modular instruction files. Instead of one massive prompt, you can break it down into specialized files:

• code-style.md
• testing.md
• api-conventions.md

This makes your instructions easier to maintain and update.

4. Auto-Invoked Workflows

The skills/ directory contains auto-invoked workflows. These are specialized skills that the AI can call upon automatically when relevant. Each skill is contained in its own subdirectory with a SKILL.md file (e.g., security-review/SKILL.md).

5. Subagent Personas

For more complex projects, you can define isolated subagent personas in the agents/ directory. These are specialized versions of the AI that are tuned for specific tasks:

• code-reviewer.md
• security-auditor.md

Why This Matters

"Everything Claude needs to know about your project lives right here."

By consolidating all AI-related configuration and documentation into a single, standardized structure, you create a more predictable and powerful development environment. It allows the AI to understand the context of your project instantly, respect your team's conventions, and leverage specialized tools and agents exactly when needed.

If you are building complex systems with AI, the .claude/ folder isn't just a directory—it's your project's brain.