Mastering Claude Code Configs: `CLAUDE.md` vs `.claude/rules/`

When configuring Claude Code (or Claude-driven AI coding assistants) in your projects, structuring your instructions efficiently is key to getting accurate code generation while keeping token consumption low. Understanding when to use a single CLAUDE.md versus modular .claude/rules/ files will help keep your AI assistant sharp, focused, and predictable. The Core Hierarchy & Scope Claude Code looks for configurations across multiple levels: ├── ~/.claude/ # User / Global level (applies to all your projects) └── project-root/ ├── CLAUDE.md # Global project level (loaded into every session) ├── .claude/rules/ # Modular & scoped rules (loaded selectively) └── sub-app/ └── CLAUDE.md # Sub-directory / Monorepo scope CLAUDE.md (The Global Cheat Sheet)Think of CLAUDE.md as the main ReadMe for the AI. It provides high-level context and essential project memory. When to use CLAUDE.md:Common CLI Commands: Build, test, lint, and run scripts (npm test, docker compose up). Core Architecture: Tech stack summary, overall folder structure, and design principles. Global Rules: Non-negotiable guidelines that apply project-wide (e.g., "Strict TypeScript, no any"). Project Context: E-Commerce Web App Build & Test Commands Build: npm run build Test single file: npx jest src/components/Button.test.tsx Lint: npm run lint High-Level Guidelines All UI components must use React 19 functional syntax. Never hardcode secrets or environment variables. .claude/rules/ (Modular & Path-Scoped Rules)As projects grow, packing every guideline into CLAUDE.md bloats the prompt context and reduces overall compliance. The .claude/rules/ directory lets you create modular, topic-specific, or path-scoped rules (in .yml or .md). When to use .claude/rules/:Path-Specific Rules (globs): Guidelines that apply only to certain files (e.g., API routes vs. React components). Domain Separation: Splitting rules into dedicated files (testing.yml, security.yml, db-migrations.yml). Token Optimization: Prevent loading backen