AI Topia Logo
AI Topia
Claude CodeReference

Anatomy of the .claude/ Folder

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

Two config locations.

your-project/.claude/ for team config (committed to git). ~/.claude/ for personal config (never committed). Both load on every session.

1Project Structure

your-project/
├─CLAUDE.mdteam instructions, in git
├─CLAUDE.local.mdpersonal overrides, gitignored
├─.claude/the control center
├─settings.jsonpermissions + config
├─settings.local.jsonpersonal, gitignored
├─commands/custom slash commands
├─review.md/project:review
├─fix-issue.md/project:fix-issue
└─deploy.md/project:deploy
├─rules/modular instruction files
├─code-style.md
├─testing.md
└─api-conventions.md
├─skills/auto-invoked workflows
├─security-review/
└─SKILL.md
├─deploy/
└─SKILL.md
├─agents/sub-agent personas
├─code-reviewer.md
└─security-auditor.md

CLAUDE.md

Write

  • Build commands
  • Architecture notes
  • Gotchas & conventions

Don't write

  • Linter configs
  • Long docs
  • Theory paragraphs
Keep it under 200 lines. Longer = worse instruction-following.

rules/

Split your crowded CLAUDE.md into focused files. Each file = one concern.

code-style.mdtesting.mdapi-conventions.mdsecurity.md

Use paths: src/api/**/*.ts to only load when Claude works in matching folders.

skills/

AutoTriggered when context matches
BundledIncludes scripts & references

agents/

IsolatedOwn context window
RestrictedLimit tools intentionally

2Hooks - Deterministic Control

PreToolUse

Block dangerous commands before they run

PostToolUse

Auto-format files after every edit

Stop

Ensure tests pass before completing

exit 0 = success
exit 1 = non-blocking error
exit 2 = BLOCK + send to Claude

exit 1 for security = most common mistake!

3settings.json

Allow

Bash(npm run *)
Read
Write
Edit

Deny

Bash(rm -rf *)
Read(.env)

Not in either list? Claude asks first.

4Precedence

On conflict, the more specific layer overrides the general one.

HIGHEST.claude/rules/path-scoped overrides
HIGHCLAUDE.local.mdpersonal, gitignored
MIDCLAUDE.mdproject / team, in git
BASE~/.claude/CLAUDE.mdglobal fallback defaults

5Get Started in 5 Steps

1

Run /init and edit CLAUDE.md down to essentials

2

Add settings.json with allow/deny rules

3

Create 1-2 custom commands/ for common workflows

4

Split crowded CLAUDE.md into rules/ files

5

Add ~/.claude/CLAUDE.md for personal preferences

CLAUDE.md is your highest-leverage file. Get that right first. Everything else is optimization.

AI Topia

Want Claude to work like a senior teammate?

Get the full setup walkthrough and more Claude Code resources.

Browse All Resources