Understanding the .claude/ folder structure for Claude Code configuration

Project and global configuration folders

There are two .claude directories: one in your project root for team configuration that gets committed to git, and another in your home directory (~/.claude/) for personal preferences and machine-local state like session history.

CLAUDE.md: The instruction manual

CLAUDE.md is loaded into Claude's system prompt at the start of each session and followed throughout the conversation. You can have CLAUDE.md at project root, in ~/.claude/ for global preferences, or in subdirectories for folder-specific rules.

Effective CLAUDE.md content includes:

• Build, test, and lint commands (npm run test, make build, etc.)
• Key architectural decisions
• Non-obvious gotchas
• Import conventions, naming patterns, error handling styles
• File and folder structure for main modules

Keep CLAUDE.md under 200 lines. Files longer than that start eating too much context and Claude's instruction adherence drops.

Example CLAUDE.md structure

# Project: Acme API

Commands
npm run dev # Start dev server
npm run test # Run tests (Jest)
npm run lint # ESLint + Prettier check
npm run build # Production build

Architecture

• Express REST API, Node 20
• PostgreSQL via Prisma ORM
• All handlers live in src/handlers/
• Shared types in src/types/

Conventions

• Use zod for request validation in every handler
• Return shape is always { data, error }
• Never expose stack traces to the client
• Use the logger module, not console.log

Watch out for

• Tests use a real local DB, not mocks. Run npm run db:test:reset first
• Strict TypeScript: no unused imports, ever

  Personal overrides with CLAUDE.local.md

  Create CLAUDE.local.md in your project root for personal preferences that don't apply to the whole team. Claude reads it alongside the main CLAUDE.md, and it's automatically gitignored so personal tweaks never land in the repository.

  Modular instructions with rules/ folder

  For larger teams, the rules/ folder provides modular instructions that scale better than a single large CLAUDE.md file.

  📖 Read the full source: HN AI Agents