# Mastering Claude Code Configs: `CLAUDE.md` vs `.claude/rules/` > Source: > Published: 2026-07-31 03:36:07+00:00 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.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 backend migration rules into context when editing CSS/React components. # .claude/rules/api-routes.yml name: API & Endpoint Rules globs: - "src/api/* */*.ts" - "src/controllers/* */*.ts" rules: - id: input-validation description: Validate all incoming payloads with Zod schemas. - id: error-handling description: Never expose internal DB error traces in API responses. Pro-Tips & Best Practices - **Keep CLAUDE.md Concise**: Aim for under 100–150 lines. Move specific domain details into .claude/rules/. - **Combine Both Strategies**: Put Commands & Core Pillars in CLAUDE.md[cite: 1].Put Framework/Directory Specifics in .claude/rules/[cite: 1]. - **Use Sub-Directory CLAUDE.md in Monorepos**: Place localized CLAUDE.md files inside specific packages/apps (e.g., apps/web/CLAUDE.md and services/auth/CLAUDE.md) so sub-teams maintain isolated contexts[cite: 1].