u/OilPsychological9307

.claude/ is the configuration folder Claude Code reads when you run it inside a project.

It sits at the root of your repo and holds everything that shapes how Claude behaves in that codebase. Instructions, permissions, automation scripts, reusable prompts, custom skills, specialized agents.

Here's the layout I use.

your-project/
├── CLAUDE.md
├── CLAUDE.local.md
└── .claude/
    ├── settings.json
    ├── rules/
    ├── hooks/
    ├── commands/
    ├── skills/
    └── agents/

Most projects don't need all of it on day one.

Top level does two jobs

CLAUDE.md covers how the project works. Stack, architecture, conventions, the commands that matter day to day.

settings.json covers what Claude is allowed to do. Permissions, hooks, project-wide behavior.

A real CLAUDE.md for a FastAPI service:

# Project: Customer Insights API

## Stack
- FastAPI
- PostgreSQL
- SQLAlchemy
- Pytest

## Structure
- `app/api/` contains route definitions
- `app/services/` contains business logic
- `app/models/` contains ORM models
- `app/schemas/` contains request and response schemas

## Commands
- `pytest` runs the test suite
- `alembic upgrade head` applies migrations
- `ruff check .` runs linting
- `ruff format .` formats the code

## Conventions
- Validate all request bodies with Pydantic schemas
- Keep route handlers thin; business logic belongs in services
- Do not expose internal exception details in API responses

CLAUDE.md vs rules/

Dumping everything into CLAUDE.md is the fastest way to make .claude/ useless. Frontend conventions next to backend validation next to data pipeline notes. More context, worse context.

Split it:

• CLAUDE.md for global guidance
• rules/ for specialized guidance

​

.claude/
└── rules/
    ├── frontend.md
    ├── backend-api.md
    ├── testing.md
    └── data-pipelines.md

A backend-api.md:

# Backend API Rules

- Every new endpoint must include request and response schemas
- Use dependency injection for database sessions
- Return paginated results for collection endpoints
- Log external API failures with the shared logger
- Prefer service-layer functions over logic inside route files

Move things into rules/ when CLAUDE.md gets crowded or when different parts of the repo need different standards.

hooks/ run, commands/ get reused

Hooks are scripts that fire automatically. They block risky actions, validate output, or enforce a workflow step. A formatter hook:

#!/usr/bin/env bash
jq -r '.tool_input.file_path' | xargs ruff format

Commands are reusable prompts. The work you run every week.

# review-pr

Review the current changes with a focus on:
- correctness
- missing edge cases
- API contract changes
- test coverage gaps

Summarize:
1. critical issues
2. medium-risk issues
3. suggested improvements

One canonical version beats five drifting copies. Names like format-edits.sh and block-prod-commands.sh explain themselves. helper.sh doesn't.

skills/ and agents/ are for later

A skill is a packaged workflow with supporting files. Release prep involves checking changes, reviewing version notes, drafting a summary, confirming migrations. More than a one-shot prompt.

.claude/
└── skills/
    └── release-prep/
        ├── SKILL.md
        └── release-template.md

commands/ for lightweight tasks, skills/ for workflows with depth.

Agents are specialized roles. One file, one purpose.

.claude/
└── agents/
    ├── code-reviewer.md
    └── security-auditor.md

Skip both folders if commands already do the job.

Team config vs personal config

The biggest source of rot is mixing the two. Shared files reflect the project. Personal files reflect the developer.

your-project/
├── CLAUDE.md
├── CLAUDE.local.md
└── .claude/
    ├── settings.json
    ├── settings.local.json
    └── ...

~/.claude/
├── CLAUDE.md
├── settings.json
├── skills/
└── agents/

If it helps the whole team work consistently, it ships in the repo. If it reflects one person's workflow, it lives in ~/.claude/ or in *.local files that aren't committed.

Grow the folder in order

Start with CLAUDE.md and settings.json. Enough for most repos.

Add rules/ when one instruction file stops scaling. Add hooks/ when you need automation. Add commands/ when prompts get repetitive. Add skills/ when workflows deepen. Add agents/ when specialization improves output.